openapi: 3.0.0
info:
title: Stripe Accounts Account Invoices API
description: 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.
contact:
email: dev-platform@stripe.com
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Invoices
paths:
/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.
tags:
- 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.
tags:
- Invoices
/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.
tags:
- Invoices
/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 specified, inherits the discount from the customer or subscription. This only works for coupons directly applied to the invoice. To apply a coupon to a subscription, you must use the `coupon` parameter instead. Pass an empty string to avoid inheriting any discounts. To preview the upcoming invoice for a subscription that hasn't been created, use `coupon` instead.
explode: true
in: query
name: discounts
required: false
schema:
anyOf:
- items:
properties:
coupon:
maxLength: 5000
type: string
discount:
maxLength: 5000
type: string
title: discounts_data_param
type: object
type: array
- enum:
- ''
type: string
style: deepObject
- 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: List of invoice items to add or update in the upcoming invoice preview.
explode: true
in: query
name: invoice_items
required: false
schema:
items:
properties:
amount:
type: integer
currency:
type: string
description:
maxLength: 5000
type: string
discountable:
type: boolean
discounts:
anyOf:
- items:
properties:
coupon:
maxLength: 5000
type: string
discount:
maxLength: 5000
type: string
title: discounts_data_param
type: object
type: array
- enum:
- ''
type: string
invoiceitem:
maxLength: 5000
type: string
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- enum:
- ''
type: string
period:
properties:
end:
format: unix-time
type: integer
start:
format: unix-time
type: integer
required:
- end
- start
title: period
type: object
price:
maxLength: 5000
type: string
price_data:
properties:
currency:
type: string
product:
maxLength: 5000
type: string
tax_behavior:
enum:
- exclusive
- inclusive
- unspecified
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
required:
- currency
- product
title: one_time_price_data
type: object
quantity:
type: integer
tax_behavior:
enum:
- exclusive
- inclusive
- unspecified
type: string
tax_code:
anyOf:
- type: string
- enum:
- ''
type: string
tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
title: invoice_item_preview_params
type: object
type: array
style: deepObject
- description: The identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields.
in: query
name: schedule
required: false
schema:
maxLength: 5000
type: string
style: form
- description: 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.
in: query
name: subscription
required: false
schema:
maxLength: 5000
type: string
style: form
- description: For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to `now` or `unchanged`.
explode: true
in: query
name: subscription_billing_cycle_anchor
required: false
schema:
anyOf:
- enum:
- now
- unchanged
maxLength: 5000
type: string
- format: unix-time
type: integer
style: deepObject
- description: A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period.
explode: true
in: query
name: subscription_cancel_at
required: false
schema:
anyOf:
- format: unix-time
type: integer
- enum:
- ''
type: string
style: deepObject
- description: Boolean indicating whether this subscription should cancel at the end of the current period.
in: query
name: subscription_cancel_at_period_end
required: false
schema:
type: boolean
style: form
- description: This simulates the subscription being canceled or expired immediately.
in: query
name: subscription_cancel_now
required: false
schema:
type: boolean
style: form
- description: If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have `tax_rates` set.
explode: true
in: query
name: subscription_default_tax_rates
required: false
schema:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
style: deepObject
- description: A list of up to 20 subscription items, each with an attached price.
explode: true
in: query
name: subscription_items
required: false
schema:
items:
properties:
billing_thresholds:
anyOf:
- properties:
usage_gte:
type: integer
required:
- usage_gte
title: item_billing_thresholds_param
type: object
- enum:
- ''
type: string
clear_usage:
type: boolean
deleted:
type: boolean
id:
maxLength: 5000
type: string
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- enum:
- ''
type: string
price:
maxLength: 5000
type: string
price_data:
properties:
currency:
type: string
product:
maxLength: 5000
type: string
recurring:
properties:
interval:
enum:
- day
- month
- week
- year
type: string
interval_count:
type: integer
required:
- interval
title: recurring_adhoc
type: object
tax_behavior:
enum:
- exclusive
- inclusive
- unspecified
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
required:
- currency
- product
- recurring
title: recurring_price_data
type: object
quantity:
type: integer
tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
title: subscription_item_update_params
type: object
type: array
style: deepObject
- description: Determines how to handle [prorations](https://stripe.com/docs/subscriptions/billing-cycle#prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`.
in: query
name: subscription_proration_behavior
required: false
schema:
enum:
- always_invoice
- create_prorations
- none
type: string
style: form
- description: If previewing an update to a subscription, and doing proration, `subscription_proration_date` forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, `subscription`, and one of `subscription_items`, or `subscription_trial_end` are required. Also, `subscription_proration_behavior` cannot be set to 'none'.
in: query
name: subscription_proration_date
required: false
schema:
format: unix-time
type: integer
style: form
- description: For paused subscriptions, setting `subscription_resume_at` to `now` will preview the invoice that will be generated if the subscription is resumed.
in: query
name: subscription_resume_at
required: false
schema:
enum:
- now
maxLength: 5000
type: string
style: form
- description: Date a subscription is intended to start (can be future or past).
in: query
name: subscription_start_date
required: false
schema:
format: unix-time
type: integer
style: form
- description: If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of `subscription_items` or `subscription` is required.
explode: true
in: query
name: subscription_trial_end
required: false
schema:
anyOf:
- enum:
- now
maxLength: 5000
type: string
- format: unix-time
type: integer
style: deepObject
- description: Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `subscription_trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `subscription_trial_end` is not allowed. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more.
in: query
name: subscription_trial_from_plan
required: false
schema:
type: boolean
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetInvoicesUpcomingRequest'
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.
tags:
- I
# --- truncated at 32 KB (166 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-invoices-api-openapi.yml