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 - createdassociative array
- ending_
beforestring - limitinteger
- starting_
afterstring
Returns
A associative array with a data property that contains an array invoice attachments,
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_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, "parent": 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 throws an error, such as if the invoice has already been deleted.
Response
{ "id": "in_1MtHbELkdIwHu7ixl4OzzPMv", "object": "invoice", "deleted": true}Attaches a PaymentIntent or an Out of Band Payment to the invoice, adding it to the list of payments.
For the PaymentIntent, when the PaymentIntent’s status changes to succeeded, the payment is credited to the invoice, increasing its amount_. When the invoice is fully paid, the invoice’s status becomes paid.
If the PaymentIntent’s status is already succeeded when it’s attached, it’s credited to the invoice immediately.
See: Partial payments to learn more.
Parameters
- payment_
intentstring The ID of the PaymentIntent to attach to the invoice.
Returns
Returns the invoice object that the payment was attached to.
Response
{ "id": "in_1Nj68C2eZvKYlo2CGmFJak8q", "object": "invoice", "account_country": "US", "account_name": "Stripe.com", "account_tax_ids": null, "amount_due": 1299, "amount_paid": 0, "amount_overpaid": 0, "amount_remaining": 1299, "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": 1692993440, "currency": "usd", "custom_fields": null, "customer": "cus_9s6XKzkNRiz8i3", "customer_address": null, "customer_email": "test@test.com", "customer_name": null, "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, "effective_at": 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": [ { "id": "il_1Nj68C2eZvKYlo2C7fRlh2gN", "object": "line_item", "amount": 1299, "currency": "usd", "description": "My First Invoice Item (created for API docs)", "discount_amounts": [], "discountable": true, "discounts": [], "livemode": false, "metadata": {}, "parent": { "type": "invoice_item_details", "invoice_item_details": { "invoice_item": "ii_1Nj68C2eZvKYlo2CTeCUHDgE", "proration": false, "proration_details": { "credited_items": null }, "subscription": null } }, "period": { "end": 1692993440, "start": 1692993440 }, "pricing": { "price_details": { "price": "price_1Nj5c82eZvKYlo2CfVgOGez4", "product": "prod_OW7r6RmADUSO13" }, "type": "price_details", "unit_amount_decimal": "1299" }, "quantity": 1, "taxes": [] } ], "has_more": false, "url": "/v1/invoices/in_1Nj68C2eZvKYlo2CGmFJak8q/lines" }, "livemode": false, "metadata": {}, "next_payment_attempt": null, "number": null, "on_behalf_of": null, "parent": null, "payment_settings": { "default_mandate": null, "payment_method_options": null, "payment_method_types": null }, "payments": { "object": "list", "data": [ { "id": "inpay_1M3USa2eZvKYlo2CBjuwbq0N", "object": "invoice_payment", "amount_paid": 2000, "amount_requested": 2000, "created": 1391288554, "currency": "usd", "invoice": "in_1Nj68C2eZvKYlo2CGmFJak8q", "is_default": true, "livemode": false, "payment": { "type": "payment_intent", "payment_intent": "pi_1GszwY2eZvKYlo2CohCEmT6b" }, "status": "paid", "status_transitions": { "canceled_at": null, "paid_at": 1391288554 } } ], "has_more": false, "url": "/v1/invoices/in_1Nj68C2eZvKYlo2CGmFJak8q/payments" }, "period_end": 1688482163, "period_start": 1688395763, "post_payment_credit_notes_amount": 0, "pre_payment_credit_notes_amount": 0, "receipt_number": null, "redaction": null, "shipping_cost": null, "shipping_details": null, "starting_balance": 0, "statement_descriptor": null, "status": "open", "status_transitions": { "finalized_at": null, "marked_uncollectible_at": null, "paid_at": null, "voided_at": null }, "subtotal": 1299, "subtotal_excluding_tax": 1299, "test_clock": null, "total": 1299, "total_discount_amounts": [], "total_excluding_tax": 1299, "total_taxes": [], "transfer_data": null, "webhooks_delivered_at": null}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.
Response
{ "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, "parent": 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}Marking an invoice as uncollectible is useful for keeping track of bad debts that can be written off for accounting purposes.
Parameters
No parameters.
Returns
Returns the invoice object.
Response
{ "id": "in_1MtG0nLkdIwHu7ixAaUw3Cb4", "object": "invoice", "account_country": "US", "account_name": "Stripe Docs", "account_tax_ids": null, "amount_due": 599, "amount_paid": 0, "amount_overpaid": 0, "amount_remaining": 599, "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": 1680638365, "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": [ { "type": "eu_vat", "value": "DE123456789" }, { "type": "eu_vat", "value": "DE123456781" } ], "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": [ { "id": "il_1MtG0nLkdIwHu7ix3eCoIIw7", "object": "line_item", "amount": 1099, "currency": "usd", "description": "My First Invoice Item (created for API docs)", "discount_amounts": [], "discountable": true, "discounts": [], "livemode": false, "metadata": {}, "parent": { "type": "invoice_item_details", "invoice_item_details": { "invoice_item": "ii_1MtG0nLkdIwHu7ixDqfiUgg8", "proration": false, "proration_details": { "credited_items": null }, "subscription": null } }, "period": { "end": 1680638365, "start": 1680638365 }, "pricing": { "price_details": { "price": "price_1Mr89PLkdIwHu7ixf5QhiWm2", "product": "prod_NcMtLgctyqlJDC" }, "type": "price_details", "unit_amount_decimal": "1099" }, "quantity": 1, "taxes": [] } ], "has_more": false, "url": "/v1/invoices/in_1MtG0nLkdIwHu7ixAaUw3Cb4/lines" }, "livemode": false, "metadata": {}, "next_payment_attempt": null, "number": null, "on_behalf_of": null, "parent": null, "payment_settings": { "default_mandate": null, "payment_method_options": null, "payment_method_types": null }, "period_end": 1680638365, "period_start": 1680638365, "post_payment_credit_notes_amount": 0, "pre_payment_credit_notes_amount": 0, "receipt_number": null, "shipping_cost": null, "shipping_details": null, "starting_balance": -500, "statement_descriptor": null, "status": "uncollectible", "status_transitions": { "finalized_at": null, "marked_uncollectible_at": null, "paid_at": null, "voided_at": null }, "subtotal": 1099, "subtotal_excluding_tax": 1099, "test_clock": null, "total": 1099, "total_discount_amounts": [], "total_excluding_tax": 1099, "total_taxes": [], "webhooks_delivered_at": null, "closed": true, "forgiven": true}