Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks
Sign in →

Retrieve an invoice's line items

When retrieving an invoice, you’ll get a lines property containing the total count of line items and the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

Parameters

No parameters.

More parameters

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

Returns a list of line_item objects.

GET /v1/invoices/:id/lines
curl https://api.stripe.com/v1/invoices/in_1NpHok2eZvKYlo2CyeiBref0/lines \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
Response
{
  "object": "list",
  "url": "/v1/invoices/in_1NpHiG2eZvKYlo2CZV0ZkEBT/lines",
  "has_more": false,
  "data": [
    {
      "id": "il_tmp_1NpHiK2eZvKYlo2C9NdV8VrI",
      "object": "line_item",
      "amount": 129999,
      "amount_excluding_tax": 129999,
      "currency": "usd",
      "description": "My First Invoice Item (created for API docs)",
      "discount_amounts": [],
      "discountable": true,
      "discounts": [],
      "invoice_item": "ii_1NpHiK2eZvKYlo2C9NdV8VrI",
      "livemode": false,
      "metadata": {},
      "period": {
        "end": 1694467932,
        "start": 1694467932
      },
      "price": {
        "id": "price_1NpEIa2eZvKYlo2CXcy5DRPA",
        "object": "price",
        "active": true,
        "billing_scheme": "per_unit",
        "created": 1694454804,
        "currency": "usd",
        "custom_unit_amount": null,
        "livemode": false,
        "lookup_key": null,
        "metadata": {},
        "nickname": null,
        "product": "prod_OcTFTbV7qh48bd",
        "recurring": null,
        "tax_behavior": "unspecified",
        "tiers_mode": null,
        "transform_quantity": null,
        "type": "one_time",
        "unit_amount": 129999,
        "unit_amount_decimal": "129999"
      },
      "proration": false,
      "proration_details": {
        "credited_items": null
      },
      "quantity": 1,
      "subscription": null,
      "tax_amounts": [],
      "tax_rates": [],
      "type": "invoiceitem",
      "unit_amount_excluding_tax": "129999"
    }
  ]
}

Retrieve an upcoming invoice's line items

When retrieving an upcoming invoice, you’ll get a lines property containing the total count of line items and the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

Parameters

  • customerstring

    The identifier of the customer whose upcoming invoice you’d like to retrieve. If automatic_tax is enabled then one of customer, customer_details, subscription, or schedule must be set.

  • subscriptionstring

    The identifier of the subscription for which you’d like to retrieve the upcoming invoice. If not provided, but a subscription_items is provided, you will preview creating a subscription with those items. If neither subscription nor subscription_items is provided, you will retrieve the next upcoming invoice from among the customer’s subscriptions.

More parameters

  • automatic_taxobject

  • couponstringDeprecated

  • currencyenum

  • customer_detailsobject

  • discountsarray of objects

  • ending_beforestring

  • invoice_itemsarray of objects

  • issuerobjectConnect only

  • limitinteger

  • on_behalf_ofstringConnect only

  • schedulestring

  • schedule_detailsobject

  • starting_afterstring

  • subscription_billing_cycle_anchorstring | timestampDeprecated

  • subscription_cancel_attimestampDeprecated

  • subscription_cancel_at_period_endbooleanDeprecated

  • subscription_cancel_nowbooleanDeprecated

  • subscription_default_tax_ratesarray of stringsDeprecated

  • subscription_detailsobject

  • subscription_itemsarray of objectsDeprecated

  • subscription_proration_behaviorenumDeprecated

  • subscription_proration_datetimestampDeprecated

  • subscription_resume_atstringDeprecated

  • subscription_start_datetimestampDeprecated

  • subscription_trial_endstring | timestampDeprecated

Returns

Returns a list of line_item objects.

GET /v1/invoices/upcoming/lines
curl -G https://api.stripe.com/v1/invoices/upcoming/lines \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d customer=cus_OgeRVYRv3sHroi
Response
{
  "object": "list",
  "url": "/v1/invoices/upcoming/lines",
  "has_more": false,
  "data": [
    {
      "id": "il_tmp_1NtH5qBHO5VeT9SUzhbifVXt",
      "object": "line_item",
      "amount": 1000,
      "amount_excluding_tax": 1000,
      "currency": "usd",
      "description": "My First Invoice Item (created for API docs)",
      "discount_amounts": [],
      "discountable": true,
      "discounts": [],
      "invoice_item": "ii_1NtH5qBHO5VeT9SUzhbifVXt",
      "livemode": false,
      "metadata": {},
      "period": {
        "end": 1695418858,
        "start": 1695418858
      },
      "price": {
        "id": "price_1NrpbEBHO5VeT9SUHp6xMwKA",
        "object": "price",
        "active": true,
        "billing_scheme": "per_unit",
        "created": 1695074844,
        "currency": "usd",
        "custom_unit_amount": null,
        "livemode": false,
        "lookup_key": null,
        "metadata": {},
        "nickname": null,
        "product": "prod_Of9vdHHGRaGOio",
        "recurring": null,
        "tax_behavior": "unspecified",
        "tiers_mode": null,
        "transform_quantity": null,
        "type": "one_time",
        "unit_amount": 1000,
        "unit_amount_decimal": "1000"
      },
      "proration": false,
      "proration_details": {
        "credited_items": null
      },
      "quantity": 1,
      "subscription": null,
      "tax_amounts": [],
      "tax_rates": [],
      "type": "invoiceitem",
      "unit_amount_excluding_tax": "1000"
    }
    {...}
    {...}
  ],
}

List all invoices

You can list all invoices, or list the invoices for a specific customer. The invoices are returned sorted by creation date, with the most recently created invoices appearing first.

Parameters

  • customerstring

    Only return invoices for the customer specified by this customer ID.

  • statusenum

    The status of the invoice, one of draft, open, paid, uncollectible, or void. Learn more

  • subscriptionstring

    Only return invoices for the subscription specified by this subscription ID.

More parameters

  • collection_methodenum

  • createdobject

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

A dictionary with a data property that contains an array invoice attachments,

GET /v1/invoices
curl -G https://api.stripe.com/v1/invoices \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d limit=3
Response
{
  "object": "list",
  "url": "/v1/invoices",
  "has_more": false,
  "data": [
    {
      "id": "in_1MtHbELkdIwHu7ixl4OzzPMv",
      "object": "invoice",
      "account_country": "US",
      "account_name": "Stripe Docs",
      "account_tax_ids": null,
      "amount_due": 0,
      "amount_paid": 0,
      "amount_remaining": 0,
      "amount_shipping": 0,
      "application": null,
      "application_fee_amount": null,
      "attempt_count": 0,
      "attempted": false,
      "auto_advance": false,
      "automatic_tax": {
        "enabled": false,
        "liability": null,
        "status": null
      },
      "billing_reason": "manual",
      "charge": null,
      "collection_method": "charge_automatically",
      "created": 1680644467,
      "currency": "usd",
      "custom_fields": null,
      "customer": "cus_NeZwdNtLEOXuvB",
      "customer_address": null,
      "customer_email": "jennyrosen@example.com",
      "customer_name": "Jenny Rosen",
      "customer_phone": null,
      "customer_shipping": null,
      "customer_tax_exempt": "none",
      "customer_tax_ids": [],
      "default_payment_method": null,
      "default_source": null,
      "default_tax_rates": [],
      "description": null,
      "discount": null,
      "discounts": [],
      "due_date": null,
      "ending_balance": null,
      "footer": null,
      "from_invoice": null,
      "hosted_invoice_url": null,
      "invoice_pdf": null,
      "issuer": {
        "type": "self"
      },
      "last_finalization_error": null,
      "latest_revision": null,
      "lines": {
        "object": "list",
        "data": [],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv/lines"
      },
      "livemode": false,
      "metadata": {},
      "next_payment_attempt": null,
      "number": null,
      "on_behalf_of": null,
      "paid": false,
      "paid_out_of_band": false,
      "payment_intent": null,
      "payment_settings": {
        "default_mandate": null,
        "payment_method_options": null,
        "payment_method_types": null
      },
      "period_end": 1680644467,
      "period_start": 1680644467,
      "post_payment_credit_notes_amount": 0,
      "pre_payment_credit_notes_amount": 0,
      "quote": null,
      "receipt_number": null,
      "rendering_options": null,
      "shipping_cost": null,
      "shipping_details": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "status": "draft",
      "status_transitions": {
        "finalized_at": null,
        "marked_uncollectible_at": null,
        "paid_at": null,
        "voided_at": null
      },
      "subscription": null,
      "subtotal": 0,
      "subtotal_excluding_tax": 0,
      "tax": null,
      "test_clock": null,
      "total": 0,
      "total_discount_amounts": [],
      "total_excluding_tax": 0,
      "total_tax_amounts": [],
      "transfer_data": null,
      "webhooks_delivered_at": 1680644467
    }
    {...}
    {...}
  ],
}

Delete a draft invoice

Permanently deletes a one-off invoice draft. This cannot be undone. Attempts to delete invoices that are no longer in a draft state will fail; once an invoice has been finalized or if an invoice is for a subscription, it must be voided.

Parameters

No parameters.

Returns

A successfully deleted invoice. Otherwise, this call raises an error, such as if the invoice has already been deleted.

DELETE /v1/invoices/:id
curl -X DELETE https://api.stripe.com/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
Response
{
  "id": "in_1MtHbELkdIwHu7ixl4OzzPMv",
  "object": "invoice",
  "deleted": true
}

Finalize an invoice

Stripe automatically finalizes drafts before sending and attempting payment on invoices. However, if you’d like to finalize a draft invoice manually, you can do so using this method.

Parameters

  • auto_advanceboolean

    Controls whether Stripe performs automatic collection of the invoice. If false, the invoice’s state doesn’t automatically advance without an explicit action.

Returns

Returns an invoice object with status=open.

POST /v1/invoices/:id/finalize
curl -X POST https://api.stripe.com/v1/invoices/in_1MtGmCLkdIwHu7ix6PgS6g8S/finalize \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
Response
{
  "id": "in_1MtGmCLkdIwHu7ix6PgS6g8S",
  "object": "invoice",
  "account_country": "US",
  "account_name": "Stripe Docs",
  "account_tax_ids": null,
  "amount_due": 0,
  "amount_paid": 0,
  "amount_remaining": 0,
  "amount_shipping": 0,
  "application": null,
  "application_fee_amount": null,
  "attempt_count": 0,
  "attempted": true,
  "auto_advance": false,
  "automatic_tax": {
    "enabled": false,
    "liability": null,
    "status": null
  },
  "billing_reason": "manual",
  "charge": null,
  "collection_method": "send_invoice",
  "created": 1680641304,
  "currency": "usd",
  "custom_fields": null,
  "customer": "cus_NeZw0zvTyquTfF",
  "customer_address": null,
  "customer_email": "jennyrosen@example.com",
  "customer_name": "Jenny Rosen",
  "customer_phone": null,
  "customer_shipping": null,
  "customer_tax_exempt": "none",
  "customer_tax_ids": [],
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discount": null,
  "discounts": [],
  "due_date": 1681246104,
  "ending_balance": 0,
  "footer": null,
  "from_invoice": null,
  "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1M2JTkLkdIwHu7ix/test_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9OZVp3dVBYNnF0dGlvdXRubGVjSXVOOWhiVWpmUktPLDcxMTgyMTA10200x7P2wMSm?s=ap",
  "invoice_pdf": "https://pay.stripe.com/invoice/acct_1M2JTkLkdIwHu7ix/test_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9OZVp3dVBYNnF0dGlvdXRubGVjSXVOOWhiVWpmUktPLDcxMTgyMTA10200x7P2wMSm/pdf?s=ap",
  "issuer": {
    "type": "self"
  },
  "last_finalization_error": null,
  "latest_revision": null,
  "lines": {
    "object": "list",
    "data": [],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/invoices/in_1MtGmCLkdIwHu7ix6PgS6g8S/lines"
  },
  "livemode": false,
  "metadata": {},
  "next_payment_attempt": null,
  "number": "9545A614-0001",
  "on_behalf_of": null,
  "paid": true,
  "paid_out_of_band": false,
  "payment_intent": null,
  "payment_settings": {
    "default_mandate": null,
    "payment_method_options": null,
    "payment_method_types": null
  },
  "period_end": 1680641304,
  "period_start": 1680641304,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "quote": null,
  "receipt_number": null,
  "rendering_options": null,
  "shipping_cost": null,
  "shipping_details": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "status": "paid",
  "status_transitions": {
    "finalized_at": 1680641304,
    "marked_uncollectible_at": null,
    "paid_at": 1680641304,
    "voided_at": null
  },
  "subscription": null,
  "subtotal": 0,
  "subtotal_excluding_tax": 0,
  "tax": null,
  "test_clock": null,
  "total": 0,
  "total_discount_amounts": [],
  "total_excluding_tax": 0,
  "total_tax_amounts": [],
  "transfer_data": null,
  "webhooks_delivered_at": 1680641304
}
Stripe Shell
Test mode

Welcome to the Stripe Shell!

Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your
Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe
resources in test mode.

- View supported Stripe commands: 
- Find webhook events: 
- Listen for webhook events: 
- Call Stripe APIs: stripe [api resource] [operation] (e.g., )
The Stripe Shell is best experienced on desktop.
$