Stripe Tax API
Automate sales tax, VAT, and GST compliance on all your transactions-low or no code integrations available.
OpenAPI Specification
openapi: 3.0.0
info:
title: Stripe Accounts Account Tax 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: Tax
paths:
/v1/customers/{customer}/tax_ids:
get:
description: <p>Returns a list of tax IDs for a customer.</p>
operationId: getCustomersCustomerTaxIds
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- 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
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCustomersCustomerTaxIdsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/TaxIDsList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Customers Customer Tax Ids
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Tax
post:
description: <p>Creates a new <code>tax_id</code> object for a customer.</p>
operationId: postCustomersCustomerTaxIds
parameters:
- in: path
name: customer
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/PostCustomersCustomerTaxIdsRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/tax_id'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Customers Customer Tax Ids
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Tax
/v1/customers/{customer}/tax_ids/{id}:
delete:
description: <p>Deletes an existing <code>tax_id</code> object.</p>
operationId: deleteCustomersCustomerTaxIdsId
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- in: path
name: id
required: true
schema:
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/DeleteCustomersCustomerTaxIdsIdRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/deleted_tax_id'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Delete Customers Customer Tax Ids Id
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Tax
get:
description: <p>Retrieves the <code>tax_id</code> object with the given identifier.</p>
operationId: getCustomersCustomerTaxIdsId
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- 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: id
required: true
schema:
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCustomersCustomerTaxIdsIdRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/tax_id'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Customers Customer Tax Ids Id
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Tax
/v1/tax/calculations:
post:
summary: Stripe Create Tax Calculation
description: <p>Calculates tax based on input and returns a Tax Calculation object.</p>
operationId: PostTaxCalculations
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- currency
- line_items
properties:
currency:
type: string
description: Three-letter ISO currency code.
customer:
type: string
maxLength: 5000
customer_details:
type: object
properties:
address:
type: object
address_source:
type: string
enum:
- billing
- shipping
ip_address:
type: string
tax_ids:
type: array
items:
type: object
taxability_override:
type: string
enum:
- customer_exempt
- none
- reverse_charge
line_items:
type: array
items:
type: object
properties:
amount:
type: integer
product:
type: string
quantity:
type: integer
reference:
type: string
tax_behavior:
type: string
enum:
- exclusive
- inclusive
tax_code:
type: string
shipping_cost:
type: object
properties:
amount:
type: integer
shipping_rate:
type: string
tax_behavior:
type: string
tax_code:
type: string
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/tax.calculation'
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error_2'
tags:
- Tax
/v1/tax/calculations/{calculation}/line_items:
get:
summary: Stripe List Tax Calculation Line Items
description: <p>Retrieves the line items of a tax calculation.</p>
operationId: GetTaxCalculationsCalculationLineItems
parameters:
- name: calculation
in: path
required: true
schema:
type: string
maxLength: 5000
- name: ending_before
in: query
required: false
schema:
type: string
- name: limit
in: query
required: false
schema:
type: integer
- name: starting_after
in: query
required: false
schema:
type: string
responses:
'200':
description: Successful response.
content:
application/json:
schema:
type: object
properties:
object:
type: string
enum:
- list
data:
type: array
items:
type: object
has_more:
type: boolean
url:
type: string
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error_2'
tags:
- Tax
/v1/tax/transactions/create_from_calculation:
post:
summary: Stripe Create Tax Transaction from Calculation
description: <p>Creates a Tax Transaction from a calculation.</p>
operationId: PostTaxTransactionsCreateFromCalculation
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- calculation
- reference
properties:
calculation:
type: string
maxLength: 5000
reference:
type: string
maxLength: 500
metadata:
type: object
additionalProperties:
type: string
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/tax.transaction'
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error_2'
tags:
- Tax
/v1/tax/transactions/create_reversal:
post:
summary: Stripe Create Tax Transaction Reversal
description: <p>Partially or fully reverses a previously created Transaction.</p>
operationId: PostTaxTransactionsCreateReversal
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- mode
- original_transaction
- reference
properties:
mode:
type: string
enum:
- full
- partial
original_transaction:
type: string
maxLength: 5000
reference:
type: string
maxLength: 500
line_items:
type: array
items:
type: object
properties:
amount:
type: integer
amount_tax:
type: integer
original_line_item:
type: string
metadata:
type: object
additionalProperties:
type: string
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/tax.transaction'
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error_2'
tags:
- Tax
/v1/tax/transactions/{transaction}:
get:
summary: Stripe Retrieve Tax Transaction
description: <p>Retrieves a Tax Transaction object.</p>
operationId: GetTaxTransactionsTransaction
parameters:
- name: transaction
in: path
required: true
schema:
type: string
maxLength: 5000
- name: expand
in: query
required: false
explode: true
schema:
type: array
items:
type: string
maxLength: 5000
style: deepObject
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/tax.transaction'
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error_2'
tags:
- Tax
/v1/tax/registrations:
get:
summary: Stripe List Tax Registrations
description: <p>Returns a list of Tax Registration objects.</p>
operationId: GetTaxRegistrations
parameters:
- name: status
in: query
required: false
schema:
type: string
enum:
- active
- all
- expired
- scheduled
- name: ending_before
in: query
required: false
schema:
type: string
- name: limit
in: query
required: false
schema:
type: integer
- name: starting_after
in: query
required: false
schema:
type: string
responses:
'200':
description: Successful response.
content:
application/json:
schema:
type: object
properties:
object:
type: string
enum:
- list
data:
type: array
items:
$ref: '#/components/schemas/tax.registration'
has_more:
type: boolean
url:
type: string
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error_2'
tags:
- Tax
post:
summary: Stripe Create Tax Registration
description: <p>Creates a new Tax Registration object.</p>
operationId: PostTaxRegistrations
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- active_from
- country
- country_options
properties:
active_from:
type: string
country:
type: string
country_options:
type: object
expires_at:
type: integer
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/tax.registration'
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error_2'
tags:
- Tax
/v1/tax/settings:
get:
summary: Stripe Retrieve Tax Settings
description: <p>Retrieves Tax Settings for a merchant.</p>
operationId: GetTaxSettings
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/tax.settings'
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error_2'
tags:
- Tax
post:
summary: Stripe Update Tax Settings
description: <p>Updates Tax Settings parameters used in tax calculations.</p>
operationId: PostTaxSettings
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
defaults:
type: object
properties:
tax_behavior:
type: string
enum:
- exclusive
- inclusive
- inferred_by_currency
tax_code:
type: string
head_office:
type: object
properties:
address:
type: object
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/tax.settings'
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error_2'
tags:
- Tax
/v1/tax/registrations/{id}:
post:
description: '<p>Updates an existing Tax <code>Registration</code> object.</p>
<p>A registration cannot be deleted after it has been created. If you wish to end a registration you may do so by setting <code>expires_at</code>.</p>'
operationId: PostTaxRegistrationsId
parameters:
- in: path
name: id
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
active_from:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
expires_at:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostTaxRegistrationsIdRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/tax.registration_2'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Tax
/v1/tax/transactions/{transaction}/line_items:
get:
description: <p>Retrieves the line items of a committed standalone transaction as a collection.</p>
operationId: GetTaxTransactionsTransactionLineItems
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: 500
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: 500
type: string
style: form
- in: path
name: transaction
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetTaxTransactionsTransactionLineItemsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/TaxProductResourceTaxTransactionLineItemList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Tax
components:
schemas:
GetCustomersCustomerTaxIdsRequest:
type: object
properties: {}
error_2:
type: object
properties:
error:
type: object
properties:
type:
type: string
message:
type: string
code:
type: string
param:
type: string
tax.registration:
type: object
properties:
id:
type: string
maxLength: 5000
object:
type: string
enum:
- tax.registration
active_from:
type: integer
country:
type: string
country_options:
type: object
created:
type: integer
expires_at:
type:
- integer
- 'null'
livemode:
type: boolean
status:
type: string
enum:
- active
- expired
- scheduled
required:
- id
- object
- active_from
- country
- country_options
- created
- livemode
- status
GetCustomersCustomerTaxIdsIdRequest:
type: object
properties: {}
tax.registration_2:
description: '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](https://stripe.com/docs/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](https://stripe.com/docs/tax/registering).
Related guide: [Using the Registrations API](https://stripe.com/docs/tax/registrations-api)'
properties:
active_from:
description: Time at which the registration becomes active. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
country:
description: Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
maxLength: 5000
type: string
country_options:
$ref: '#/components/schemas/tax_product_registrations_resource_country_options'
created:
description: Time at which the object was created. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
expires_at:
description: If set, the registration stops being active at this time. If not set, the registration will be active indefinitely. Measured in seconds since the Unix epoch.
format: unix-time
nullable: true
type: integer
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
livemode:
description: Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
type: boolean
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- tax.registration
type: string
status:
description: The status of the registration. This field is present for convenience and can be deduced from `active_from` and `expires_at`.
enum:
- active
- expired
- scheduled
type: string
required:
- active_from
- country
- country_options
- created
- id
- livemode
- object
- status
title: TaxProductRegistrationsResourceTaxRegistration
type: object
x-expandableFields:
- country_options
x-resourceId: tax.registration
PostTaxRegistrationsIdRequest:
type: object
properties:
active_from:
anyOf:
- enum:
- now
maxLength: 5000
type: string
- format: unix-time
type: integer
description: Time at which the registration becomes active. It can be either `now` to indicate the current time, or a timestamp measured in seconds since the Unix epoch.
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
expires_at:
anyOf:
- enum:
- now
maxLength: 5000
type: string
- format: unix-time
type: integer
- enum:
- ''
type: string
description: If set, the registration stops being active at this time. If not set, the registration will be active indefinitely. It can be either `now` to indicate the current time, or a timestamp measured in seconds since the Unix epoch.
deleted_customer:
description: ''
properties:
deleted:
description: Always true for a deleted object
enum:
- true
type: boolean
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- customer
type: string
required:
- deleted
- id
- object
title: DeletedCustomer
type: object
x-expandableFields: []
x-resourceId: deleted_customer
TaxProductResourceTaxTransactionLineItemList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
description: Details about each object.
items:
$ref: '#/components/schemas/tax.transaction_line_item'
type: array
has_more:
description: True if this list has another page of items after this one that can be fetched.
type: boolean
object:
description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
pattern: ^/v1/tax/transactions/[^/]+/line_items
type: string
customer:
description: '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](https://stripe.com/docs/payments/save-during-payment)'
properties:
address:
anyOf:
- $ref: '#/components/schemas/address'
description: The customer's address.
nullable: true
balance:
description: The current balance, if any, that's stored on the customer. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that's added to their next invoice. The balance only considers amounts that Stripe hasn't successfully applied to any invoice. It doesn't reflect unpaid invoices. This balance is only taken into account after invoices finalize.
type: integer
cash_balance:
anyOf:
- $ref: '#/components/schemas/cash_balance'
description: The current funds being held by Stripe on behalf of the customer. You can apply these funds towards payment intents when the source is "cash_balance". The `settings[reconciliation_mode]` field describes if these funds apply to these payment intents manually or automatically.
nullable: true
created:
description: Time at which the object was created. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
currency:
description: Three-letter [ISO code for the currency](https://stripe.com/docs/currencies) the cu
# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-tax-api-openapi.yml