Commerce Layer tax_categories API

openapi: 3.1.0
info:
  title: Commerce Layer addresses tax_categories API
  version: 7.10.1
  contact:
    name: API Support
    url: https://commercelayer.io
    email: support@commercelayer.io
  description: Headless Commerce for Global Brands.
servers:
- url: https://{your_organization_slug}.commercelayer.io/api
  description: API
- url: https://core.commercelayer.io/users/sign_in
  description: Sign in
- url: https://docs.commercelayer.io/api
  description: API reference
security:
- bearerAuth: []
tags:
- name: tax_categories
  description: resource type
paths:
  /avalara_accounts/{avalaraAccountId}/tax_categories:
    get:
      operationId: GET/avalaraAccountId/tax_categories
      summary: Retrieve the tax categories associated to the avalara account
      description: Retrieve the tax categories associated to the avalara account
      tags:
      - tax_categories
      parameters:
      - name: avalaraAccountId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The tax_categories associated to the avalara account
  /stripe_tax_accounts/{stripeTaxAccountId}/tax_categories:
    get:
      operationId: GET/stripeTaxAccountId/tax_categories
      summary: Retrieve the tax categories associated to the stripe tax account
      description: Retrieve the tax categories associated to the stripe tax account
      tags:
      - tax_categories
      parameters:
      - name: stripeTaxAccountId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The tax_categories associated to the stripe tax account
  /tax_categories:
    get:
      operationId: GET/tax_categories
      summary: List all tax categories
      description: List all tax categories
      tags:
      - tax_categories
      responses:
        '200':
          description: A list of tax category objects
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/taxCategoryResponseList'
    post:
      operationId: POST/tax_categories
      summary: Create a tax category
      description: Create a tax category
      tags:
      - tax_categories
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/taxCategoryCreate'
      responses:
        '201':
          description: The created tax category object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/taxCategoryResponse'
  /tax_categories/{taxCategoryId}:
    get:
      operationId: GET/tax_categories/taxCategoryId
      summary: Retrieve a tax category
      description: Retrieve a tax category
      tags:
      - tax_categories
      parameters:
      - name: taxCategoryId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The tax category object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/taxCategoryResponse'
    patch:
      operationId: PATCH/tax_categories/taxCategoryId
      summary: Update a tax category
      description: Update a tax category
      tags:
      - tax_categories
      parameters:
      - name: taxCategoryId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/taxCategoryUpdate'
      responses:
        '200':
          description: The updated tax category object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/taxCategoryResponse'
    delete:
      operationId: DELETE/tax_categories/taxCategoryId
      summary: Delete a tax category
      description: Delete a tax category
      tags:
      - tax_categories
      parameters:
      - name: taxCategoryId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '204':
          description: No content
  /taxjar_accounts/{taxjarAccountId}/tax_categories:
    get:
      operationId: GET/taxjarAccountId/tax_categories
      summary: Retrieve the tax categories associated to the taxjar account
      description: Retrieve the tax categories associated to the taxjar account
      tags:
      - tax_categories
      parameters:
      - name: taxjarAccountId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The tax_categories associated to the taxjar account
components:
  schemas:
    taxCategoryUpdate:
      required:
      - data
      type: object
      properties:
        data:
          type: object
          required:
          - type
          - id
          - attributes
          properties:
            type:
              type: string
              description: The resource's type
              enum:
              - tax_categories
            id:
              type: string
              description: Unique identifier for the resource (hash).
              example: XAyRWNUzyN
            attributes:
              type: object
              properties:
                code:
                  type: string
                  description: The tax category identifier code, specific for a particular tax calculator.
                  example: '31000'
                  nullable: false
                sku_code:
                  type: string
                  description: The code of the associated SKU.
                  example: TSHIRTMM000000FFFFFFXLXX
                  nullable: true
                reference:
                  type: string
                  description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
                  example: ANY-EXTERNAL-REFEFERNCE
                  nullable: true
                reference_origin:
                  type: string
                  description: Any identifier of the third party system that defines the reference code.
                  example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
                  nullable: true
                metadata:
                  type: object
                  description: Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
                  example:
                    foo: bar
                  nullable: true
            relationships:
              type: object
              properties:
                sku:
                  required:
                  - data
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - skus
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
    taxCategoryResponseList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/taxCategoryResponse/properties/data'
    vertexAccount:
      type: object
      properties:
        data:
          type: object
          required:
          - type
          - attributes
          properties:
            type:
              type: string
              description: The resource's type
              enum:
              - vertex_accounts
            attributes:
              type: object
              properties:
                name:
                  type: string
                  description: The tax calculator's internal name.
                  example: Personal tax calculator
                  nullable: false
                type:
                  type: string
                  description: The tax calculator's type.
                  example: avalara_accounts
                  nullable: false
                  enum:
                  - avalara_accounts
                  - stripe_tax_accounts
                  - vertex_accounts
                  - taxjar_accounts
                  - manual_tax_calculators
                  - external_tax_calculators
                created_at:
                  type: string
                  description: Time at which the resource was created.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: false
                updated_at:
                  type: string
                  description: Time at which the resource was last updated.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: false
                reference:
                  type: string
                  description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
                  example: ANY-EXTERNAL-REFEFERNCE
                  nullable: true
                reference_origin:
                  type: string
                  description: Any identifier of the third party system that defines the reference code.
                  example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
                  nullable: true
                metadata:
                  type: object
                  description: Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
                  example:
                    foo: bar
                  nullable: true
                kind:
                  type: string
                  description: The Vertex account kind. One of 'cloud', 'on_demand', or 'on_premise'.
                  example: cloud
                  nullable: true
                  enum:
                  - cloud
                  - on_demand
                  - on_premise
                baseurl:
                  type: string
                  description: The Vertex API baseurl, optional for 'cloud' kind.
                  example: yourbaseurl
                  nullable: true
                api_endpoint:
                  type: string
                  description: The API endpoint as computed by specified kind and baseurl.
                  example: https://my_baseurl.ondemand.vertexinc.com
                  nullable: true
                commit_invoice:
                  type: boolean
                  description: Indicates if the transaction will be recorded and visible on the Vertex website.
                  example: true
                  nullable: true
                token_expires_at:
                  type: string
                  description: The expiration date/time of the access token.
                  example: '2018-01-02T12:00:00.000Z'
                  nullable: true
            relationships:
              type: object
              properties:
                markets:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - markets
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                attachments:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - attachments
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                events:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - events
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                event_stores:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - event_stores
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
    taxCategoryResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              description: Unique identifier for the resource (hash).
              example: XAyRWNUzyN
            type:
              type: string
              description: The resource's type
              enum:
              - tax_categories
            links:
              type: object
              properties:
                self:
                  type: string
                  description: URL
            attributes:
              $ref: '#/components/schemas/taxCategory/properties/data/properties/attributes'
            relationships:
              type: object
              properties:
                sku:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - sku
                        id:
                          type: string
                          description: The resource ID
                tax_calculator:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - tax_calculator
                        id:
                          type: string
                          description: The resource ID
                attachments:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - attachments
                        id:
                          type: string
                          description: The resource ID
                event_stores:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - event_stores
                        id:
                          type: string
                          description: The resource ID
    taxCategory:
      properties:
        data:
          properties:
            attributes:
              type: object
              properties:
                code:
                  type: string
                  description: The tax category identifier code, specific for a particular tax calculator.
                  example: '31000'
                  nullable: false
                sku_code:
                  type: string
                  description: The code of the associated SKU.
                  example: TSHIRTMM000000FFFFFFXLXX
                  nullable: true
                created_at:
                  type: string
                  description: Time at which the resource was created.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: false
                updated_at:
                  type: string
                  description: Time at which the resource was last updated.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: false
                reference:
                  type: string
                  description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
                  example: ANY-EXTERNAL-REFEFERNCE
                  nullable: true
                reference_origin:
                  type: string
                  description: Any identifier of the third party system that defines the reference code.
                  example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
                  nullable: true
                metadata:
                  type: object
                  description: Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
                  example:
                    foo: bar
                  nullable: true
    taxCategoryCreate:
      required:
      - data
      type: object
      properties:
        data:
          type: object
          required:
          - type
          - attributes
          properties:
            type:
              type: string
              description: The resource's type
              enum:
              - tax_categories
            attributes:
              type: object
              properties:
                code:
                  type: string
                  description: The tax category identifier code, specific for a particular tax calculator.
                  example: '31000'
                sku_code:
                  type: string
                  description: The code of the associated SKU.
                  example: TSHIRTMM000000FFFFFFXLXX
                reference:
                  type: string
                  description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
                  example: ANY-EXTERNAL-REFEFERNCE
                reference_origin:
                  type: string
                  description: Any identifier of the third party system that defines the reference code.
                  example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
                metadata:
                  type: object
                  description: Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
                  example:
                    foo: bar
              required:
              - code
            relationships:
              type: object
              properties:
                sku:
                  required:
                  - data
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - skus
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                tax_calculator:
                  required:
                  - data
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - avalara_accounts
                          - stripe_tax_accounts
                          - vertex_accounts
                          - taxjar_accounts
                          - manual_tax_calculators
                          - external_tax_calculators
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                  oneOf:
                  - $ref: '#/components/schemas/avalaraAccount'
                  - $ref: '#/components/schemas/stripeTaxAccount'
                  - $ref: '#/components/schemas/vertexAccount'
                  - $ref: '#/components/schemas/taxjarAccount'
                  - $ref: '#/components/schemas/manualTaxCalculator'
                  - $ref: '#/components/schemas/externalTaxCalculator'
              required:
              - sku
              - tax_calculator
    stripeTaxAccount:
      type: object
      properties:
        data:
          type: object
          required:
          - type
          - attributes
          properties:
            type:
              type: string
              description: The resource's type
              enum:
              - stripe_tax_accounts
            attributes:
              type: object
              properties:
                name:
                  type: string
                  description: The tax calculator's internal name.
                  example: Personal tax calculator
                  nullable: false
                type:
                  type: string
                  description: The tax calculator's type.
                  example: avalara_accounts
                  nullable: false
                  enum:
                  - avalara_accounts
                  - stripe_tax_accounts
                  - vertex_accounts
                  - taxjar_accounts
                  - manual_tax_calculators
                  - external_tax_calculators
                created_at:
                  type: string
                  description: Time at which the resource was created.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: false
                updated_at:
                  type: string
                  description: Time at which the resource was last updated.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: false
                reference:
                  type: string
                  description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
                  example: ANY-EXTERNAL-REFEFERNCE
                  nullable: true
                reference_origin:
                  type: string
                  description: Any identifier of the third party system that defines the reference code.
                  example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
                  nullable: true
                metadata:
                  type: object
                  description: Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
                  example:
                    foo: bar
                  nullable: true
                commit_invoice:
                  type: boolean
                  description: Indicates if the transaction will be recorded and visible on the Stripe website.
                  example: true
                  nullable: true
            relationships:
              type: object
              properties:
                markets:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - markets
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                attachments:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - attachments
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                events:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - events
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                event_stores:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - event_stores
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                tax_categories:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - tax_categories
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
    externalTaxCalculator:
      type: object
      properties:
        data:
          type: object
          required:
          - type
          - attributes
          properties:
            type:
              type: string
              description: The resource's type
              enum:
              - external_tax_calculators
            attributes:
              type: object
              properties:
                name:
                  type: string
                  description: The tax calculator's internal name.
                  example: Personal tax calculator
                  nullable: false
                type:
                  type: string
                  description: The tax calculator's type.
                  example: avalara_accounts
                  nullable: false
                  enum:
                  - avalara_accounts
                  - stripe_tax_accounts
                  - vertex_accounts
                  - taxjar_accounts
                  - manual_tax_calculators
                  - external_tax_calculators
                created_at:
                  type: string
                  description: Time at which the resource was created.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: false
                updated_at:
                  type: string
                  description: Time at which the resource was last updated.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: false
                reference:
                  type: string
                  description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
                  example: ANY-EXTERNAL-REFEFERNCE
                  nullable: true
                reference_origin:
                  type: string
                  description: Any identifier of the third party system that defines the reference code.
                  example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
                  nullable: true
                metadata:
                  type: object
                  description: Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
                  example:
                    foo: bar
                  nullable: true
                circuit_state:
                  type: string
                  description: The circuit breaker state, by default it is 'closed'. It can become 'open' once the number of consecutive failures overlaps the specified threshold, in such case no further calls to the failing callback are made.
                  example: closed
                  nullable: true
                circuit_failure_count:
                  type: integer
                  description: The number of consecutive failures recorded by the circuit breaker associated to this resource, will be reset on first successful call to callback.
                  example: 5
                  null

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/commerce-layer/refs/heads/main/openapi/commerce-layer-tax-categories-api-openapi.yml