DOrtyUNUV2030 Lav7756

 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 , or send_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 metadatanullable object
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.
 period_starttimestamp
Start of the usage period during which invoice items were added to this invoice.
 statusnullable enum
The status of the invoice, one of draft , open , paid , uncollectible , or void . Learn more
 subscriptionnullable stringExpandable
The subscription that this invoice was prepared for, if any.
 totalinteger
Total after discounts and taxes. 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"
},
customer_tax_ids": [],
"discount": null,
"discounts": [],
"due_date": null,
"footer": null,
"issuer": {
"type": "self"
},
More attributes
Expand all
 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_taxobject
 billing_reasonnullable enum
 createdtimestamp
 custom_fieldsnullable array of objects
 customer_addressnullable object
 customer_emailnullable string
 customer_namenullable string
 customer_phonenullable string
 customer_shippingnullable object
 customer_tax_exemptnullable enum
 customer_tax_idsnullable array of objects
 default_payment_methodnullable stringExpandable
 default_sourcenullable stringExpandable
 default_tax_ratesarray of objects
 discountnullable objectDeprecated
 discountsnullable array of stringsExpandable
 due_datenullable timestamp
 effective_atnullable timestamp
 ending_balancenullable integer
 footernullable string
 from_invoicenullable object
 invoice_pdfnullable string
 issuerobjectConnect only
 last_finalization_errornullable object
 latest_revisionnullable stringExpandable
 livemodeboolean
 next_payment_attemptnullable timestamp
 numbernullable string
 on_behalf_ofnullable stringExpandableConnect only
 paidboolean
 paid_out_of_bandboolean
 payment_settingsobject
 post_payment_credit_notes_amountinteger
 pre_payment_credit_notes_amountinteger
 quotenullable stringExpandable
 receipt_numbernullable string
 renderingnullable object
 shipping_costnullable object
 shipping_detailsnullable object
 starting_balanceinteger
 statement_descriptornullable string
 status_transitionsobject
 subscription_detailsnullable object
 subscription_proration_datenullable integer
 subtotalinteger
 subtotal_excluding_taxnullable integer
 taxnullable integer
 test_clocknullable stringExpandable
 threshold_reasonnullable object
 total_discount_amountsnullable array of objects
 total_excluding_taxnullable integer
 total_tax_amountsarray of objects
 transfer_datanullable objectConnect only
 webhooks_delivered_atnullable timestamp
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": [],
"discount": null,
"discounts": [],
"due_date": null,
"footer": 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.
 metadataobject
about the object in a structured format. Note that for line items with type=subscription this will reflect the
metadata of the subscription that caused the line item to be created.
 periodobject
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.
Show child attributes
 pricenullable object
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 a subscription .
Possible enum values
invoiceitem
subscription
More attributes
Expand all
 objectstring
 amount_excluding_taxnullable integer
 discount_amountsnullable array of objects
 discountableboolean
 discountsnullable array of stringsExpandable
 invoice_itemnullable stringExpandable
 livemodeboolean
 proration_detailsnullable object
 subscriptionnullable stringExpandable
 subscription_itemnullable stringExpandable
 tax_amountsarray of objects
 tax_ratesarray of objects
 unit_amount_excluding_taxnullable decimal string
THE INVOICE LINE ITEM OBJECT
{
"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,
"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
Either charge_automatically , or send_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 to charge_automatically .
charge_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.
 metadataobject
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
Expand all
 account_tax_idsarray of strings
 application_fee_amountintegerConnect only
 currencyenum
 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
 from_invoiceobject
 numberstring
 on_behalf_ofstringConnect only
 pending_invoice_items_behaviorenum
 renderingobject
 shipping_costobject
 shipping_detailsobject
 statement_descriptorstring
 transfer_dataobjectConnect only
Returns
Returns the invoice object. Raises an error if the customer ID provided is invalid.
POST /v1/invoices
Server-side language
curl https://api.stripe.com/v1/invoices \
-u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
-d customer=cus_NeZwdNtLEOXuvB
RESPONSE
{
"amount_due": 0,
"amount_paid": 0,
"attempt_count": 0,
"attempted": false,
"automatic_tax": {
"enabled": false,
"liability": null,
"status": null
},
"charge": null,
"created": 1680644467,
"currency": "usd",
"discount": null,
"discounts": [],
"due_date": null,
"footer": null,
"issuer": {
"type": "self"
},
"lines": {
"object": "list",
"data": [],
"has_more": false,
"total_count": 0,
},
"livemode": false,
"metadata": {},
"number": null,
"paid": false,
},
"period_end": 1680644467,
"quote": null,
"status": "draft",
"paid_at": null,
"voided_at": null
},
"subtotal": 0,
"tax": null,
"test_clock": null,
"total": 0,
}
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
Controls whether Stripe performs automatic collection of the invoice.
Either charge_automatically or send_invoice . This field can be updated only on draft invoices.
charge_automatically
send_invoice
An arbitrary string attached to the object. Often useful for displaying to users. Referenced as ‘memo’ in the
Dashboard.
 metadataobject
More parameters
Expand all
 account_tax_idsarray of strings
 application_fee_amountintegerConnect only
 custom_fieldsarray of objects
 days_until_dueinteger
 default_payment_methodstring
 default_sourcestring
 default_tax_ratesarray of strings
 due_datetimestamp
 effective_attimestamp
 footerstring
 numberstring
 renderingobject
 shipping_costobject
 shipping_detailsobject
 statement_descriptorstring
 transfer_dataobjectConnect only
Returns
Returns the invoice object.
POST /v1/invoices/:id
curl https://api.stripe.com/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv \
-d "metadata[order_id]"=6735
RESPONSE
{
"amount_due": 0,
"amount_paid": 0,
"attempt_count": 0,
"attempted": false,
"automatic_tax": {
"enabled": false,
"liability": null,
"status": null
},
"charge": null,
"created": 1680644467,
"currency": "usd",
"discount": null,
"discounts": [],
"due_date": null,
"footer": null,
"issuer": {
"type": "self"
},
"lines": {
"object": "list",
"data": [],
"has_more": false,
"total_count": 0,
},
"livemode": false,
"metadata": {
"order_id": "6735"
},
"number": null,
"paid": false,
},
"period_end": 1680644467,
"quote": null,
"status": "draft",
"paid_at": null,
"voided_at": null
},
"subtotal": 0,
"tax": null,
"test_clock": null,
"total": 0,
}
Update an invoice's line item

Updates an invoice’s line item. Some fields, such as tax_amounts , only live on the invoice line
item, so they can only be updated through this endpoint. Other fields, such as amount , live on
both the invoice item and the invoice line item, so updates on this endpoint will propagate to the
invoice item as well. Updating an invoice’s line item is only possible before the invoice is finalized.
Parameters
 invoicestringRequired
Invoice ID of line item
 line_item_idstringRequired
Invoice line item ID
 amountinteger
The integer amount in cents of the charge to be applied to the upcoming invoice. If you want to apply a
credit to the customer’s account, pass a negative amount.
An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for
easy tracking.
 metadataobject
 periodobject
The period associated with this invoice item. When set to different values, the period will be rendered on
the invoice. If you have Stripe Revenue Recognition enabled, the period will be used to recognize and
defer revenue. See the Revenue Recognition documentation for details.
Show child parameters
 pricestring
The ID of the price object.
 quantityinteger
Non-negative integer. The quantity of units for the line item.
More parameters
Expand all
 discountableboolean
 price_dataobject
 tax_amountsarray of objects
 tax_ratesarray of strings
Returns
The updated invoice’s line item object is returned upon success. Otherwise, this call raises an
error.
POST /v1/invoices/:id/lines/:id
cURL
curl -X POST https://api.stripe.com/v1/invoices/in_1NuhUa2eZvKYlo2CWYVhyvD9/lines/
il_tmp_1Nzo1ZGgdF1VjufLzD1UUn9R \
-u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
RESPONSE
{
"id": "il_tmp_1Nzo1ZGgdF1VjufLzD1UUn9R",
"amount": 1000,
"currency": "usd",
"discounts": [],
"invoice_item": "ii_1Nzo1ZGgdF1VjufLzD1UUn9R",
"livemode": false,
"metadata": {},
"period": {
"end": 1696975413,
"start": 1696975413
},
"price": {
"id": "price_1NzlYfGgdF1VjufL0cVjLJVI",
"object": "price",
"active": true,
"created": 1696965933,
"currency": "usd",
"livemode": false,
"lookup_key": null,
"metadata": {},
"nickname": null,
"product": "prod_OnMHDH6VBmYlTr",
"recurring": null,
"tiers_mode": null,
"type": "one_time",
},
"proration": false,
},
"quantity": 1,
"tax_amounts": [],
"tax_rates": [],
}
Retrieve an invoice
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_payment_attempt 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_payment_attempt will be null.
GET /v1/invoices/:id
curl https://api.stripe.com/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv \
RESPONSE
{
"amount_due": 0,
"amount_paid": 0,
"attempt_count": 0,
"attempted": false,
"automatic_tax": {
"enabled": false,
"liability": null,
"status": null
},
"charge": null,
"created": 1680644467,
"currency": "usd",
"discount": null,
"discounts": [],
"due_date": null,
"footer": null,
"issuer": {
"type": "self"
},
"lines": {
"object": "list",
"data": [],
"has_more": false,
"total_count": 0,
},
"livemode": false,
"metadata": {},
"number": null,
"paid": false,
},
"period_end": 1680644467,
"quote": null,
"status": "draft",
"paid_at": null,
"voided_at": null
},
"subtotal": 0,
"tax": null,
"test_clock": null,
"total": 0,
}
Retrieve an upcoming 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 a proration_date parameter when doing the actual subscription update.
The value passed in should be the same as the subscription_proration_date returned on the upcoming
invoice resource. 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_proration_date on the
upcoming invoice resource.
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.
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
Expand all
 couponstring
 currencyenum
 customer_detailsobject
 invoice_itemsarray of objects
 schedulestring
 subscription_billing_cycle_anchorstring | timestamp
 subscription_cancel_attimestamp
 subscription_cancel_at_period_endboolean
 subscription_cancel_nowboolean
 subscription_default_tax_ratesarray of strings
 subscription_itemsarray of objects
 subscription_proration_behaviorenum
 subscription_proration_datetimestamp
 subscription_resume_atstring
 subscription_start_datetimestamp
 subscription_trial_endstring | timestamp
 subscription_trial_from_planboolean
Returns
Returns an invoice if valid customer information is provided. Raises an error otherwise.
GET /v1/invoices/upcoming
curl -G https://api.stripe.com/v1/invoices/upcoming \
-d customer=cus_NeZwdNtLEOXuvB
RESPONSE
{
"amount_due": 0,
"amount_paid": 0,
"attempt_count": 0,
"attempted": false,
"automatic_tax": {
"enabled": false,
"liability": null,
"status": null
},
"charge": null,
"created": 1680644467,
"currency": "usd",
"discount": null,
"discounts": [],
"due_date": null,
"footer": null,
"issuer": {
"type": "self"
},
"lines": {
"object": "list",
"data": [],
"has_more": false,
"total_count": 0,
},
"livemode": false,
"metadata": {},
"number": null,
"paid": false,
},
"period_end": 1680644467,
"quote": null,
"status": "draft",
"paid_at": null,
"voided_at": null
},
"subtotal": 0,
"tax": null,
"test_clock": null,
"total": 0,
}
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
Expand all
 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 \
RESPONSE
{
"object": "list",
"url": "/v1/invoices/in_1NpHiG2eZvKYlo2CZV0ZkEBT/lines",
"has_more": false,
"data": [
{
"id": "il_tmp_1NpHiK2eZvKYlo2C9NdV8VrI",
"amount": 129999,
"currency": "usd",
"discounts": [],
"invoice_item": "ii_1NpHiK2eZvKYlo2C9NdV8VrI",
"livemode": false,
"metadata": {},
"period": {
"end": 1694467932,
"start": 1694467932
},
"price": {
"id": "price_1NpEIa2eZvKYlo2CXcy5DRPA",
"object": "price",
"active": true,
"created": 1694454804,
"currency": "usd",
"livemode": false,
"lookup_key": null,
"metadata": {},
"nickname": null,
"product": "prod_OcTFTbV7qh48bd",
"recurring": null,
"tiers_mode": null,
"type": "one_time",
},
"proration": false,
},
"quantity": 1,
"tax_amounts": [],
"tax_rates": [],
}
]
}
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.
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
Expand all
 couponstring
 currencyenum
 customer_detailsobject
 invoice_itemsarray of objects
 limitinteger
 schedulestring
 subscription_billing_cycle_anchorstring | timestamp
 subscription_cancel_attimestamp
 subscription_cancel_at_period_endboolean
 subscription_cancel_nowboolean
 subscription_default_tax_ratesarray of strings
 subscription_itemsarray of objects
 subscription_proration_behaviorenum
 subscription_proration_datetimestamp
 subscription_resume_atstring
 subscription_start_datetimestamp
 subscription_trial_endstring | timestamp
 subscription_trial_from_planboolean
Returns
Returns a list of line_item objects.
GET /v1/invoices/upcoming/lines
curl -G https://api.stripe.com/v1/invoices/upcoming/lines \
-d customer=cus_OgeRVYRv3sHroi
RESPONSE
{
"object": "list",
"url": "/v1/invoices/upcoming/lines",
"has_more": false,
"data": [
{
"id": "il_tmp_1NtH5qBHO5VeT9SUzhbifVXt",
"amount": 1000,
"currency": "usd",
"discounts": [],
"invoice_item": "ii_1NtH5qBHO5VeT9SUzhbifVXt",
"livemode": false,
"metadata": {},
"period": {
"end": 1695418858,
"start": 1695418858
},
"price": {
"id": "price_1NrpbEBHO5VeT9SUHp6xMwKA",
"object": "price",
"active": true,
"created": 1695074844,
"currency": "usd",
"livemode": false,
"lookup_key": null,
"metadata": {},
"nickname": null,
"product": "prod_Of9vdHHGRaGOio",
"recurring": null,
"tiers_mode": null,
"type": "one_time",
},
"proration": false,
},
"quantity": 1,
"tax_amounts": [],
"tax_rates": [],
}
{...}
{...}
],
}
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
Only return invoices for the subscription specified by this subscription ID.
More parameters
Expand all
 createdobject
 limitinteger
Returns
A dictionary with a data property that contains an array invoice attachments,
GET /v1/invoices
curl -G https://api.stripe.com/v1/invoices \
-d limit=3
RESPONSE
{
"object": "list",
"url": "/v1/invoices",
"has_more": false,
"data": [
{
"amount_due": 0,
"amount_paid": 0,
"attempt_count": 0,
"attempted": false,
"automatic_tax": {
"enabled": false,
"liability": null,
"status": null
},
"charge": null,
"created": 1680644467,
"currency": "usd",
"discount": null,
"discounts": [],
"due_date": null,
"footer": null,
"issuer": {
"type": "self"
},
"lines": {
"object": "list",
"data": [],
"has_more": false,
"total_count": 0,
},
"livemode": false,
"metadata": {},
"number": null,
"paid": false,
},
"period_end": 1680644467,
"quote": null,
"status": "draft",
"paid_at": null,
"voided_at": null
},
"subtotal": 0,
"tax": null,
"test_clock": null,
"total": 0,
}
{...}
{...}
],
}
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 \

RESPONSE
{
"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
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 \

RESPONSE
{
"id": "in_1MtGmCLkdIwHu7ix6PgS6g8S",
"amount_due": 0,
"amount_paid": 0,
"attempt_count": 0,
"attempted": true,
"automatic_tax": {
"enabled": false,
"liability": null,
"status": null
},
"charge": null,
"collection_method": "send_invoice",
"created": 1680641304,
"currency": "usd",
"customer": "cus_NeZw0zvTyquTfF",
"discount": null,
"discounts": [],
"due_date": 1681246104,
"ending_balance": 0,
"footer": null,
"hosted_invoice_url":
"https://invoice.stripe.com/i/acct_1M2JTkLkdIwHu7ix/test_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9OZVp3d
VBYNnF0dGlvdXRubGVjSXVOOWhiVWpmUktPLDcxMTgyMTA10200x7P2wMSm?s=ap",
"invoice_pdf":
"https://pay.stripe.com/invoice/acct_1M2JTkLkdIwHu7ix/test_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9OZV
p3dVBYNnF0dGlvdXRubGVjSXVOOWhiVWpmUktPLDcxMTgyMTA10200x7P2wMSm/pdf?s=ap",
"issuer": {
"type": "self"
},
"lines": {
"object": "list",
"data": [],
"has_more": false,
"total_count": 0,
"url": "/v1/invoices/in_1MtGmCLkdIwHu7ix6PgS6g8S/lines"
},
"livemode": false,
"metadata": {},
"number": "9545A614-0001",
"paid": true,
},
"period_end": 1680641304,
"quote": null,
"status": "paid",
"finalized_at": 1680641304,
"paid_at": 1680641304,
"voided_at": null
},
"subtotal": 0,
"tax": null,
"test_clock": null,
"total": 0,
}
Mark an invoice as uncollectible

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
POST /v1/invoices/:id/mark_uncollectible
curl -X POST https://api.stripe.com/v1/invoices/in_1MtG0nLkdIwHu7ixAaUw3Cb4/mark_uncollectible \

RESPONSE
{
"id": "in_1MtG0nLkdIwHu7ixAaUw3Cb4",
"amount_due": 599,
"amount_paid": 0,
"attempt_count": 0,
"attempted": false,
"automatic_tax": {
"enabled": false,
"liability": null,
"status": null
},
"charge": null,
"created": 1680638365,
"currency": "usd",
"customer_tax_ids": [
{
"type": "eu_vat",
"value": "DE123456789"
},
{
"type": "eu_vat",
"value": "DE123456781"
}
],
"discount": null,
"discounts": [],
"due_date": null,
"footer": null,
"issuer": {
"type": "self"
},
"lines": {
"object": "list",
"data": [
{
"id": "il_1MtG0nLkdIwHu7ix3eCoIIw7",
"amount": 1099,
"currency": "usd",
"discounts": [],
"invoice_item": "ii_1MtG0nLkdIwHu7ixDqfiUgg8",
"livemode": false,
"metadata": {},
"period": {
"end": 1680638365,
"start": 1680638365
},
"price": {
"id": "price_1Mr89PLkdIwHu7ixf5QhiWm2",
"object": "price",
"active": true,
"created": 1680131491,
"currency": "usd",
"livemode": false,
"lookup_key": null,
"metadata": {},
"nickname": null,
"product": "prod_NcMtLgctyqlJDC",
"recurring": null,
"tiers_mode": null,
"type": "one_time",
},
"proration": false,
},
"quantity": 1,
"tax_amounts": [],
"tax_rates": [],
}
],
"has_more": false,
"url": "/v1/invoices/in_1MtG0nLkdIwHu7ixAaUw3Cb4/lines"
},
"livemode": false,
"metadata": {},
"number": null,
"paid": false,
},
"period_end": 1680638365,
"quote": null,
"starting_balance": -500,
"status": "uncollectible",
"paid_at": null,
"voided_at": null
},
"subtotal": 1099,
"tax": null,
"test_clock": null,
"total": 1099,
"webhooks_delivered_at": null,
"closed": true,
"forgiven": true
}
Pay an invoice
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
Expand all
 forgiveboolean
 mandatestring
 off_sessionboolean
 paid_out_of_bandboolean
 payment_methodstring
 sourcestring
Returns
POST /v1/invoices/:id/pay
curl -X POST https://api.stripe.com/v1/invoices/in_1MtGmCLkdIwHu7ix6PgS6g8S/pay \

RESPONSE
{
"amount_due": 0,
"amount_paid": 0,
"attempt_count": 0,
"attempted": true,
"automatic_tax": {
"enabled": false,
"liability": null,
"status": null
},
"charge": null,
"created": 1680641304,
"currency": "usd",
"discount": null,
"discounts": [],
"due_date": 1681246104,
"footer": null,
"https://invoice.stripe.com/i/acct_1M2JTkLkdIwHu7ix/test_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9OZVp3d
VBYNnF0dGlvdXRubGVjSXVOOWhiVWpmUktPLDcxMTgyMTA10200x7P2wMSm?s=ap",
"invoice_pdf":
p3dVBYNnF0dGlvdXRubGVjSXVOOWhiVWpmUktPLDcxMTgyMTA10200x7P2wMSm/pdf?s=ap",
"issuer": {
"type": "self"
},
"lines": {
"object": "list",
"data": [],
"has_more": false,
"total_count": 0,
},
"livemode": false,
"metadata": {},
"number": "9545A614-0001",
"paid": true,
},
"period_end": 1680641304,
"quote": null,
"status": "paid",
"paid_at": 1680641304,
"voided_at": null
},
"subtotal": 0,
"tax": null,
"test_clock": null,
"total": 0,
}
Search invoices
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.
GET /v1/invoices/search
curl -G https://api.stripe.com/v1/invoices/search \
-d query="amount<1"
RESPONSE
{
"object": "search_result",
"url": "/v1/invoices/search",
"has_more": false,
"data": [
{
"amount_due": 0,
"amount_paid": 0,
"attempt_count": 0,
"attempted": false,
"automatic_tax": {
"enabled": false,
"liability": null,
"status": null
},
"charge": null,
"created": 1680644467,
"currency": "usd",
"discount": null,
"discounts": [],
"due_date": null,
"footer": null,
"issuer": {
"type": "self"
},
"lines": {
"object": "list",
"data": [],
"has_more": false,
"total_count": 0,
},
"livemode": false,
"metadata": {},
"number": null,
"paid": false,
},
"period_end": 1680644467,
"quote": null,
"status": "draft",
"paid_at": null,
"voided_at": null
},
"subtotal": 0,
"tax": null,
"test_clock": null,
"total": 0,
}
{...}
{...}
],
}
Send an invoice for manual payment

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.sent event.
Parameters
No parameters.
Returns
POST /v1/invoices/:id/send
curl -X POST https://api.stripe.com/v1/invoices/in_1MtGmCLkdIwHu7ixJlveR2DO/send \

RESPONSE
{
"id": "in_1MtGmCLkdIwHu7ixJlveR2DO",
"amount_due": 0,
"amount_paid": 0,
"attempt_count": 0,
"attempted": true,
"automatic_tax": {
"enabled": false,
"liability": null,
"status": null
},
"charge": null,
"created": 1680641304,
"currency": "usd",
"customer": "cus_NeZwvqcz9Sh2uw",
"discount": null,
"discounts": [],
"due_date": 1681246104,
"footer": null,
"https://invoice.stripe.com/i/acct_1M2JTkLkdIwHu7ix/test_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9OZVp3
SDR0Q1Q4U1N0YkVjY2lvSmRoRGppU3E1eGVJLDcxMTgyMTA10200hQIJrDM1?s=ap",
"invoice_pdf":
p3SDR0Q1Q4U1N0YkVjY2lvSmRoRGppU3E1eGVJLDcxMTgyMTA10200hQIJrDM1/pdf?s=ap",
"issuer": {
"type": "self"
},
"lines": {
"object": "list",
"data": [],
"has_more": false,
"total_count": 0,
"url": "/v1/invoices/in_1MtGmCLkdIwHu7ixJlveR2DO/lines"
},
"livemode": false,
"metadata": {},
"number": "3AB9C0CA-0001",
"paid": true,
},
"period_end": 1680641304,
"quote": null,
"status": "paid",
"paid_at": 1680641304,
"voided_at": null
},
"subtotal": 0,
"tax": null,
"test_clock": null,
"total": 0,
}
Void an invoice
Mark a finalized invoice as void. This cannot be undone. Voiding an invoice is similar to deletion,
however it only applies to finalized invoices and maintains a papertrail where the invoice can still
be found.
Parameters
No parameters.
Returns
Returns the voided invoice object.
POST /v1/invoices/:id/void
curl -X POST https://api.stripe.com/v1/invoices/in_1MtGmCLkdIwHu7ix6PgS6g8S/void \

RESPONSE
{
"amount_due": 0,
"amount_paid": 0,
"attempt_count": 0,
"attempted": false,
"automatic_tax": {
"enabled": false,
"liability": null,
"status": null
},
"charge": null,
"created": 1680644467,
"currency": "usd",
"discount": null,
"discounts": [],
"due_date": null,
"footer": null,
"issuer": {
"type": "self"
},
"lines": {
"object": "list",
"data": [],
"has_more": false,
"total_count": 0,
},
"livemode": false,
"metadata": {},
"number": null,
"paid": false,
},
"period_end": 1680644467,
"quote": null,
"status": "void",
"paid_at": null,
"voided_at": null
},
"subtotal": 0,
"tax": null,
"test_clock": null,
"total": 0,
}
Invoice Items
Invoice Items represent the component lines of an invoice. An invoice item is added to an invoice
by creating or updating it with an invoice field, at which point it will be included as an invoice line
item within invoice.lines.
Invoice Items can be created before you are ready to actually send the invoice. This can be
particularly useful when combined with a subscription. Sometimes you want to add a charge or
credit to a customer, but actually charge or credit the customer’s card only at the end of a regular
billing cycle. This is useful for combining several charges (to minimize per-transaction fees), or for
having Stripe tabulate your usage-based billing totals.
Related guides: Integrate with the Invoicing API, Subscription Invoices.
ENDPOINTS
POST/v1/invoiceitemsPOST/v1/invoiceitems/:idGET/v1/invoiceitems/:idGET/v1/invoiceitemsDELETE/
v1/invoiceitems/:id
SHOW
Plans
You can now model subscriptions more flexibly using the Prices API. It replaces the Plans API and
is backwards compatible to simplify your migration.
Plans define the base price, currency, and billing cycle for recurring purchases of
products. Products help you track inventory or provisioning, and plans help you track pricing.
Different physical goods or levels of service should be represented by products, and pricing
options should be represented by plans. This approach lets you change prices without having to
change your provisioning scheme.
For example, you might have a single “gold” product that has plans for $10/month, $100/year,
€9/month, and €90/year.
Related guides: Set up a subscription and more about products and prices.
ENDPOINTS
POST/v1/plansPOST/v1/plans/:idGET/v1/plans/:idGET/v1/plansDELETE/v1/plans/:id
SHOW
Quote
A Quote is a way to model prices that you’d like to provide to a customer. Once accepted, it will
automatically create an invoice, subscription or subscription schedule.
ENDPOINTS
POST/v1/quotesPOST/v1/quotes/:idGET/v1/quotes/:id/line_itemsGET/v1/quotes/:id/
computed_upfront_line_itemsGET/v1/quotes/:idGET/v1/quotesPOST/v1/quotes/:id/acceptPOST/v1/
quotes/:id/cancelGET/v1/quotes/:id/pdfPOST/v1/quotes/:id/finalize
SHOW
Subscriptions
Subscriptions allow you to charge a customer on a recurring basis.
Related guide: Creating subscriptions
ENDPOINTS
POST/v1/subscriptionsPOST/v1/subscriptions/:idGET/v1/subscriptions/:idGET/v1/
subscriptionsDELETE/v1/subscriptions/:idPOST/v1/subscriptions/:id/resumeGET/v1/subscriptions/search
SHOW
Subscription Items
Subscription items allow you to create customer subscriptions with more than one plan, making
it easy to represent complex billing relationships.
ENDPOINTS
POST/v1/subscription_itemsPOST/v1/subscription_items/:idGET/v1/subscription_items/:idGET/v1/
subscription_itemsDELETE/v1/subscription_items/:id
SHOW
Subscription Schedule
A subscription schedule allows you to create and manage the lifecycle of a subscription by
predefining expected changes.
Related guide: Subscription schedules
ENDPOINTS
POST/v1/subscription_schedulesPOST/v1/subscription_schedules/:idGET/v1/
subscription_schedules/:idGET/v1/subscription_schedulesPOST/v1/subscription_schedules/:id/
cancelPOST/v1/subscription_schedules/:id/release
SHOW
Tax IDs
You can add one or multiple tax IDs to a customer or account. Customer and account tax IDs get
displayed on related invoices and credit notes.
Related guides: Customer tax identification numbers, Account tax IDs
ENDPOINTS
POST/v1/customers/:id/tax_idsPOST/v1/tax_idsGET/v1/customers/:id/tax_ids/:idGET/v1/
tax_ids/:idGET/v1/customers/:id/tax_idsGET/v1/tax_idsDELETE/v1/customers/:id/tax_ids/:idDELETE/
v1/tax_ids/:id
SHOW
Test ClocksTest helper

A test clock enables deterministic control over objects in testmode. With a test clock, you can
create objects at a frozen time in the past or future, and advance to a specific future time to
observe webhooks and state changes. After the clock advances, you can either validate the
current state of your scenario (and test your assumptions), change the current state of your
scenario (and test more complex scenarios), or keep advancing forward in time.
ENDPOINTS
POST/v1/test_helpers/test_clocksGET/v1/test_helpers/test_clocks/:idGET/v1/test_helpers/
test_clocksDELETE/v1/test_helpers/test_clocks/:idPOST/v1/test_helpers/test_clocks/:id/advance
SHOW
Usage Records
Usage records allow you to report customer usage and metrics to Stripe for metered billing of
subscription prices.
Related guide: Metered billing
ENDPOINTS
POST/v1/subscription_items/:id/usage_recordsGET/v1/subscription_items/:id/usage_record_summaries
SHOW
Accounts
This is an object representing a Stripe account. You can retrieve it to see properties on the
account like its current requirements or if the account is enabled to make live charges or receive
payouts.
For Custom accounts, the properties below are always returned. For other accounts, some
properties are returned until that account has started to go through Connect Onboarding. Once
you create an Account Link or Account Session, some properties are only returned for Custom
accounts. Learn about the differences between accounts.
ENDPOINTS
POST/v1/accountsPOST/v1/accounts/:idGET/v1/accounts/:idGET/v1/accountsDELETE/v1/
accounts/:idPOST/v1/accounts/:id/reject
SHOW
Login Links
Login Links are single-use login link for an Express account to access their Stripe dashboard.
ENDPOINTS
POST/v1/accounts/:id/login_links
SHOW
Account Links
Account Links are the means by which a Connect platform grants a connected account
permission to access Stripe-hosted applications, such as Connect Onboarding.
Related guide: Connect Onboarding
ENDPOINTS
POST/v1/account_links
SHOW
Account Session
An AccountSession allows a Connect platform to grant access to a connected account in Connect
embedded components.
We recommend that you create an AccountSession each time you need to display an embedded
component to your user. Do not save AccountSessions to your database as they expire
relatively quickly, and cannot be used more than once.
Related guide: Connect embedded components
ENDPOINTS
POST/v1/account_sessions
SHOW
Application Fees
When you collect a transaction fee on top of a charge made for your user (using Connect),
an Application Fee object is created in your account. You can list, retrieve, and refund application
fees.
Related guide: Collecting application fees
ENDPOINTS
GET/v1/application_fees/:idGET/v1/application_fees
SHOW
Application Fee Refunds

Application Fee Refund objects allow you to refund an application fee that has previously been
created but not yet refunded. Funds will be refunded to the Stripe account from which the fee
was originally collected.
Related guide: Refunding application fees
ENDPOINTS
POST/v1/application_fees/:id/refundsPOST/v1/application_fees/:id/refunds/:idGET/v1/
application_fees/:id/refunds/:idGET/v1/application_fees/:id/refunds
SHOW
Capabilities
This is an object representing a capability for a Stripe account.
Related guide: Account capabilities
ENDPOINTS
POST/v1/accounts/:id/capabilities/:idGET/v1/accounts/:id/capabilities/:idGET/v1/accounts/:id/capabilities
SHOW
Country Specs
Stripe needs to collect certain pieces of information about each account created. These
requirements can differ depending on the account’s country. The Country Specs API makes these
rules available to your integration.
You can also view the information from this API call as an online guide.
ENDPOINTS
GET/v1/country_specs/:idGET/v1/country_specs
SHOW
External Bank Accounts

External bank accounts are financial accounts associated with a Stripe platform’s connected
accounts for the purpose of transferring funds to or from the connected account’s Stripe balance.
ENDPOINTS
POST/v1/accounts/:id/external_accountsPOST/v1/accounts/:id/external_accounts/:idGET/v1/
accounts/:id/external_accounts/:idGET/v1/accounts/:id/external_accountsDELETE/v1/accounts/:id/
external_accounts/:id
SHOW
External Account Cards

External account cards are debit cards associated with a Stripe platform’s connected accounts for
the purpose of transferring funds to or from the connected accounts Stripe balance.
ENDPOINTS
POST/v1/accounts/:id/external_accountsPOST/v1/accounts/:id/external_accounts/:idGET/v1/
accounts/:id/external_accounts/:idGET/v1/accounts/:id/external_accountsDELETE/v1/accounts/:id/
external_accounts/:id
SHOW
Person
This is an object representing a person associated with a Stripe account.
A platform cannot access a Standard or Express account’s persons after the account starts
onboarding, such as after generating an account link for the account. See the Standard
onboarding or Express onboarding documentation for information about platform prefilling and
account onboarding steps.
Related guide: Handling identity verification with the API
ENDPOINTS
POST/v1/accounts/:id/personsPOST/v1/accounts/:id/persons/:idGET/v1/accounts/:id/persons/:idGET/v1/
accounts/:id/personsDELETE/v1/accounts/:id/persons/:id
SHOW
Top-ups
To top up your Stripe balance, you create a top-up object. You can retrieve individual top-ups, as
well as list all top-ups. Top-ups are identified by a unique, random ID.
Related guide: Topping up your platform account
ENDPOINTS
POST/v1/topupsPOST/v1/topups/:idGET/v1/topups/:idGET/v1/topupsPOST/v1/topups/:id/cancel
SHOW
Transfers
A Transfer object is created when you move funds between Stripe accounts as part of Connect.
Before April 6, 2017, transfers also represented movement of funds from a Stripe account to a
card or bank account. This behavior has since been split out into a Payout object, with
corresponding payout endpoints. For more information, read about the transfer/payout split.
Related guide: Creating separate charges and transfers
ENDPOINTS
POST/v1/transfersPOST/v1/transfers/:idGET/v1/transfers/:idGET/v1/transfers
SHOW
Transfer Reversals
Stripe Connect platforms can reverse transfers made to a connected account, either entirely or
partially, and can also specify whether to refund any related application fees. Transfer reversals
add to the platform’s balance and subtract from the destination account’s balance.
Reversing a transfer that was made for a destination charge is allowed only up to the amount
of the charge. It is possible to reverse a transfer_group transfer only if the destination account
has enough balance to cover the reversal.
Related guide: Reversing transfers
ENDPOINTS
POST/v1/transfers/:id/reversalsPOST/v1/transfers/:id/reversals/:idGET/v1/transfers/:id/reversals/:idGET/
v1/transfers/:id/reversals
SHOW
Secrets
Secret Store is an API that allows Stripe Apps developers to securely persist secrets for use by UI
Extensions and app backends.
The primary resource in Secret Store is a secret . Other apps can’t view secrets created by an app.
Additionally, secrets are scoped to provide further permission control.
All Dashboard users and the app backend share account scoped secrets. Use the account scope for
secrets that don’t change per-user, like a third-party API key.
A user scoped secret is accessible by the app backend and one specific Dashboard user. Use
the user scope for per-user secrets like per-user OAuth tokens, where different users might have
different permissions.
Related guide: Store data between page reloads
ENDPOINTS
GET/v1/apps/secretsPOST/v1/apps/secrets/deleteGET/v1/apps/secrets/findPOST/v1/apps/secrets
SHOW
Early Fraud Warning
An early fraud warning indicates that the card issuer has notified us that a charge may be
fraudulent.
Related guide: Early fraud warnings
ENDPOINTS
GET/v1/radar/early_fraud_warnings/:idGET/v1/radar/early_fraud_warnings
SHOW
Reviews
Reviews can be used to supplement automated fraud detection with human expertise.
Learn more about Radar and reviewing payments here.
ENDPOINTS
GET/v1/reviews/:idGET/v1/reviewsPOST/v1/reviews/:id/approve
SHOW
Value Lists
Value lists allow you to group values together which can then be referenced in rules.
Related guide: Default Stripe lists
ENDPOINTS
POST/v1/radar/value_listsPOST/v1/radar/value_lists/:idGET/v1/radar/value_lists/:idGET/v1/radar/
value_listsDELETE/v1/radar/value_lists/:id
SHOW
Value List Items

Value list items allow you to add specific values to a given Radar value list, which can then be
used in rules.
Related guide: Managing list items
ENDPOINTS
POST/v1/radar/value_list_itemsGET/v1/radar/value_list_items/:idGET/v1/radar/
value_list_itemsDELETE/v1/radar/value_list_items/:id
SHOW
Authorizations
When an issued card is used to make a purchase, an Issuing Authorization object is
created. Authorizations must be approved for the purchase to be completed successfully.
Related guide: Issued card authorizations
ENDPOINTS
POST/v1/issuing/authorizations/:idGET/v1/issuing/authorizations/:idGET/v1/issuing/
authorizationsPOST/v1/issuing/authorizations/:id/approvePOST/v1/issuing/authorizations/:id/
declinePOST/v1/test_helpers/issuing/authorizationsPOST/v1/test_helpers/issuing/authorizations/:id/
capturePOST/v1/test_helpers/issuing/authorizations/:id/expirePOST/v1/test_helpers/issuing/
authorizations/:id/incrementPOST/v1/test_helpers/issuing/authorizations/:id/reverse
SHOW
Cardholders
An Issuing Cardholder object represents an individual or business entity who is issued cards.
Related guide: How to create a cardholder
ENDPOINTS
POST/v1/issuing/cardholdersPOST/v1/issuing/cardholders/:idGET/v1/issuing/cardholders/:idGET/v1/
issuing/cardholders
SHOW
Cards
You can create physical or virtual cards that are issued to cardholders.
ENDPOINTS
POST/v1/issuing/cardsPOST/v1/issuing/cards/:idGET/v1/issuing/cards/:idGET/v1/issuing/cardsPOST/v1/
test_helpers/issuing/cards/:id/shipping/deliverPOST/v1/test_helpers/issuing/cards/:id/shipping/failPOST/
v1/test_helpers/issuing/cards/:id/shipping/returnPOST/v1/test_helpers/issuing/cards/:id/shipping/ship
SHOW
Disputes
As a card issuer, you can dispute transactions that the cardholder does not recognize, suspects to
be fraudulent, or has other issues with.
Related guide: Issuing disputes
ENDPOINTS
POST/v1/issuing/disputesPOST/v1/issuing/disputes/:idGET/v1/issuing/disputes/:idGET/v1/issuing/
disputesPOST/v1/issuing/disputes/:id/submit
SHOW
Funding Instructions
Funding Instructions contain reusable bank account and routing information. Push funds to these
addresses via bank transfer to top up Issuing Balances.
ENDPOINTS
POST/v1/issuing/funding_instructionsGET/v1/issuing/funding_instructionsPOST/v1/test_helpers/issuing/
fund_balance
SHOW
TokensPreview feature
An issuing token object is created when an issued card is added to a digital wallet. As a card
issuer, you can view and manage these tokens through Stripe.
ENDPOINTS
POST/v1/issuing/tokens/:idGET/v1/issuing/tokens/:idGET/v1/issuing/tokens
SHOW
Transactions
Any use of an issued card that results in funds entering or leaving your Stripe account, such as a
completed purchase or refund, is represented by an Issuing Transaction object.
Related guide: Issued card transactions
ENDPOINTS
POST/v1/issuing/transactions/:idGET/v1/issuing/transactions/:idGET/v1/issuing/transactionsPOST/v1/
test_helpers/issuing/transactions/create_force_capturePOST/v1/test_helpers/issuing/transactions/
create_unlinked_refundPOST/v1/test_helpers/issuing/transactions/:id/refund
SHOW
Connection Token
A Connection Token is used by the Stripe Terminal SDK to connect to a reader.
Related guide: Fleet management
ENDPOINTS
POST/v1/terminal/connection_tokens
SHOW
Location
A Location represents a grouping of readers.
Related guide: Fleet management
ENDPOINTS
POST/v1/terminal/locationsPOST/v1/terminal/locations/:idGET/v1/terminal/locations/:idGET/v1/
terminal/locationsDELETE/v1/terminal/locations/:id
SHOW
Reader
A Reader represents a physical device for accepting payment details.
Related guide: Connecting to a reader
ENDPOINTS
POST/v1/terminal/readersPOST/v1/terminal/readers/:idGET/v1/terminal/readers/:idGET/v1/terminal/
readersDELETE/v1/terminal/readers/:idPOST/v1/terminal/readers/:id/cancel_actionPOST/v1/terminal/
readers/:id/collect_inputsPOST/v1/terminal/readers/:id/confirm_payment_intentPOST/v1/terminal/
readers/:id/collect_payment_methodPOST/v1/terminal/readers/:id/process_payment_intentPOST/v1/
terminal/readers/:id/process_setup_intentPOST/v1/terminal/readers/:id/refund_paymentPOST/v1/
terminal/readers/:id/set_reader_displayPOST/v1/test_helpers/terminal/readers/:id/
present_payment_method
SHOW
Terminal Hardware OrderPreview feature

A TerminalHardwareOrder represents an order for Terminal hardware, containing information
such as the price, shipping information and the items ordered.
ENDPOINTS
POST/v1/terminal/hardware_ordersGET/v1/terminal/hardware_orders/:idGET/v1/terminal/
hardware_ordersPOST/v1/terminal/hardware_orders/:id/cancelGET/v1/terminal/hardware_orders/
previewPOST/v1/test_helpers/terminal/hardware_orders/:id/mark_ready_to_shipPOST/v1/test_helpers/
terminal/hardware_orders/:id/deliverPOST/v1/test_helpers/terminal/hardware_orders/:id/shipPOST/v1/
test_helpers/terminal/hardware_orders/:id/mark_undeliverable
SHOW
Terminal Hardware ProductPreview

feature
A TerminalHardwareProduct is a category of hardware devices that are generally similar, but may
have variations depending on the country it’s shipped to.
TerminalHardwareSKUs represent variations within the same Product (for example, a country
specific device). For example, WisePOS E is a TerminalHardwareProduct and a WisePOS E - US
and WisePOS E - UK are TerminalHardwareSKUs.
ENDPOINTS
GET/v1/terminal/hardware_products/:idGET/v1/terminal/hardware_products
SHOW
Terminal Hardware SKUPreview feature

A TerminalHardwareSKU represents a SKU for Terminal hardware. A SKU is a representation of a
product available for purchase, containing information such as the name, price, and images.
ENDPOINTS
GET/v1/terminal/hardware_skus/:idGET/v1/terminal/hardware_skus
SHOW
Terminal Hardware Shipping

MethodPreview feature
A TerminalHardwareShipping represents a Shipping Method for Terminal hardware. A Shipping
Method is a country-specific representation of a way to ship hardware, containing information
such as the country, name, and expected delivery date.
ENDPOINTS
GET/v1/terminal/hardware_shipping_methods/:idGET/v1/terminal/hardware_shipping_methods
SHOW
Configuration
A Configurations object represents how features should be configured for terminal readers.
ENDPOINTS
POST/v1/terminal/configurationsPOST/v1/terminal/configurations/:idGET/v1/terminal/
configurations/:idGET/v1/terminal/configurationsDELETE/v1/terminal/configurations/:id
SHOW
Financial Accounts
Stripe Treasury provides users with a container for money called a FinancialAccount that is
separate from their Payments balance. FinancialAccounts serve as the source and destination of
Treasury’s money movement APIs.
ENDPOINTS
POST/v1/treasury/financial_accountsPOST/v1/treasury/financial_accounts/:idGET/v1/treasury/
financial_accounts/:idGET/v1/treasury/financial_accounts
SHOW
Financial Account Features

Encodes whether a FinancialAccount has access to a particular Feature, with a status enum and
associated status_details . Stripe or the platform can control Features via the requested field.
ENDPOINTS
POST/v1/treasury/financial_accounts/:id/featuresGET/v1/treasury/financial_accounts/:id/features
SHOW
Transactions
Transactions represent changes to a FinancialAccount’s balance.
ENDPOINTS
GET/v1/treasury/transactions/:idGET/v1/treasury/transactions
SHOW
Transaction Entries
TransactionEntries represent individual units of money movements within a single Transaction.
ENDPOINTS
GET/v1/treasury/transaction_entries/:idGET/v1/treasury/transaction_entries
SHOW
Outbound Transfers
Use OutboundTransfers to transfer funds from a FinancialAccount to a PaymentMethod
belonging to the same entity. To send funds to a different party, use OutboundPayments instead.
You can send funds over ACH rails or through a domestic wire transfer to a user’s own external
bank account.
Simulate OutboundTransfer state changes with the /v1/test_helpers/treasury/outbound_transfers endpoints.
These methods can only be called on test mode objects.
ENDPOINTS
POST/v1/treasury/outbound_transfersGET/v1/treasury/outbound_transfers/:idGET/v1/treasury/
outbound_transfersPOST/v1/treasury/outbound_transfers/:id/cancelPOST/v1/test_helpers/treasury/
outbound_transfers/:id/failPOST/v1/test_helpers/treasury/outbound_transfers/:id/postPOST/v1/
test_helpers/treasury/outbound_transfers/:id/return
SHOW
Outbound Payments
Use OutboundPayments to send funds to another party’s external bank account
or FinancialAccount. To send money to an account belonging to the same user, use
an OutboundTransfer.
Simulate OutboundPayment state changes with
the /v1/test_helpers/treasury/outbound_payments endpoints. These methods can only be called on test
mode objects.
ENDPOINTS
POST/v1/treasury/outbound_paymentsGET/v1/treasury/outbound_payments/:idGET/v1/treasury/
outbound_paymentsPOST/v1/treasury/outbound_payments/:id/cancelPOST/v1/test_helpers/treasury/
outbound_payments/:id/failPOST/v1/test_helpers/treasury/outbound_payments/:id/postPOST/v1/
test_helpers/treasury/outbound_payments/:id/return
SHOW
Inbound Transfers
Use InboundTransfers to add funds to your FinancialAccount via a PaymentMethod that is owned
by you. The funds will be transferred via an ACH debit.
ENDPOINTS
POST/v1/treasury/inbound_transfersGET/v1/treasury/inbound_transfers/:idGET/v1/treasury/
inbound_transfersPOST/v1/treasury/inbound_transfers/:id/cancelPOST/v1/test_helpers/treasury/
inbound_transfers/:id/failPOST/v1/test_helpers/treasury/inbound_transfers/:id/returnPOST/v1/
test_helpers/treasury/inbound_transfers/:id/succeed
SHOW
Received Credits
ReceivedCredits represent funds sent to a FinancialAccount (for example, via ACH or wire). These
money movements are not initiated from the FinancialAccount.
ENDPOINTS
GET/v1/treasury/received_credits/:idGET/v1/treasury/received_creditsPOST/v1/test_helpers/treasury/
received_credits
SHOW
Received Debits
ReceivedDebits represent funds pulled from a FinancialAccount. These are not initiated from the
FinancialAccount.
ENDPOINTS
GET/v1/treasury/received_debits/:idGET/v1/treasury/received_debitsPOST/v1/test_helpers/treasury/
received_debits
SHOW
Credit Reversals
You can reverse some ReceivedCredits depending on their network and source flow. Reversing a
ReceivedCredit leads to the creation of a new object known as a CreditReversal.
ENDPOINTS
POST/v1/treasury/credit_reversalsGET/v1/treasury/credit_reversals/:idGET/v1/treasury/credit_reversals
SHOW
Debit Reversals
You can reverse some ReceivedDebits depending on their network and source flow. Reversing a
ReceivedDebit leads to the creation of a new object known as a DebitReversal.
ENDPOINTS
POST/v1/treasury/debit_reversalsGET/v1/treasury/debit_reversals/:idGET/v1/treasury/debit_reversals
SHOW
Scheduled Queries
If you have scheduled a Sigma query, you’ll receive a sigma.scheduled_query_run.created webhook each
time the query runs. The webhook contains a ScheduledQueryRun object, which you can use
to retrieve the query results.
ENDPOINTS
GET/v1/sigma/scheduled_query_runs/:idGET/v1/sigma/scheduled_query_runs
SHOW
Report Runs
The Report Run object represents an instance of a report type generated with specific run
parameters. Once the object is created, Stripe begins processing the report. When the report has
finished running, it will give you a reference to a file where you can retrieve your results. For an
overview, see API Access to Reports.
Note that certain report types can only be run based on your live-mode data (not test-
mode data), and will error when queried without a live-mode API key.
ENDPOINTS
POST/v1/reporting/report_runsGET/v1/reporting/report_runs/:idGET/v1/reporting/report_runs
SHOW
Report Types
The Report Type resource corresponds to a particular type of report, such as the “Activity
summary” or “Itemized payouts” reports. These objects are identified by an ID belonging to a set
of enumerated values. See API Access to Reports documentation for those Report Type IDs,
along with required and optional parameters.
Note that certain report types can only be run based on your live-mode data (not test-
mode data), and will error when queried without a live-mode API key.
ENDPOINTS
GET/v1/reporting/report_types/:idGET/v1/reporting/report_types
SHOW
Accounts
A Financial Connections Account represents an account that exists outside of Stripe, to which you
have been granted some degree of access.
ENDPOINTS
GET/v1/financial_connections/accounts/:idGET/v1/financial_connections/accountsPOST/v1/
financial_connections/accounts/:id/disconnectPOST/v1/financial_connections/accounts/:id/refreshPOST/
v1/financial_connections/accounts/:id/subscribePOST/v1/financial_connections/accounts/:id/unsubscribe
SHOW
Account Owner
Describes an owner of an account.
ENDPOINTS
GET/v1/financial_connections/accounts/:id/owners
SHOW
Session
A Financial Connections Session is the secure way to programmatically launch the client-side
Stripe.js modal that lets your users link their accounts.
ENDPOINTS
POST/v1/financial_connections/sessionsGET/v1/financial_connections/sessions/:id
SHOW
Transactions
A Transaction represents a real transaction that affects a Financial Connections Account balance.
ENDPOINTS
GET/v1/financial_connections/transactions/:idGET/v1/financial_connections/transactions
SHOW
Tax Calculations
A Tax Calculation allows you to calculate the tax to collect from your customer.
Related guide: Calculate tax in your custom payment flow
ENDPOINTS
GET/v1/tax/calculations/:id/line_itemsPOST/v1/tax/calculations
SHOW
Tax Registrations
A Tax Registration lets us know that your business is registered to collect tax on payments within a
region, enabling you to automatically collect tax.
Stripe doesn’t register on your behalf with the relevant authorities when you create a
Tax Registration object. For more information on how to register to collect tax, see our guide.
Related guide: Using the Registrations API
ENDPOINTS
POST/v1/tax/registrationsPOST/v1/tax/registrations/:idGET/v1/tax/registrations/:idGET/v1/tax/
registrations
SHOW
Tax Transactions
A Tax Transaction records the tax collected from or refunded to your customer.
Related guide: Calculate tax in your custom payment flow
ENDPOINTS
POST/v1/tax/transactions/create_reversalPOST/v1/tax/transactions/create_from_calculationGET/v1/tax/
transactions/:id/line_itemsGET/v1/tax/transactions/:id
SHOW
Tax Settings
You can use Tax Settings to manage configurations used by Stripe Tax calculations.
Related guide: Using the Settings API
ENDPOINTS
POST/v1/tax/settingsGET/v1/tax/settings
SHOW
Verification Session
A VerificationSession guides you through the process of collecting and verifying the identities of
your users. It contains details about the type of verification, such as what verification check to
perform. Only create one VerificationSession for each verification in your system.
A VerificationSession transitions through multiple statuses throughout its lifetime as it progresses
through the verification flow. The VerificationSession contains the user’s verified data
after verification checks are complete.
Related guide: The Verification Sessions API
ENDPOINTS
POST/v1/identity/verification_sessionsPOST/v1/identity/verification_sessions/:idGET/v1/identity/
verification_sessions/:idGET/v1/identity/verification_sessionsPOST/v1/identity/verification_sessions/:id/
cancelPOST/v1/identity/verification_sessions/:id/redact
SHOW
Verification Report
A VerificationReport is the result of an attempt to collect and verify data from a user. The
collection of verification checks performed is determined from the type and options parameters
used. You can find the result of each verification check performed in the appropriate sub-
resource: document , id_number , selfie .
Each VerificationReport contains a copy of any data collected by the user as well as reference IDs
which can be used to access collected images through the FileUpload API. To configure and
create VerificationReports, use the VerificationSession API.
Related guides: Accessing verification results.
ENDPOINTS
GET/v1/identity/verification_reports/:idGET/v1/identity/verification_reports
SHOW
Crypto Onramp Session

A Crypto Onramp Session represents your customer’s session as they purchase cryptocurrency
through Stripe. Once payment is successful, Stripe will fulfill the delivery of cryptocurrency to
your user’s wallet and contain a reference to the crypto transaction ID.
You can create an onramp session on your server and embed the widget on your frontend.
Alternatively, you can redirect your users to the standalone hosted onramp.
Related guide: Integrate the onramp
ENDPOINTS
POST/v1/crypto/onramp_sessionsGET/v1/crypto/onramp_sessions/:idGET/v1/crypto/onramp_sessions
SHOW
Crypto Onramp Quotes

Crypto Onramp Quotes are estimated quotes for onramp conversions into all the different
cryptocurrencies on different networks. The Quotes API allows you to display quotes in your
product UI before directing the user to the onramp widget.
Related guide: Quotes API
ENDPOINTS
GET/v1/crypto/onramp/quotes
SHOW
Climate Order
Orders represent your intent to purchase a particular Climate product. When you create an order,
the payment is deducted from your merchant balance.
ENDPOINTS
POST/v1/climate/ordersPOST/v1/climate/orders/:idGET/v1/climate/orders/:idGET/v1/climate/
ordersPOST/v1/climate/orders/:id/cancel
SHOW
Climate Product
A Climate product represents a type of carbon removal unit available for reservation. You can
retrieve it to see the current price and availability.
ENDPOINTS
GET/v1/climate/products/:idGET/v1/climate/products
SHOW
Climate Supplier
A supplier of carbon removal.
ENDPOINTS
GET/v1/climate/suppliers/:idGET/v1/climate/suppliers
SHOW
Forwarding RequestPreview feature

Instructs Stripe to make a request on your behalf using the destination URL and HTTP method in
the config. A config is set up for each destination URL by Stripe at the time of onboarding. Stripe
verifies requests with your credentials in the config, and injects card details from the
payment_method into the request.
Stripe redacts all sensitive fields and headers, including authentication credentials and card
numbers, before storing the request and response data in the forwarding Request object, which
are subject to a 30-day retention period.
You can provide a Stripe idempotency key to make sure that requests with the same key result in
only one outbound request. The Stripe idempotency key provided should be unique and different
from any idempotency keys provided on the underlying third-party request.
Forwarding Requests are synchronous requests that return a response or time out according
to Stripe’s limits.
ENDPOINTS
POST/v1/forwarding/requestsGET/v1/forwarding/requests/:idGET/v1/forwarding/requests
SHOW
Webhook Endpoints
You can configure webhook endpoints via the API to be notified about events that happen in
your Stripe account or connected accounts.
Most users configure webhooks from the dashboard, which provides a user interface for
registering and testing your webhook endpoints.
Related guide: Setting up webhooks
ENDPOINTS
POST/v1/webhook_endpointsPOST/v1/webhook_endpoints/:idGET/v1/webhook_endpoints/:idGET/v1/
webhook_endpointsDELETE/v1/webhook_endpoints/:id
SHOW
We use cookies to improve your experience and for marketing. Read our cookie policy or manage cookies.
ndicate an error that failed given the information provided (e.g., a required parameter was
omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Stripe’s servers
(these are rare).
Some 4xx errors that could be handled programmatically (e.g., a card is declined) include
an error code that briefly explains the error reported.
Attributes
 typeenum
The type of error returned. One of api_error , card_error , idempotency_error , or invalid_request_error
api_error
card_error
idempotency_error
invalid_request_error
 codenullable string
For some errors that could be handled programmatically, a short string indicating the error
code reported.
 decline_codenullable string
For card errors resulting from a card issuer decline, a short string indicating the card issuer’s
reason for the decline if they provide one.
 messagenullable string
A human-readable message providing more details about the error. For card errors, these
messages can be shown to your users.
 paramnullable string
If the error is parameter-specific, the parameter related to the error. For example, you can use
this to display a message near the correct form field.
 payment_intentnullable object
The PaymentIntent object for errors returned on a request involving a PaymentIntent.
More
Expand all
 chargenullable string
 payment_method_typenullable string
 doc_urlnullable string
 request_log_urlnullable string
 setup_intentnullable object
 sourcenullable object
 payment_methodnullable object
HTTP STATUS CODE SUMMARY
200 OK Everything worked as expected.
The request was unacceptable, often due to missing a required
400 Bad Request
parameter.
401 Unauthorized No valid API key provided.
402 Request Failed The parameters were valid but the request failed.
403 Forbidden The API key doesn’t have permissions to perform the request.
404 Not Found The requested resource doesn’t exist.
The request conflicts with another request (perhaps due to
409 Conflict
using the same idempotent key).
Too Many Too many requests hit the API too quickly. We recommend an
429
Requests exponential backoff of your requests.
500, 502,
Server Errors Something went wrong on Stripe’s end. (These are rare.)
503, 504
ERROR TYPES
API errors cover any other type of problem (e.g., a temporary problem with
api_error
Stripe’s servers), and are extremely uncommon.
Card errors are the most common type of error you should expect to
card_error handle. They result when the user enters a card that can’t be charged for
some reason.
Idempotency errors occur when an Idempotency-Key is re-used on a request
idempotency_error
that does not match the first request’s API endpoint and parameters.
invalid_request_erro
r
Invalid request errors arise when your request has invalid parameters.
Handling errors
Our Client libraries raise exceptions for many reasons, such as a failed charge, invalid
parameters, authentication errors, and network unavailability. We recommend writing code
that gracefully handles all possible API exceptions.
 Related guide: Error Handling
cUR L
# Select a client library to see examples of

# handling different kinds of errors.
Expanding Responses
Many objects allow you to request additional information as an expanded response by using
the expand request parameter. This parameter is available on all API requests, and applies to
the response of that request only. You can expand responses in two ways.
In many cases, an object contains the ID of a related object in its response properties. For
example, a Charge might have an associated Customer ID. You can expand these objects in
line with the expand request parameter. The expandable label in this documentation indicates
ID fields that you can expand into objects.
Some available fields aren’t included in the responses by default, such as
the number and cvc fields for the Issuing Card object. You can request these fields as an
expanded response by using the expand request parameter.
You can expand recursively by specifying nested fields after a dot ( . ). For example,
requesting invoice.subscription on a charge expands the invoice property into a full Invoice
object, then expands the subscription property on that invoice into a full Subscription object.
You can use the expand parameter on any endpoint that returns expandable fields, including
list, create, and update endpoints.
Expansions on list requests start with the data property. For example, you can
expand data.customers on a request to list charges and associated customers. Performing deep
expansions on numerous list requests might result in slower processing times.
Expansions have a maximum depth of four levels (for example, the deepest expansion
allowed when listing charges is data.invoice.subscription.default_source ).
You can expand multiple objects at the same time by identifying multiple items in
the expand array.
 Related guide: Expanding responses
 Related video: Expand
curl https://api.stripe.com/v1/charges/ch_3LmzzQ2eZvKYlo2C0XjzUzJV \
-u sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc: \
-d "expand[]"=customer \
-d "expand[]"="invoice.subscription" \
-G
RESPONSE
{
"id": "ch_3LmzzQ2eZvKYlo2C0XjzUzJV",
"object": "charge",
"customer": {
"id": "cu_14HOpH2eZvKYlo2CxXIM7Pb2",
"object": "customer",
// ...
},
"invoice": {
"id": "in_1LmzzQ2eZvKYlo2CpyWn8szu",
"subscription": {
"id": "su_1LmzoG2eZvKYlo2Cpw6S7dAq",
"object": "subscription",
// ...
},
// ...
},
// ...
}
Idempotent requests
The API supports idempotency for safely retrying requests without accidentally performing
the same operation twice. When creating or updating an object, use an idempotency key.
Then, if a connection error occurs, you can safely repeat the request without risk of creating a
second object or performing the update twice.
To perform an idempotent request, provide an additional IdempotencyKey element to the
request options.
Stripe’s idempotency works by saving the resulting status code and body of the first request
made for any given idempotency key, regardless of whether it succeedes or fails. Subsequent
requests with the same key return the same result, including 500 errors.
A client generates an idempotency key, which is a unique key that the server uses to
recognize subsequent retries of the same request. How you create unique keys is up to you,
but we suggest using V4 UUIDs, or another random string with enough entropy to avoid
collisions. Idempotency keys are up to 255 characters long.
You can remove keys from the system automatically after they’re at least 24 hours old. We
generate a new request if a key is reused after the original is pruned. The idempotency layer
compares incoming parameters to those of the original request and errors if they’re the same
to prevent accidental misuse.
We save results only after the execution of an endpoint begins. If incoming parameters fail
validation, or the request conflicts with another request that’s executing concurrently, we
don’t save the idempotent result because no API endpoint initiates the execution. You can
retry these requests. Learn more about when you can retry idempotent requests.
All POST requests accept idempotency keys. Don’t send idempotency keys
in GET and DELETE requests because it has no effect. These requests are idempotent by
definition.
 Related video: Idempotency and retries
curl https://api.stripe.com/v1/customers \
-H "Idempotency-Key: KG5LxwFBepaKHyUD" \
-d description="My First Test Customer (created for API docs at https://www.stripe.com/docs/api)"
Metadata
Updateable Stripe objects—
including Account, Charge, Customer, PaymentIntent, Refund, Subscription,
and Transfer have a metadata parameter. You can use this parameter to attach key-value data
to these Stripe objects.
You can specify up to 50 keys, with key names up to 40 characters long and values up to 500
characters long.
You can use metadata to store additional, structured information on an object. For example,
you could store your user’s full name and corresponding unique identifier from your system
on a Stripe Customer object. Stripe doesn’t use metadata—for example, we don’t use it to
authorize or decline a charge and it won’t be seen by your users unless you choose to show it
to them.
Some of the objects listed above also support a description parameter. You can use
the description parameter to annotate a charge-for example, a human-readable description such
as 2 shirts for test@example.com . Unlike metadata , description is a single string, which your users
might see (for example, in email receipts Stripe sends on your behalf).
Don’t store any sensitive information (bank account numbers, card details, and so on) as
metadata or in the description parameter.
 Related video: Metadata
Sample metadata use cases
 Link IDs: Attach your system’s unique IDs to a Stripe object to simplify lookups. For
example, add your order number to a charge, your user ID to a customer or recipient,
or a unique receipt number to a transfer.
 Refund papertrails: Store information about the reason for a refund and the
individual responsible for its creation.
 Customer details: Annotate a customer by storing an internal ID for your future use.
POST /v1/customers
-d "metadata[order_id]"=6735
{
"id": "cus_123456789",
"address": {
"city": "city",
"country": "US",
"line1": "line 1",
"line2": "line 2",
"postal_code": "90210",
"state": "CA"
},
"balance": 0,
"created": 1483565364,
"currency": null,
"delinquent": false,
"discount": null,
"email": null,
"invoice_prefix": "C11F7E1",
"invoice_settings": {
"footer": null,
"rendering_options": null
},
"livemode": false,
"metadata": {
"order_id": "6735"
},
"name": null,
"next_invoice_sequence": 1,
"phone": null,
"preferred_locales": [],
"shipping": null,
"tax_exempt": "none"
}
Pagination
All top-level API resources have support for bulk fetches through “list” API methods. For
example, you can list charges, list customers, and list invoices. These list API methods share
a common structure and accept, at a minimum, the following three
parameters: limit , starting_after , and ending_before .
Stripe’s list API methods use cursor-based pagination through
the starting_after and ending_before parameters. Both parameters accept an existing object ID
value (see below) and return objects in reverse chronological order.
The ending_before parameter returns objects listed before the named object.
The starting_after parameter returns objects listed after the named object. These parameters are
mutually exclusive. You can use either the starting_after or ending_before parameter, but not
both simultaneously.
Our client libraries offer auto-pagination helpers to traverse all pages of a list.
 Related video: Pagination and auto-pagination
Parameters
 limitoptional, default is 10
This specifies a limit on the number of objects to return, ranging between 1 and 100.
 starting_afteroptional object ID
A cursor to use in pagination. starting_after is an object ID that defines your place in the list.
For example, if you make a list request and receive 100 objects, ending with obj_foo , your
subsequent call can include starting_after=obj_foo to fetch the next page of the list.
 ending_beforeoptional object ID
A cursor to use in pagination. ending_before is an object ID that defines your place in the list.
For example, if you make a list request and receive 100 objects, starting with obj_bar , your
subsequent call can include ending_before=obj_bar to fetch the previous page of the list.
List Response Format
 objectstring, value is "list"

A string that provides a description of the object type that returns.
 dataarray
An array containing the actual response elements, paginated by any request parameters.
 has_moreboolean
Whether or not there are more elements available after this set. If false , this set comprises the
end of the list.
 urlurl
The URL for accessing this list.
RESPONSE
{
"object": "list",
"url": "/v1/customers",
"has_more": false,
"data": [
{
"id": "cus_4QFJOjw2pOmAGJ",
"address": null,
"balance": 0,
"created": 1405641735,
"currency": "usd",
"default_source": "card_14HOpG2eZvKYlo2Cz4u5AJG5",
"description": "New customer",
"discount": null,
"email": null,
"invoice_prefix": "7D11B54",
"footer": null,
},
"livemode": false,
"metadata": {
"order_id": "6735"
},
"name": "cus_4QFJOjw2pOmAGJ",
"phone": null,
"shipping": null,
"tax_exempt": "none",
"test_clock": null
},
{...},
{...}
]
}
Search
Some top-level API resource have support for retrieval via “search” API methods. For
example, you can search charges, search customers, and search subscriptions.
Stripe’s search API methods utilize cursor-based pagination via the page request parameter
and next_page response parameter. For example, if you make a search request and
receive "next_page": "pagination_key" in the response, your subsequent call can
include page=pagination_key to fetch the next page of results.
Our client libraries offer auto-pagination helpers to easily traverse all pages of a search result.
Search request format
 queryrequired
The search query string. See search query language.
 limitoptional
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the
default is 10.
 pageoptional
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.
Search response format
 objectstring, value is "search_result"

A string describing the object type returned.
 urlstring
The URL for accessing this list.
 has_moreboolean
Whether or not there are more elements available after this set. If false , this set comprises the
end of the list.
 dataarray
An array containing the actual response elements, paginated by any request parameters.
 next_pagestring
A cursor for use in pagination. If has_more is true, you can pass the value of next_page to a
subsequent call to fetch the next page of results.
 total_countoptional positive integer or zero
The total number of objects that match the query, only accurate up to 10,000. This field is not
included by default. To include it in the response, expand the total_count field.
RESPONSE
{
"object": "search_result",
"url": "/v1/customers/search",
"has_more": false,
"data": [
{
"id": "cus_4QFJOjw2pOmAGJ",
"address": null,
"balance": 0,
"created": 1405641735,
"currency": "usd",
"default_source": "card_14HOpG2eZvKYlo2Cz4u5AJG5",
"description": "someone@example.com for Coderwall",
"discount": null,
"email": null,
"invoice_prefix": "7D11B54",
"footer": null,
},
"livemode": false,
"metadata": {
"foo": "bar"
},
"name": "fakename",
"phone": null,
"shipping": null,
"tax_exempt": "none",
"test_clock": null
},
{...},
{...}
]
}
Auto-pagination
Our libraries support auto-pagination. This feature allows you to easily iterate through large
lists of resources without having to manually perform the requests to fetch subsequent pages.
# The auto-pagination feature is specific to Stripe's

# libraries and cannot be used directly with curl.
Request IDs
Each API request has an associated request identifier. You can find this value in the response
headers, under Request-Id . You can also find request identifiers in the URLs of individual
request logs in your Dashboard.
To expedite the resolution process, provide the request identifier when you contact us about a
specific request.
-D "-" \
-X POST
Versioning
When backwards-incompatible changes are made to the API, we release a new, dated version.
The current version is 2023-10-16. Learn more about API upgrades and backwards
compatibility. For information on all API updates, view our API changelog.
You can upgrade your API version in the Developer Dashboard. As a precaution, use API
versioning to test a new API version before committing to an upgrade.
 Related video: Versioning
curl https://api.stripe.com/v1/charges \
-H "Stripe-Version: 2023-10-16"
Balance
This is an object representing your Stripe balance. You can retrieve it to see the balance currently
on your Stripe account.
You can also retrieve the balance history, which contains a list of transactions that contributed to
the balance (charges, payouts, and so forth).
The available and pending amounts for each currency are broken down further by payment
source types.
Related guide: Understanding Connect account balances
ENDPOINTS
GET/v1/balance
SHOW
Balance Transactions
Balance transactions represent funds moving through your Stripe account. Stripe creates them
for every type of transaction that enters or leaves your Stripe account balance.
Related guide: Balance transaction types
ENDPOINTS
GET/v1/balance_transactions/:idGET/v1/balance_transactions
SHOW
Charges
The Charge object represents a single attempt to move money into your Stripe
account. PaymentIntent confirmation is the most common way to create Charges, but
transferring money to a different Stripe account through Connect also creates Charges. Some
legacy payment flows create Charges directly, which is not recommended for new integrations.
ENDPOINTS
POST/v1/chargesPOST/v1/charges/:idGET/v1/charges/:idGET/v1/chargesPOST/v1/charges/:id/
captureGET/v1/charges/search
SHOW
Customers
This object represents a customer of your business. Use it to create recurring charges and track
payments that belong to the same customer.
Related guide: Save a card during payment
ENDPOINTS
POST/v1/customersPOST/v1/customers/:idGET/v1/customers/:idGET/v1/customersDELETE/v1/
customers/:idGET/v1/customers/search
SHOW
Customer Session
A customer session allows you to grant client access to Stripe’s frontend SDKs (like
StripeJs) control over a customer.
ENDPOINTS
POST/v1/customer_sessions
SHOW
Disputes
A dispute occurs when a customer questions your charge with their card issuer. When this
happens, you have the opportunity to respond to the dispute with evidence that shows that the
charge is legitimate.
Related guide: Disputes and fraud
ENDPOINTS
POST/v1/disputes/:idGET/v1/disputes/:idGET/v1/disputesPOST/v1/disputes/:id/close
SHOW
Events
Events are our way of letting you know when something interesting happens in your account.
When an interesting event occurs, we create a new Event object. For example, when a charge
succeeds, we create a charge.succeeded event, and when an invoice payment attempt fails, we create
an invoice.payment_failed event. Certain API requests might create multiple events. For example, if
you create a new subscription for a customer, you receive both a customer.subscription.created event
and a charge.succeeded event.
Events occur when the state of another API resource changes. The event’s data field embeds the
resource’s state at the time of the change. For example, a charge.succeeded event contains a charge,
and an invoice.payment_failed event contains an invoice.
As with other API resources, you can use endpoints to retrieve an individual event or a list of
events from the API. We also have a separate webhooks system for sending the Event objects
directly to an endpoint on your server. You can manage webhooks in your account settings.
Learn how to listen for events so that your integration can automatically trigger reactions.
When using Connect, you can also receive event notifications that occur in connected accounts.
For these events, there’s an additional account attribute in the received Event object.
We only guarantee access to events through the Retrieve Event API for 30 days.
ENDPOINTS
GET/v1/events/:idGET/v1/events
SHOW
Files
This object represents files hosted on Stripe’s servers. You can upload files with the create
file request (for example, when uploading dispute evidence). Stripe also creates files
independently (for example, the results of a Sigma scheduled query).
Related guide: File upload guide
ENDPOINTS
POST/v1/filesGET/v1/files/:idGET/v1/files
SHOW
File Links
To share the contents of a File object with non-Stripe users, you can create a FileLink . FileLink s
contain a URL that you can use to retrieve the contents of the file without authentication.
ENDPOINTS
POST/v1/file_linksPOST/v1/file_links/:idGET/v1/file_links/:idGET/v1/file_links
SHOW
Mandates
A Mandate is a record of the permission that your customer gives you to debit their payment
method.
ENDPOINTS
GET/v1/mandates/:id
SHOW
Payment Intents
A PaymentIntent guides you through the process of collecting a payment from your
customer. We recommend that you create exactly one PaymentIntent for each order or customer
session in your system. You can reference the PaymentIntent later to see the history of payment
attempts for a particular session.
A PaymentIntent transitions through multiple statuses throughout its lifetime as it interfaces with
Stripe.js to perform authentication flows and ultimately creates at most one successful charge.
Related guide: Payment Intents API
ENDPOINTS
POST/v1/payment_intentsPOST/v1/payment_intents/:idGET/v1/payment_intents/:idGET/v1/
payment_intentsPOST/v1/payment_intents/:id/cancelPOST/v1/payment_intents/:id/capturePOST/v1/
payment_intents/:id/confirmPOST/v1/payment_intents/:id/increment_authorizationPOST/v1/
payment_intents/:id/apply_customer_balanceGET/v1/payment_intents/searchPOST/v1/
payment_intents/:id/verify_microdeposits
SHOW
Setup Intents
A SetupIntent guides you through the process of setting up and saving a customer’s payment
credentials for future payments. For example, you can use a SetupIntent to set up and save your
customer’s card without immediately collecting a payment. Later, you can use PaymentIntents to
drive the payment flow.
Create a SetupIntent when you’re ready to collect your customer’s payment credentials. Don’t
maintain long-lived, unconfirmed SetupIntents because they might not be valid. The SetupIntent
transitions through multiple statuses as it guides you through the setup process.
Successful SetupIntents result in payment credentials that are optimized for future payments. For
example, cardholders in certain regions might need to be run through Strong Customer
Authentication during payment method collection to streamline later off-session payments. If
you use the SetupIntent with a Customer, it automatically attaches the resulting payment method
to that Customer after successful setup. We recommend using SetupIntents
or setup_future_usage on PaymentIntents to save payment methods to prevent saving invalid or
unoptimized payment methods.
By using SetupIntents, you can reduce friction for your customers, even as regulations change
over time.
Related guide: Setup Intents API
ENDPOINTS
POST/v1/setup_intentsPOST/v1/setup_intents/:idGET/v1/setup_intents/:idGET/v1/setup_intentsPOST/
v1/setup_intents/:id/cancelPOST/v1/setup_intents/:id/confirmPOST/v1/setup_intents/:id/
verify_microdeposits
SHOW
Setup Attempts
A SetupAttempt describes one attempted confirmation of a SetupIntent, whether that
confirmation is successful or unsuccessful. You can use SetupAttempts to inspect details of a
specific attempt at setting up a payment method using a SetupIntent.
ENDPOINTS
GET/v1/setup_attempts
SHOW
Payouts
A Payout object is created when you receive funds from Stripe, or when you initiate a payout to
either a bank account or debit card of a connected Stripe account. You can retrieve individual
payouts, and list all payouts. Payouts are made on varying schedules, depending on your country
and industry.
Related guide: Receiving payouts
ENDPOINTS
POST/v1/payoutsPOST/v1/payouts/:idGET/v1/payouts/:idGET/v1/payoutsPOST/v1/payouts/:id/
cancelPOST/v1/payouts/:id/reverse
SHOW
Refunds
Refund objects allow you to refund a previously created charge that isn’t refunded yet. Funds are
refunded to the credit or debit card that’s initially charged.
Related guide: Refunds
ENDPOINTS
POST/v1/refundsPOST/v1/refunds/:idGET/v1/refunds/:idGET/v1/refundsPOST/v1/refunds/:id/cancel
SHOW
Confirmation TokenPreview feature

ConfirmationTokens help transport client side data collected by Stripe JS over to your server for
confirming a PaymentIntent or SetupIntent. If the confirmation is successful, values present on
the ConfirmationToken are written onto the Intent.
To learn more or request access, visit the related guided: Finalize payments on the server using
Confirmation Tokens.
ENDPOINTS
GET/v1/confirmation_tokens/:id
SHOW
Tokens
Tokenization is the process Stripe uses to collect sensitive card or bank account details, or
personally identifiable information (PII), directly from your customers in a secure manner. A token
representing this information is returned to your server to use. Use our recommended payments
integrations to perform this process on the client-side. This guarantees that no sensitive card
data touches your server, and allows your integration to operate in a PCI-compliant way.
If you can’t use client-side tokenization, you can also create tokens using the API with either your
publishable or secret API key. If your integration uses this method, you’re responsible for any PCI
compliance that it might require, and you must keep your secret API key safe. Unlike with client-
side tokenization, your customer’s information isn’t sent directly to Stripe, so we can’t determine
how it’s handled or stored.
You can’t store or use tokens more than once. To store card or bank account information for later
use, create Customer objects or Custom accounts. Radar, our integrated solution for automatic
fraud protection, performs best with integrations that use client-side tokenization.
ENDPOINTS
POST/v1/tokensPOST/v1/tokensPOST/v1/tokensPOST/v1/tokensPOST/v1/tokensPOST/v1/tokensGET/
v1/tokens/:id
SHOW
Payment Methods
PaymentMethod objects represent your customer’s payment instruments. You can use them
with PaymentIntents to collect payments or save them to Customer objects to store instrument
details for future payments.
Related guides: Payment Methods and More Payment Scenarios.
ENDPOINTS
POST/v1/payment_methodsPOST/v1/payment_methods/:idGET/v1/customers/:id/
payment_methods/:idGET/v1/payment_methods/:idGET/v1/customers/:id/payment_methodsGET/v1/
payment_methodsPOST/v1/payment_methods/:id/attachPOST/v1/payment_methods/:id/detach
SHOW
Payment Method Configurations

PaymentMethodConfigurations control which payment methods are displayed to your customers
when you don’t explicitly specify payment method types. You can have multiple configurations
with different sets of payment methods for different scenarios.
There are two types of PaymentMethodConfigurations. Which is used depends on the charge
type:
Direct configurations apply to payments created on your account, including Connect destination
charges, Connect separate charges and transfers, and payments not involving Connect.
Child configurations apply to payments created on your connected accounts using direct
charges, and charges with the on_behalf_of parameter.
Child configurations have a parent that sets default values and controls which settings connected
accounts may override. You can specify a parent ID at payment time, and Stripe will automatically
resolve the connected account’s associated child configuration. Parent configurations
are managed in the dashboard and are not available in this API.
Related guides:
 Payment Method Configurations API
 Multiple configurations on dynamic payment methods
 Multiple configurations for your Connect accounts
ENDPOINTS
POST/v1/payment_method_configurationsPOST/v1/payment_method_configurations/:idGET/v1/
payment_method_configurations/:idGET/v1/payment_method_configurations
SHOW
Payment Method Domains

A payment method domain represents a web domain that you have registered with Stripe. Stripe
Elements use registered payment method domains to control where certain payment methods
are shown.
Related guides: Payment method domains.
ENDPOINTS
POST/v1/payment_method_domainsPOST/v1/payment_method_domains/:idGET/v1/
payment_method_domains/:idGET/v1/payment_method_domainsPOST/v1/
payment_method_domains/:id/validate
SHOW
Bank Accounts
These bank accounts are payment methods on Customer objects.
On the other hand External Accounts are transfer destinations on Account objects for Custom
accounts. They can be bank accounts or debit cards as well, and are documented in the links
above.
Related guide: Bank debits and transfers
ENDPOINTS
POST/v1/customers/:id/sourcesPOST/v1/customers/:id/sources/:idGET/v1/customers/:id/
bank_accounts/:idGET/v1/customers/:id/bank_accountsDELETE/v1/customers/:id/sources/:idPOST/v1/
customers/:id/sources/:id/verify
SHOW
Cash Balance
A customer’s Cash balance represents real funds. Customers can add funds to their cash balance by
sending a bank transfer. These funds can be used for payment and can eventually be paid out to
your bank account.
ENDPOINTS
POST/v1/customers/:id/cash_balanceGET/v1/customers/:id/cash_balance
SHOW
Cash Balance Transaction

Customers with certain payments enabled have a cash balance, representing funds that were
paid by the customer to a merchant, but have not yet been allocated to a payment. Cash Balance
Transactions represent when funds are moved into or out of this balance. This includes funding
by the customer, allocation to payments, and refunds to the customer.
ENDPOINTS
GET/v1/customers/:id/cash_balance_transactions/:idGET/v1/customers/:id/
cash_balance_transactionsPOST/v1/test_helpers/customers/:id/fund_cash_balance
SHOW
Cards
You can store multiple cards on a customer in order to charge the customer later. You can also
store multiple debit cards on a recipient in order to transfer to those cards later.
Related guide: Card payments with Sources
ENDPOINTS
POST/v1/customers/:id/sourcesPOST/v1/customers/:id/sources/:idGET/v1/customers/:id/cards/:idGET/
v1/customers/:id/cardsDELETE/v1/customers/:id/sources/:id
SHOW
SourcesDeprecated
Source objects allow you to accept a variety of payment methods. They represent a customer’s
payment instrument, and can be used with the Stripe API just like a Card object: once chargeable,
they can be charged, or can be attached to customers.
Stripe doesn’t recommend using the deprecated Sources API. We recommend that you adopt
the PaymentMethods API. This newer API provides access to our latest features and payment
method types.
Related guides: Sources API and Sources & Customers.
ENDPOINTS
POST/v1/sourcesPOST/v1/sources/:idGET/v1/sources/:idPOST/v1/customers/:id/sourcesDELETE/v1/
customers/:id/sources/:id
SHOW
Products
Products describe the specific goods or services you offer to your customers. For example, you
might offer a Standard and Premium version of your goods or service; each version would be a
separate Product. They can be used in conjunction with Prices to configure pricing in Payment
Links, Checkout, and Subscriptions.
Related guides: Set up a subscription, share a Payment Link, accept payments with Checkout, and
more about Products and Prices

DOrtyUNUV2030 Lav7756

Uploaded by

Copyright:

Available Formats

DOrtyUNUV2030 Lav7756

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

DOrtyUNUV2030 Lav7756

Uploaded by

Copyright:

Available Formats

 idstring

The Invoice Line Item object

Update an invoice's line item

Retrieve an upcoming invoice

Retrieve an invoice's line items

Retrieve an upcoming invoice's line items

List all invoices

Delete a draft invoice

curl -X DELETE https://api.stripe.com/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv \

curl -X POST https://api.stripe.com/v1/invoices/in_1MtGmCLkdIwHu7ix6PgS6g8S/finalize \

Mark an invoice as uncollectible

curl -X POST https://api.stripe.com/v1/invoices/in_1MtG0nLkdIwHu7ixAaUw3Cb4/mark_uncollectible \

curl -X POST https://api.stripe.com/v1/invoices/in_1MtGmCLkdIwHu7ix6PgS6g8S/pay \

Send an invoice for manual payment

curl -X POST https://api.stripe.com/v1/invoices/in_1MtGmCLkdIwHu7ixJlveR2DO/send \

curl -X POST https://api.stripe.com/v1/invoices/in_1MtGmCLkdIwHu7ix6PgS6g8S/void \

Test ClocksTest helper

Application Fee Refunds

External Bank Accounts

External Account Cards

Value List Items

Terminal Hardware OrderPreview feature

Terminal Hardware ProductPreview

Terminal Hardware SKUPreview feature

Terminal Hardware Shipping

Financial Account Features

Crypto Onramp Session

Crypto Onramp Quotes

Forwarding RequestPreview feature

# Select a client library to see examples of

List Response Format

 objectstring, value is "list"

Search request format

Search response format

 objectstring, value is "search_result"

# The auto-pagination feature is specific to Stripe's

Confirmation TokenPreview feature

Payment Method Configurations

Payment Method Domains

Cash Balance Transaction

You might also like