Invoices are statements of amounts owed by a customer, and are either generated one-off, or generated periodically from a subscription.
openapi: 3.0.0
info:
title: Stripe Accounts Account Invoice 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: Invoice
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:
- Invoice
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
/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:
- Invoice
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:
- Invoice
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
/v1/invoices/{invoice}:
delete:
description: <p>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 <a href="#void_invoice">voided</a>.</p>
operationId: deleteInvoicesInvoice
parameters:
- in: path
name: invoice
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/DeleteInvoicesInvoiceRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/deleted_invoice'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Delete Invoices Invoice
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Invoice
get:
description: <p>Retrieves the invoice with the given ID.</p>
operationId: getInvoicesInvoice
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: invoice
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetInvoicesInvoiceRequest'
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 Get Invoices Invoice
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Invoice
post:
description: '<p>Draft invoices are fully editable. Once an invoice is <a href="/docs/billing/invoices/workflow#finalized">finalized</a>,
monetary values, as well as <code>collection_method</code>, become uneditable.</p>
<p>If you would like to stop the Stripe Billing engine from automatically finalizing, reattempting payments on,
sending reminders for, or <a href="/docs/billing/invoices/reconciliation">automatically reconciling</a> invoices, pass
<code>auto_advance=false</code>.</p>'
operationId: postInvoicesInvoice
parameters:
- in: path
name: invoice
required: true
schema:
maxLength: 5000
type: string
style: simple
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_source:
explode: true
style: deepObject
default_tax_rates:
explode: true
style: deepObject
discounts:
explode: true
style: deepObject
effective_at:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
on_behalf_of:
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/PostInvoicesInvoiceRequest'
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 Invoice
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Invoice
/v1/invoices/{invoice}/finalize:
post:
description: <p>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.</p>
operationId: postInvoicesInvoiceFinalize
parameters:
- in: path
name: invoice
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostInvoicesInvoiceFinalizeRequest'
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 Invoice Finalize
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Invoice
/v1/invoices/{invoice}/lines:
get:
description: <p>When retrieving an invoice, you’ll get a <strong>lines</strong> 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.</p>
operationId: getInvoicesInvoiceLines
parameters:
- 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
- in: path
name: invoice
required: true
schema:
maxLength: 5000
type: string
style: simple
- 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
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetInvoicesInvoiceLinesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/InvoiceLinesList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Invoices Invoice Lines
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Invoice
/v1/invoices/{invoice}/lines/{line_item_id}:
post:
description: '<p>Updates an invoice’s line item. Some fields, such as <code>tax_amounts</code>, only live on the invoice line item,
so they can only be updated through this endpoint. Other fields, such as <code>amount</code>, 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.</p>'
operationId: postInvoicesInvoiceLinesLineItemId
parameters:
- description: Invoice ID of line item
in: path
name: invoice
required: true
schema:
maxLength: 5000
type: string
style: simple
- description: Invoice line item ID
in: path
name: line_item_id
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_amounts:
explode: true
style: deepObject
tax_rates:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostInvoicesInvoiceLinesLineItemIdRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/line_item'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Invoices Invoice Lines Line Item Id
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Invoice
/v1/invoices/{invoice}/mark_uncollectible:
post:
description: <p>Marking an invoice as uncollectible is useful for keeping track of bad debts that can be written off for accounting purposes.</p>
operationId: postInvoicesInvoiceMarkUncollectible
parameters:
- in: path
name: invoice
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostInvoicesInvoiceMarkUncollectibleRequest'
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 Invoice Mark Uncollectible
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Invoice
/v1/invoices/{invoice}/pay:
post:
description: <p>Stripe automatically creates and then attempts to collect payment on invoices for customers on subscriptions according to your <a href="https://dashboard.stripe.com/account/billing/automatic">subscriptions settings</a>. 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.</p>
operationId: postInvoicesInvoicePay
parameters:
- in: path
name: invoice
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
mandate:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostInvoicesInvoicePayRequest'
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 Invoice Pay
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Invoice
/v1/invoices/{invoice}/send:
post:
description: '<p>Stripe will automatically send invoices to customers according to your <a href="https://dashboard.stripe.com/account/billing/automatic">subscriptions settings</a>. 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.</p>
<p>Requests made in test-mode result in no emails being sent, despite sending an <code>invoice.sent</code> event.</p>'
operationId: postInvoicesInvoiceSend
parameters:
- in: path
name: invoice
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostInvoicesInvoiceSendRequest'
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 Invoice Send
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Invoice
/v1/invoices/{invoice}/void:
post:
description: <p>Mark a finalized invoice as void. This cannot be undone. Voiding an invoice is similar to <a href="#delete_invoice">deletion</a>, however it only applies to finalized invoices and maintains a papertrail where the invoice can still be found.</p>
operationId: postInvoicesInvoiceVoid
parameters:
- in: path
name: invoice
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostInvoicesInvoiceVoidRequest'
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 Invoice Void
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Invoice
components:
schemas:
PostInvoicesInvoiceSendRequest:
type: object
properties:
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
PostInvoicesInvoiceVoidRequest:
type: object
properties:
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
line_item:
description: ''
properties:
amount:
description: The amount, in cents (or local equivalent).
type: integer
amount_excluding_tax:
description: The integer amount in cents (or local equivalent) representing the amount for this line item, excluding all tax and discounts.
nullable: true
type: integer
currency:
description: Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
type: string
description:
description: An arbitrary string attached to the object. Often useful for displaying to users.
maxLength: 5000
nullable: true
type: string
discount_amounts:
description: The amount of discount calculated per discount for this line item.
items:
$ref: '#/components/schemas/discounts_resource_discount_amount'
nullable: true
type: array
discountable:
description: If true, discounts will apply to this line item. Always false for prorations.
type: boolean
discounts:
description: The discounts applied to the invoice line item. Line item discounts are applied be
# --- truncated at 32 KB (116 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-invoice-api-openapi.yml