openapi: 3.0.0
info:
  title: Stripe Accounts Account Tax Rates 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 Rates
paths:
  /v1/tax_rates:
    get:
      description: <p>Returns a list of your tax rates. Tax rates are returned sorted by creation date, with the most recently created tax rates appearing first.</p>
      operationId: GetTaxRates
      parameters:
      - description: Optional flag to filter by tax rates that are either active or inactive (archived).
        in: query
        name: active
        required: false
        schema:
          type: boolean
        style: form
      - description: Optional range for filtering created date.
        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: 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: Optional flag to filter by tax rates that are inclusive (or those that are not inclusive).
        in: query
        name: inclusive
        required: false
        schema:
          type: boolean
        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: 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/GetTaxRatesRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                - data
                $ref: '#/components/schemas/TaxRatesList'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Tax Rates
    post:
      description: <p>Creates a new tax rate.</p>
      operationId: PostTaxRates
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostTaxRatesRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tax_rate'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Tax Rates
  /v1/tax_rates/{tax_rate}:
    get:
      description: <p>Retrieves a tax rate with the given ID</p>
      operationId: GetTaxRatesTaxRate
      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: tax_rate
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetTaxRatesTaxRateRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tax_rate'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Tax Rates
    post:
      description: <p>Updates an existing tax rate.</p>
      operationId: PostTaxRatesTaxRate
      parameters:
      - in: path
        name: tax_rate
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostTaxRatesTaxRateRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tax_rate'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Tax Rates
components:
  schemas:
    PostTaxRatesRequest:
      type: object
      required:
      - display_name
      - inclusive
      - percentage
      properties:
        active:
          description: Flag determining whether the tax rate is active or inactive (archived). Inactive tax rates cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set.
          type: boolean
        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
        description:
          description: An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers.
          maxLength: 5000
          type: string
        display_name:
          description: The display name of the tax rate, which will be shown to users.
          maxLength: 50
          type: string
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
        inclusive:
          description: This specifies if the tax rate is inclusive or exclusive.
          type: boolean
        jurisdiction:
          description: The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer’s invoice.
          maxLength: 50
          type: string
        metadata:
          additionalProperties:
            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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
          type: object
        percentage:
          description: This represents the tax rate percent out of 100.
          type: number
        state:
          description: '[ISO 3166-2 subdivision code](https://en.wikipedia.org/wiki/ISO_3166-2:US), without country prefix. For example, "NY" for New York, United States.'
          maxLength: 2
          type: string
        tax_type:
          description: The high-level tax type, such as `vat` or `sales_tax`.
          enum:
          - amusement_tax
          - communications_tax
          - gst
          - hst
          - igst
          - jct
          - lease_tax
          - pst
          - qst
          - rst
          - sales_tax
          - service_tax
          - vat
          type: string
    GetTaxRatesRequest:
      type: object
      properties: {}
    error:
      description: An error response from the Stripe API
      properties:
        error:
          $ref: '#/components/schemas/api_errors'
      required:
      - error
      type: object
    PostTaxRatesTaxRateRequest:
      type: object
      properties:
        active:
          description: Flag determining whether the tax rate is active or inactive (archived). Inactive tax rates cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set.
          type: boolean
        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
        description:
          description: An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers.
          maxLength: 5000
          type: string
        display_name:
          description: The display name of the tax rate, which will be shown to users.
          maxLength: 50
          type: string
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
        jurisdiction:
          description: The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer’s invoice.
          maxLength: 50
          type: string
        metadata:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - enum:
            - ''
            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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
        state:
          description: '[ISO 3166-2 subdivision code](https://en.wikipedia.org/wiki/ISO_3166-2:US), without country prefix. For example, "NY" for New York, United States.'
          maxLength: 2
          type: string
        tax_type:
          description: The high-level tax type, such as `vat` or `sales_tax`.
          enum:
          - amusement_tax
          - communications_tax
          - gst
          - hst
          - igst
          - jct
          - lease_tax
          - pst
          - qst
          - rst
          - sales_tax
          - service_tax
          - vat
          type: string
    TaxRatesList:
      type: object
      required:
      - data
      - has_more
      - object
      - url
      properties:
        data:
          items:
            $ref: '#/components/schemas/tax_rate'
          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_rates
          type: string
    tax_rate:
      description: 'Tax rates can be applied to [invoices](https://stripe.com/docs/billing/invoices/tax-rates), [subscriptions](https://stripe.com/docs/billing/subscriptions/taxes) and [Checkout Sessions](https://stripe.com/docs/payments/checkout/set-up-a-subscription#tax-rates) to collect tax.


        Related guide: [Tax rates](https://stripe.com/docs/billing/taxes/tax-rates)'
      properties:
        active:
          description: Defaults to `true`. When set to `false`, this tax rate cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set.
          type: boolean
        country:
          description: Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
          maxLength: 5000
          nullable: true
          type: string
        created:
          description: Time at which the object was created. Measured in seconds since the Unix epoch.
          format: unix-time
          type: integer
        description:
          description: An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers.
          maxLength: 5000
          nullable: true
          type: string
        display_name:
          description: The display name of the tax rates as it will appear to your customer on their receipt email, PDF, and the hosted invoice page.
          maxLength: 5000
          type: string
        effective_percentage:
          description: 'Actual/effective tax rate percentage out of 100. For tax calculations with automatic_tax[enabled]=true,

            this percentage reflects the rate actually used to calculate tax based on the product''s taxability

            and whether the user is registered to collect taxes in the corresponding jurisdiction.'
          nullable: true
          type: number
        id:
          description: Unique identifier for the object.
          maxLength: 5000
          type: string
        inclusive:
          description: This specifies if the tax rate is inclusive or exclusive.
          type: boolean
        jurisdiction:
          description: The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer’s invoice.
          maxLength: 5000
          nullable: true
          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
        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.
          nullable: true
          type: object
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - tax_rate
          type: string
        percentage:
          description: Tax rate percentage out of 100. For tax calculations with automatic_tax[enabled]=true, this percentage includes the statutory tax rate of non-taxable jurisdictions.
          type: number
        state:
          description: '[ISO 3166-2 subdivision code](https://en.wikipedia.org/wiki/ISO_3166-2:US), without country prefix. For example, "NY" for New York, United States.'
          maxLength: 5000
          nullable: true
          type: string
        tax_type:
          description: The high-level tax type, such as `vat` or `sales_tax`.
          enum:
          - amusement_tax
          - communications_tax
          - gst
          - hst
          - igst
          - jct
          - lease_tax
          - pst
          - qst
          - rst
          - sales_tax
          - service_tax
          - vat
          nullable: true
          type: string
      required:
      - active
      - created
      - display_name
      - id
      - inclusive
      - livemode
      - object
      - percentage
      title: TaxRate
      type: object
      x-expandableFields: []
      x-resourceId: tax_rate
    GetTaxRatesTaxRateRequest:
      type: object
      properties: {}