Draft invoices are fully editable. Once an invoice is finalized, monetary values, as well as collection_, 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_.
Parameters
- auto_
advanceboolean Controls whether Stripe performs automatic collection of the invoice.
- automatic_
taxobject Settings for automatic tax lookup for this invoice.
- collection_
methodenum Either
charge_orautomatically send_. This field can be updated only oninvoice draftinvoices.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.
- metadataobject
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 - automatically_
finalizes_ attimestamp - custom_
fieldsarray of objects - days_
until_ dueinteger - default_
payment_ methodstring - default_
sourcestring - default_
tax_ ratesarray of strings - discountsarray of objects
- due_
datetimestamp - effective_
attimestamp - footerstring
- issuerobjectConnect only
- numberstring
- on_
behalf_ ofstringConnect only - payment_
settingsobject - renderingobject
- shipping_
costobject - shipping_
detailsobject - statement_
descriptorstring - transfer_
dataobjectConnect 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_overpaid": 0, "amount_remaining": 0, "amount_shipping": 0, "application": null, "attempt_count": 0, "attempted": false, "auto_advance": false, "automatic_tax": { "enabled": false, "liability": null, "status": null }, "billing_reason": "manual", "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, "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, "parent": null, "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, "receipt_number": 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 }, "subtotal": 0, "subtotal_excluding_tax": 0, "test_clock": null, "total": 0, "total_discount_amounts": [], "total_excluding_tax": 0, "total_taxes": [], "webhooks_delivered_at": 1680644467}Retrieves the invoice with the given ID.
Parameters
No parameters.
Returns
Returns an invoice object if a valid invoice ID was provided. Raises an error otherwise.
The invoice object contains a lines hash that contains information about the subscriptions and invoice items that have been applied to the invoice, as well as any prorations that Stripe has automatically calculated. Each line on the invoice has an amount attribute that represents the amount actually contributed to the invoice’s total. For invoice items and prorations, the amount attribute is the same as for the invoice item or proration respectively. For subscriptions, the amount may be different from the plan’s regular price depending on whether the invoice covers a trial period or the invoice period differs from the plan’s usual interval.
The invoice object has both a subtotal and a total. The subtotal represents the total before any discounts, while the total is the final amount to be charged to the customer after all coupons have been applied.
The invoice also has a next_ attribute that tells you the next time (as a Unix timestamp) payment for the invoice will be automatically attempted. For invoices with manual payment collection, that have been closed, or that have reached the maximum number of retries (specified in your subscriptions settings), the next_ will be null.
{ "id": "in_1MtHbELkdIwHu7ixl4OzzPMv", "object": "invoice", "account_country": "US", "account_name": "Stripe Docs", "account_tax_ids": null, "amount_due": 0, "amount_paid": 0, "amount_overpaid": 0, "amount_remaining": 0, "amount_shipping": 0, "application": null, "attempt_count": 0, "attempted": false, "auto_advance": false, "automatic_tax": { "enabled": false, "liability": null, "status": null }, "billing_reason": "manual", "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, "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, "parent": null, "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, "receipt_number": 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 }, "subtotal": 0, "subtotal_excluding_tax": 0, "test_clock": null, "total": 0, "total_discount_amounts": [], "total_excluding_tax": 0, "total_taxes": [], "webhooks_delivered_at": 1680644467}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, orvoid. 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,
{ "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_overpaid": 0, "amount_remaining": 0, "amount_shipping": 0, "application": null, "attempt_count": 0, "attempted": false, "auto_advance": false, "automatic_tax": { "enabled": false, "liability": null, "status": null }, "billing_reason": "manual", "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, "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, "parent": null, "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, "receipt_number": 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 }, "subtotal": 0, "subtotal_excluding_tax": 0, "test_clock": null, "total": 0, "total_discount_amounts": [], "total_excluding_tax": 0, "total_taxes": [], "webhooks_delivered_at": 1680644467 } ]}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.
{ "id": "in_1MtHbELkdIwHu7ixl4OzzPMv", "object": "invoice", "deleted": true}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.
{ "id": "in_1MtGmCLkdIwHu7ix6PgS6g8S", "object": "invoice", "account_country": "US", "account_name": "Stripe Docs", "account_tax_ids": null, "amount_due": 0, "amount_paid": 0, "amount_overpaid": 0, "amount_remaining": 0, "amount_shipping": 0, "application": null, "attempt_count": 0, "attempted": true, "auto_advance": false, "automatic_tax": { "enabled": false, "liability": null, "status": null }, "billing_reason": "manual", "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, "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, "parent": null, "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, "receipt_number": 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 }, "subtotal": 0, "subtotal_excluding_tax": 0, "test_clock": null, "total": 0, "total_discount_amounts": [], "total_excluding_tax": 0, "total_taxes": [], "webhooks_delivered_at": 1680641304}