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_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}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_remaining": 599, "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": 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, "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": [ { "id": "il_1MtG0nLkdIwHu7ix3eCoIIw7", "object": "line_item", "amount": 1099, "amount_excluding_tax": 1099, "currency": "usd", "description": "My First Invoice Item (created for API docs)", "discount_amounts": [], "discountable": true, "discounts": [], "invoice_item": "ii_1MtG0nLkdIwHu7ixDqfiUgg8", "livemode": false, "metadata": {}, "period": { "end": 1680638365, "start": 1680638365 }, "price": { "id": "price_1Mr89PLkdIwHu7ixf5QhiWm2", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1680131491, "currency": "usd", "custom_unit_amount": null, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "product": "prod_NcMtLgctyqlJDC", "recurring": null, "tax_behavior": "unspecified", "tiers_mode": null, "transform_quantity": null, "type": "one_time", "unit_amount": 1099, "unit_amount_decimal": "1099" }, "proration": false, "proration_details": { "credited_items": null }, "quantity": 1, "subscription": null, "tax_amounts": [], "tax_rates": [], "type": "invoiceitem", "unit_amount_excluding_tax": "1099" } ], "has_more": false, "url": "/v1/invoices/in_1MtG0nLkdIwHu7ixAaUw3Cb4/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": 1680638365, "period_start": 1680638365, "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": -500, "statement_descriptor": null, "status": "uncollectible", "status_transitions": { "finalized_at": null, "marked_uncollectible_at": null, "paid_at": null, "voided_at": null }, "subscription": null, "subtotal": 1099, "subtotal_excluding_tax": 1099, "tax": null, "test_clock": null, "total": 1099, "total_discount_amounts": [], "total_excluding_tax": 1099, "total_tax_amounts": [], "transfer_data": null, "webhooks_delivered_at": null, "closed": true, "forgiven": true}Stripe automatically creates and then attempts to collect payment on invoices for customers on subscriptions according to your subscriptions settings. However, if you’d like to attempt payment on an invoice out of the normal collection schedule or for some other reason, you can do so.
Parameters
No parameters.
More parameters
- forgiveboolean
- mandatestring
- off_
sessionboolean - paid_
out_ of_ bandboolean - payment_
methodstring - sourcestring
Returns
Returns the invoice object.
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}Search for invoices you’ve previously created using Stripe’s Search Query Language. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.
Parameters
- querystringRequired
The search query string. See search query language and the list of supported query fields for invoices.
- limitinteger
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
- pagestring
A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.
Returns
A dictionary with a data property that contains an array of up to limit invoices. If no objects match the query, the resulting array will be empty. See the related guide on expanding properties in lists.
Response
{ "object": "search_result", "url": "/v1/invoices/search", "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 } ]}Stripe will automatically send invoices to customers according to your subscriptions settings. However, if you’d like to manually send an invoice to your customer out of the normal schedule, you can do so. When sending invoices that have already been paid, there will be no reference to the payment in the email.
Requests made in test-mode result in no emails being sent, despite sending an invoice. event.
Parameters
No parameters.
Returns
Returns the invoice object.
Response
{ "id": "in_1MtGmCLkdIwHu7ixJlveR2DO", "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_NeZwvqcz9Sh2uw", "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_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9OZVp3SDR0Q1Q4U1N0YkVjY2lvSmRoRGppU3E1eGVJLDcxMTgyMTA10200hQIJrDM1?s=ap", "invoice_pdf": "https://pay.stripe.com/invoice/acct_1M2JTkLkdIwHu7ix/test_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9OZVp3SDR0Q1Q4U1N0YkVjY2lvSmRoRGppU3E1eGVJLDcxMTgyMTA10200hQIJrDM1/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_1MtGmCLkdIwHu7ixJlveR2DO/lines" }, "livemode": false, "metadata": {}, "next_payment_attempt": null, "number": "3AB9C0CA-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}