Stripe Tax API

openapi: 3.2.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:
    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.
        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.
        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 customer can be charged in for recurring billing purposes.
          maxLength: 5000
          type:
          - string
          - 'null'
        default_source:
          anyOf:
          - maxLength: 5000
            type: string
          - $ref: '#/components/schemas/bank_account'
          - $ref: '#/components/schemas/card'
          - $ref: '#/components/schemas/source'
          description: 'ID of the default payment source for the customer.


            If you use payment methods created through the PaymentMethods API, see the [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) field instead.'
          x-expansionResources:
            oneOf:
            - $ref: '#/components/schemas/bank_account'
            - $ref: '#/components/schemas/card'
            - $ref: '#/components/schemas/source'
          x-stripeBypassValidation: true
        delinquent:
          description: 'Tracks the most recent state change on any invoice belonging to the customer. Paying an invoice or marking it uncollectible via the API will set this field to false. An automatic payment failure or passing the `invoice.due_date` will set this field to `true`.


            If an invoice becomes uncollectible by [dunning](https://stripe.com/docs/billing/automatic-collection), `delinquent` doesn''t reset to `false`.


            If you care whether the customer has paid their most recent subscription invoice, use `subscription.status` instead. Paying or marking uncollectible any customer invoice regardless of whether it is the latest invoice for a subscription will always set this field to `false`.'
          type:
          - boolean
          - 'null'
        description:
          description: An arbitrary string attached to the object. Often useful for displaying to users.
          maxLength: 5000
          type:
          - string
          - 'null'
        discount:
          anyOf:
          - $ref: '#/components/schemas/discount'
          description: Describes the current discount active on the customer, if there is one.
        email:
          description: The customer's email address.
          maxLength: 5000
          type:
          - string
          - 'null'
        id:
          description: Unique identifier for the object.
          maxLength: 5000
          type: string
        invoice_credit_balance:
          additionalProperties:
            type: integer
          description: The current multi-currency balances, if any, that's stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that's added to their next invoice denominated in that currency. These balances don't apply to unpaid invoices. They solely track amounts that Stripe hasn't successfully applied to any invoice. Stripe only applies a balance in a specific currency to an invoice after that invoice (which is in the same currency) finalizes.
          type: object
        invoice_prefix:
          description: The prefix for the customer used to generate unique invoice numbers.
          maxLength: 5000
          type:
          - string
          - 'null'
        invoice_settings:
          $ref: '#/components/schemas/invoice_setting_customer_setting'
        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
        metadata:
          additionalProperties:
            maxLength: 500
            type: string
          description: Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
          type: object
        name:
          description: The customer's full name or business name.
          maxLength: 5000
          type:
          - string
          - 'null'
        next_invoice_sequence:
          description: The suffix of the customer's next invoice number (for example, 0001).
          type: integer
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - customer
          type: string
        phone:
          description: The customer's phone number.
          maxLength: 5000
          type:
          - string
          - 'null'
        preferred_locales:
          description: The customer's preferred locales (languages), ordered by preference.
          items:
            maxLength: 5000
            type: string
          type:
          - array
          - 'null'
        shipping:
          anyOf:
          - $ref: '#/components/schemas/shipping'
          description: Mailing and shipping address for the customer. Appears on invoices emailed to this customer.
        sources:
          description: The customer's payment sources, if any.
          properties:
            data:
              description: Details about each object.
              items:
                anyOf:
                - $ref: '#/components/schemas/bank_account'
                - $ref: '#/components/schemas/card'
                - $ref: '#/components/schemas/source'
                title: Polymorphic
                x-stripeBypassValidation: true
              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
              type: string
          required:
          - data
          - has_more
          - object
          - url
          title: ApmsSourcesSourceList
          type: object
          x-expandableFields:
          - data
        subscriptions:
          description: The customer's current subscriptions, if any.
          properties:
            data:
              description: Details about each object.
              items:
                $ref: '#/components/schemas/subscription'
              type: array
  

# --- 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