The Invoice object
Attributes
- idstring
Unique identifier for the object. This property is always present unless the invoice is an upcoming invoice. See Retrieve an upcoming invoice for more details.
- 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. - chargenullable stringExpandable
ID of the latest charge generated for this invoice, if any.
- collection_
methodenum Either
charge_automatically
, orsend_invoice
. When charging automatically, Stripe will attempt to pay this invoice using the default source attached to the customer. When sending an invoice, Stripe will email this invoice to the customer with payment instructions.Possible enum valuescharge_automatically
Attempt payment using the default source attached to the customer.
send_invoice
Email payment instructions to the customer.
- currencyenum
Three-letter ISO currency code, in lowercase. Must be a supported currency.
- customerstringExpandable
The ID of the customer who will be billed.
- descriptionnullable string
An arbitrary string attached to the object. Often useful for displaying to users. Referenced as ‘memo’ in the Dashboard.
- hosted_
invoice_ urlnullable string The URL for the hosted invoice page, which allows customers to view and pay an invoice. If the invoice has not been finalized yet, this will be null.
- linesassociative array
The individual line items that make up the invoice.
lines
is sorted as follows: (1) pending invoice items (including prorations) in reverse chronological order, (2) subscription items in reverse chronological order, and (3) invoice items added after invoice creation in chronological order. - metadatanullable associative array
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
- payment_
intentnullable stringExpandable The PaymentIntent associated with this invoice. The PaymentIntent is generated when the invoice is finalized, and can then be used to pay the invoice. Note that voiding an invoice will cancel the PaymentIntent.
- period_
endtimestamp End of the usage period during which invoice items were added to this invoice. This looks back one period for a subscription invoice. Use the line item period to get the service period for each price.
- period_
starttimestamp Start of the usage period during which invoice items were added to this invoice. This looks back one period for a subscription invoice. Use the line item period to get the service period for each price.
- statusnullable enum
The status of the invoice, one of
draft
,open
,paid
,uncollectible
, orvoid
. Learn more - subscriptionnullable stringExpandable
The subscription that this invoice was prepared for, if any.
- totalinteger
Total after discounts and taxes.
More attributes
- objectstring
- account_
countrynullable string - account_
namenullable string - account_
tax_ idsnullable array of stringsExpandable - amount_
dueinteger - amount_
paidinteger - amount_
remaininginteger - amount_
shippinginteger - applicationnullable stringExpandableConnect only
- application_
fee_ amountnullable integerConnect only - attempt_
countinteger - attemptedboolean
- automatic_
taxassociative array - billing_
reasonnullable enum - createdtimestamp
- custom_
fieldsnullable array of associative arrays - customer_
addressnullable associative array - customer_
emailnullable string - customer_
namenullable string - customer_
phonenullable string - customer_
shippingnullable associative array - customer_
tax_ exemptnullable enum - customer_
tax_ idsnullable array of associative arrays - default_
payment_ methodnullable stringExpandable - default_
sourcenullable stringExpandable - default_
tax_ ratesarray of associative arrays - discountnullable associative arrayDeprecated
- discountsarray of stringsExpandable
- due_
datenullable timestamp - effective_
atnullable timestamp - ending_
balancenullable integer - footernullable string
- from_
invoicenullable associative array - invoice_
pdfnullable string - issuerassociative arrayConnect only
- last_
finalization_ errornullable associative array - latest_
revisionnullable stringExpandable - livemodeboolean
- next_
payment_ attemptnullable timestamp - numbernullable string
- on_
behalf_ ofnullable stringExpandableConnect only - paidboolean
- paid_
out_ of_ bandboolean - payment_
settingsassociative array - post_
payment_ credit_ notes_ amountinteger - pre_
payment_ credit_ notes_ amountinteger - quotenullable stringExpandable
- receipt_
numbernullable string - renderingnullable associative array
- shipping_
costnullable associative array - shipping_
detailsnullable associative array - starting_
balanceinteger - statement_
descriptornullable string - status_
transitionsassociative array - subscription_
detailsnullable associative array - subscription_
proration_ datenullable integer - subtotalinteger
- subtotal_
excluding_ taxnullable integer - taxnullable integer
- test_
clocknullable stringExpandable - threshold_
reasonnullable associative array - total_
discount_ amountsnullable array of associative arrays - total_
excluding_ taxnullable integer - total_
tax_ amountsarray of associative arrays - transfer_
datanullable associative arrayConnect only - webhooks_
delivered_ atnullable timestamp
{
"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
}
The Invoice Line Item object
Attributes
- idstring
Unique identifier for the object.
- amountinteger
The amount, in cents.
- currencyenum
Three-letter ISO currency code, in lowercase. Must be a supported currency.
- descriptionnullable string
An arbitrary string attached to the object. Often useful for displaying to users.
- invoicenullable string
The ID of the invoice that contains this line item.
- metadataassociative array
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Note that for line items with
type=subscription
,metadata
reflects the current metadata from the subscription associated with the line item, unless the invoice line was directly updated with different metadata after creation. - periodassociative array
The period this
line_item
covers. For subscription line items, this is the subscription period. For prorations, this starts when the proration was calculated, and ends at the period end of the subscription. For invoice items, this is the time at which the invoice item was created or the period of the item. If you have Stripe Revenue Recognition enabled, the period will be used to recognize and defer revenue. See the Revenue Recognition documentation for details. - pricenullable associative array
The price of the line item.
- prorationboolean
Whether this is a proration.
- quantitynullable integer
The quantity of the subscription, if the line item is a subscription or a proration.
- typeenum
A string identifying the type of the source of this line item, either an
invoiceitem
or asubscription
.Possible enum valuesinvoiceitem
subscription
More attributes
- objectstring
- amount_
excluding_ taxnullable integer - discount_
amountsnullable array of associative arrays - discountableboolean
- discountsarray of stringsExpandable
- invoice_
itemnullable stringExpandable - livemodeboolean
- proration_
detailsnullable associative array - subscriptionnullable stringExpandable
- subscription_
itemnullable stringExpandable - tax_
amountsarray of associative arrays - tax_
ratesarray of associative arrays - unit_
amount_ excluding_ taxnullable decimal string
{
"id": "il_tmp_1Nzo1ZGgdF1VjufLzD1UUn9R",
"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_1Nzo1ZGgdF1VjufLzD1UUn9R",
"livemode": false,
"metadata": {},
"period": {
"end": 1696975413,
"start": 1696975413
},
"price": {
"id": "price_1NzlYfGgdF1VjufL0cVjLJVI",
"object": "price",
"active": true,
"billing_scheme": "per_unit",
"created": 1696965933,
"currency": "usd",
"custom_unit_amount": null,
"livemode": false,
"lookup_key": null,
"metadata": {},
"nickname": null,
"product": "prod_OnMHDH6VBmYlTr",
"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"
}
Create an invoice
This endpoint creates a draft invoice for a given customer. The invoice remains a draft until you finalize the invoice, which allows you to pay or send the invoice to your customers.
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. - collection_
methodenum Either
charge_automatically
, orsend_invoice
. When charging automatically, Stripe will attempt to pay this invoice using the default source attached to the customer. When sending an invoice, Stripe will email this invoice to the customer with payment instructions. Defaults tocharge_automatically
.Possible enum valuescharge_automatically
send_invoice
- customerstring
The ID of the customer who will be billed.
- descriptionstring
An arbitrary string attached to the object. Often useful for displaying to users. Referenced as ‘memo’ in the Dashboard.
- metadataassociative array
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to
metadata
. - subscriptionstring
The ID of the subscription to invoice, if any. If set, the created invoice will only include pending invoice items for that subscription. The subscription’s billing cycle and regular subscription events won’t be affected.
More parameters
- account_
tax_ idsarray of strings - application_
fee_ amountintegerConnect only - automatic_
taxassociative array - currencyenum
- custom_
fieldsarray of associative arrays - days_
until_ dueinteger - default_
payment_ methodstring - default_
sourcestring - default_
tax_ ratesarray of strings - discountsarray of associative arrays
- due_
datetimestamp - effective_
attimestamp - footerstring
- from_
invoiceassociative array - issuerassociative arrayConnect only
- numberstring
- on_
behalf_ ofstringConnect only - payment_
settingsassociative array - pending_
invoice_ items_ behaviorenum - renderingassociative array
- shipping_
costassociative array - shipping_
detailsassociative array - statement_
descriptorstring - transfer_
dataassociative arrayConnect only
Returns
Returns the invoice object. Throws an error if the customer ID provided is invalid.
{
"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
}
Create a preview invoice
At any time, you can preview the upcoming invoice for a customer. This will show you all the charges that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discounts that are applicable to the invoice.
Note that when you are viewing an upcoming invoice, you are simply viewing a preview – the invoice has not yet been created. As such, the upcoming invoice will not show up in invoice listing calls, and you cannot use the API to pay or edit the invoice. If you want to change the amount that your customer will be billed, you can add, remove, or update pending invoice items, or update the customer’s discount.
You can preview the effects of updating a subscription, including a preview of what proration will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass the subscription_details.proration_date
parameter when doing the actual subscription update. The recommended way to get only the prorations being previewed is to consider only proration line items where period[start]
is equal to the subscription_details.proration_date
value passed in the request.
Note: Currency conversion calculations use the latest exchange rates. Exchange rates may vary between the time of the preview and the time of the actual invoice creation. Learn more
Parameters
- customerstring
The identifier of the customer whose upcoming invoice you’d like to retrieve. If
automatic_tax
is enabled then one ofcustomer
,customer_details
,subscription
, orschedule
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 neithersubscription
norsubscription_items
is provided, you will retrieve the next upcoming invoice from among the customer’s subscriptions.
More parameters
- automatic_
taxassociative array - couponstringDeprecated
- currencyenum
- customer_
detailsassociative array - discountsarray of associative arrays
- invoice_
itemsarray of associative arrays - issuerassociative arrayConnect only
- on_
behalf_ ofstringConnect only - preview_
modeenum - schedulestring
- schedule_
detailsassociative array - subscription_
detailsassociative array
Returns
Returns an invoice if valid customer information is provided. Throws an error otherwise.
{
"id": "upcoming_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,
"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,
"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
}
Update an invoice
Draft invoices are fully editable. Once an invoice is finalized, monetary values, as well as collection_method
, become uneditable.
If you would like to stop the Stripe Billing engine from automatically finalizing, reattempting payments on, sending reminders for, or automatically reconciling invoices, pass auto_advance=false
.
Parameters
- auto_
advanceboolean Controls whether Stripe performs automatic collection of the invoice.
- collection_
methodenum Either
charge_automatically
orsend_invoice
. This field can be updated only ondraft
invoices.Possible enum valuescharge_automatically
send_invoice
- descriptionstring
An arbitrary string attached to the object. Often useful for displaying to users. Referenced as ‘memo’ in the Dashboard.
- metadataassociative array
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to
metadata
.
More parameters
- account_
tax_ idsarray of strings - application_
fee_ amountintegerConnect only - automatic_
taxassociative array - custom_
fieldsarray of associative arrays - days_
until_ dueinteger - default_
payment_ methodstring - default_
sourcestring - default_
tax_ ratesarray of strings - discountsarray of associative arrays
- due_
datetimestamp - effective_
attimestamp - footerstring
- issuerassociative arrayConnect only
- numberstring
- on_
behalf_ ofstringConnect only - payment_
settingsassociative array - renderingassociative array
- shipping_
costassociative array - shipping_
detailsassociative array - statement_
descriptorstring - transfer_
dataassociative arrayConnect only
Returns
Returns the invoice object.
{
"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": {
"order_id": "6735"
},
"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
}