Stripe Invoice API
Invoices are statements of amounts owed by a customer, and are either generated one-off, or generated periodically from a subscription.
OpenAPI Specification
openapi: 3.0.0
info:
title: Stripe Invoice API
description: >-
Invoices are statements of amounts owed by a customer, and are either
generated one-off, or generated periodically from a subscription.
contact:
email: [email protected]
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
security:
- basicAuth: []
- bearerAuth: []
servers:
- url: https://api.stripe.com/
paths:
/v1/Invoice Items:
get:
description: >-
<p>Returns a list of your invoice items. Invoice items are returned
sorted by creation date, with the most recently created invoice items
appearing first.</p>
operationId: getInvoice Items
parameters:
- explode: true
in: query
name: created
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: >-
The identifier of the customer whose invoice items to return. If
none is provided, all invoice items will be returned.
in: query
name: customer
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
Only return invoice items belonging to this invoice. If none is
provided, all invoice items will be returned. If specifying an
invoice, no customer identifier is needed.
in: query
name: invoice
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
Set to `true` to only show pending invoice items, which are not yet
attached to any invoices. Set to `false` to only show invoice items
already attached to invoices. If unspecified, no filter is applied.
in: query
name: pending
required: false
schema:
type: boolean
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetInvoice ItemsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/InvoicesItemsList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Invoice Items
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Invoice
- Items
post:
description: >-
<p>Creates an item to be added to a draft invoice (up to 250 items per
invoice). If no invoice is specified, the item will be on the next
invoice created for the customer specified.</p>
operationId: postInvoice Items
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
discounts:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
period:
explode: true
style: deepObject
price_data:
explode: true
style: deepObject
tax_code:
explode: true
style: deepObject
tax_rates:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostInvoice ItemsRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/invoiceitem'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Invoice Items
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Invoice
- Items
- Post
/v1/Invoice Items/{invoiceitem}:
delete:
description: >-
<p>Deletes an invoice item, removing it from an invoice. Deleting
invoice items is only possible when they’re not attached to invoices, or
if it’s attached to a draft invoice.</p>
operationId: deleteInvoice ItemsInvoiceitem
parameters:
- in: path
name: invoiceitem
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/DeleteInvoice ItemsInvoiceitemRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/deleted_invoiceitem'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Delete Invoice Items
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Delete
- Invoice
- Items
get:
description: <p>Retrieves the invoice item with the given ID.</p>
operationId: getInvoice ItemsInvoiceitem
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: invoiceitem
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetInvoice ItemsInvoiceitemRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/invoiceitem'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Invoice Items
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Invoice
- Items
post:
description: >-
<p>Updates the amount or description of an invoice item on an upcoming
invoice. Updating an invoice item is only possible before the invoice
it’s attached to is closed.</p>
operationId: postInvoice ItemsInvoiceitem
parameters:
- in: path
name: invoiceitem
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
discounts:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
period:
explode: true
style: deepObject
price_data:
explode: true
style: deepObject
tax_code:
explode: true
style: deepObject
tax_rates:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostInvoice ItemsInvoiceitemRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/invoiceitem'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Invoice Items
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Invoice
- Items
- Post
/v1/invoices:
get:
description: >-
<p>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.</p>
operationId: getInvoices
parameters:
- description: >-
The collection method of the invoice to retrieve. Either
`charge_automatically` or `send_invoice`.
in: query
name: collection_method
required: false
schema:
enum:
- charge_automatically
- send_invoice
type: string
style: form
- explode: true
in: query
name: created
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: Only return invoices for the customer specified by this customer ID.
in: query
name: customer
required: false
schema:
maxLength: 5000
type: string
style: form
- explode: true
in: query
name: due_date
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
The status of the invoice, one of `draft`, `open`, `paid`,
`uncollectible`, or `void`. [Learn
more](https://stripe.com/docs/billing/invoices/workflow#workflow-overview)
in: query
name: status
required: false
schema:
enum:
- draft
- open
- paid
- uncollectible
- void
type: string
x-stripeBypassValidation: true
style: form
- description: >-
Only return invoices for the subscription specified by this
subscription ID.
in: query
name: subscription
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetInvoicesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/InvoicesList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Invoices
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Invoices
post:
description: >-
<p>This endpoint creates a draft invoice for a given customer. The
invoice remains a draft until you <a
href="#finalize_invoice">finalize</a> the invoice, which allows you to
<a href="#pay_invoice">pay</a> or <a href="#send_invoice">send</a> the
invoice to your customers.</p>
operationId: postInvoices
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
account_tax_ids:
explode: true
style: deepObject
automatic_tax:
explode: true
style: deepObject
custom_fields:
explode: true
style: deepObject
default_tax_rates:
explode: true
style: deepObject
discounts:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
from_invoice:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
payment_settings:
explode: true
style: deepObject
rendering:
explode: true
style: deepObject
shipping_cost:
explode: true
style: deepObject
shipping_details:
explode: true
style: deepObject
transfer_data:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostInvoicesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Invoices
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Invoices
- Post
/v1/invoices/search:
get:
description: >-
<p>Search for invoices you’ve previously created using Stripe’s <a
href="/docs/search#search-query-language">Search Query Language</a>.
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.</p>
operationId: getInvoicesSearch
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
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.
in: query
name: page
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
The search query string. See [search query
language](https://stripe.com/docs/search#search-query-language) and
the list of supported [query fields for
invoices](https://stripe.com/docs/search#query-fields-for-invoices).
in: query
name: query
required: true
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetInvoicesSearchRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/SearchResult'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Invoices Search
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Invoices
- Search
/v1/invoices/upcoming:
get:
description: >-
<p>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.</p>
<p>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.</p>
<p>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 <code>proration_date</code> parameter when doing the
actual subscription update. The value passed in should be the same as
the <code>subscription_proration_date</code> returned on the upcoming
invoice resource. The recommended way to get only the prorations being
previewed is to consider only proration line items where
<code>period[start]</code> is equal to the
<code>subscription_proration_date</code> on the upcoming invoice
resource.</p>
operationId: getInvoicesUpcoming
parameters:
- description: Settings for automatic tax lookup for this invoice preview.
explode: true
in: query
name: automatic_tax
required: false
schema:
properties:
enabled:
type: boolean
required:
- enabled
title: automatic_tax_param
type: object
style: deepObject
- description: >-
The code of the coupon to apply. If `subscription` or
`subscription_items` is provided, the invoice returned will preview
updating or creating a subscription with that coupon. Otherwise, it
will preview applying that coupon to the customer for the next
upcoming invoice from among the customer's subscriptions. The
invoice can be previewed without a coupon by passing this value as
an empty string.
in: query
name: coupon
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
The currency to preview this invoice in. Defaults to that of
`customer` if not specified.
in: query
name: currency
required: false
schema:
type: string
style: form
- description: >-
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.
in: query
name: customer
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
Details about the customer you want to invoice or overrides for an
existing customer. If `automatic_tax` is enabled then one of
`customer`, `customer_details`, `subscription`, or `schedule` must
be set.
explode: true
in: query
name: customer_details
required: false
schema:
properties:
address:
anyOf:
- properties:
city:
maxLength: 5000
type: string
country:
maxLength: 5000
type: string
line1:
maxLength: 5000
type: string
line2:
maxLength: 5000
type: string
postal_code:
maxLength: 5000
type: string
state:
maxLength: 5000
type: string
title: optional_fields_address
type: object
- enum:
- ''
type: string
shipping:
anyOf:
- properties:
address:
properties:
city:
maxLength: 5000
type: string
country:
maxLength: 5000
type: string
line1:
maxLength: 5000
type: string
line2:
maxLength: 5000
type: string
postal_code:
maxLength: 5000
type: string
state:
maxLength: 5000
type: string
title: optional_fields_address
type: object
name:
maxLength: 5000
type: string
phone:
maxLength: 5000
type: string
required:
- address
- name
title: customer_shipping
type: object
- enum:
- ''
type: string
tax:
properties:
ip_address:
anyOf:
- type: string
- enum:
- ''
type: string
title: tax_param
type: object
tax_exempt:
enum:
- ''
- exempt
- none
- reverse
type: string
tax_ids:
items:
properties:
type:
enum:
- ad_nrt
- ae_trn
- ar_cuit
- au_abn
- au_arn
- bg_uic
- bo_tin
- br_cnpj
- br_cpf
- ca_bn
- ca_gst_hst
- ca_pst_bc
- ca_pst_mb
- ca_pst_sk
- ca_qst
- ch_vat
- cl_tin
- cn_tin
- co_nit
- cr_tin
- do_rcn
- ec_ruc
- eg_tin
- es_cif
- eu_oss_vat
- eu_vat
- gb_vat
- ge_vat
- hk_br
- hu_tin
- id_npwp
- il_vat
- in_gst
- is_vat
- jp_cn
- jp_rn
- jp_trn
- ke_pin
- kr_brn
- li_uid
- mx_rfc
- my_frp
- my_itn
- my_sst
- no_vat
- nz_gst
- pe_ruc
- ph_tin
- ro_tin
- rs_pib
- ru_inn
- ru_kpp
- sa_vat
- sg_gst
- sg_uen
- si_tin
- sv_nit
- th_vat
- tr_tin
- tw_vat
- ua_vat
- us_ein
- uy_ruc
- ve_rif
- vn_tin
- za_vat
maxLength: 5000
type: string
x-stripeBypassValidation: true
value:
type: string
required:
- type
- value
title: data_params
type: object
type: array
title: customer_details_param
type: object
style: deepObject
- description: >-
The coupons to redeem into discounts for the invoice preview. If not
# --- truncated at 32 KB (213 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-invoice-api-openapi.yml