Tax Categories

Tax Categories define how products are to be taxed in different countries.

Representations

TaxCategory

  • id - String
    The unique ID of the category.
  • key - String - Optional
    User-specific unique identifier for the category.
  • version - Number
    The current version of the category.
  • createdAt - DateTime
  • createdBy - CreatedBy beta
    Present on resources created after 1/02/2019 except for events not tracked.
  • lastModifiedAt - DateTime
  • lastModifiedBy - LastModifiedBy beta
    Present on resources updated after 1/02/2019 except for events not tracked.
  • name - String
  • description - String - Optional
  • rates - Array of TaxRate
    The tax rates have unique IDs in the rates list

TaxCategoryDraft

TaxCategoryDrafts are sent with Create TaxCategory requests.

  • name - String - Required
  • key - String - Optional
  • description - String - Optional
  • rates - Array of TaxRateDraft

TaxRate

  • id - String - Optional
    The ID is always set if the tax rate is part of a TaxCategory. The external tax rates in a Cart do not contain an id.
  • name - String
  • amount - Number Percentage in the range of [0..1]. The sum of the amounts of all subRates, if there are any.
  • includedInPrice - Boolean
  • country - String
    A two-digit country code as per ↗ ISO 3166-1 alpha-2 .
  • state - String - Optional
    The state in the country
  • subRates - Array of SubRate
    For countries (e.g. the US) where the total tax is a combination of multiple taxes (e.g. state and local taxes).

SubRate beta

A SubRate is used to calculate the taxPortions field in a cart or order. It is useful if the total tax of a country is a combination of multiple taxes (e.g. state and local taxes).

  • name - String
  • amount - Number Percentage in the range of [0..1].

TaxRateDraft

  • name - String
  • amount - Number - Optional
    Percentage in the range of [0..1]. Must be supplied if no subRates are specified. If subRates are specified then the amount can be omitted or it must be the sum of the amounts of all subRates.
  • includedInPrice - Boolean
  • country - String
    A two-digit country code as per ↗ ISO 3166-1 alpha-2 .
  • state - String - Optional
    The state in the country
  • subRates - Array of SubRate - Optional beta
    For countries (e.g. the US) where the total tax is a combination of multiple taxes (e.g. state and local taxes).

Get TaxCategory

Get TaxCategory by ID

Endpoint: /{projectKey}/tax-categories/{id}
Method: GET
OAuth2 Scopes: view_products:{projectKey}
Response Representation: TaxCategory

Get TaxCategory by Key

Endpoint: /{projectKey}/tax-categories/key={key}
Method: GET
OAuth2 Scopes: view_products:{projectKey}
Response Representation: TaxCategory

Query TaxCategories

Endpoint: /{projectKey}/tax-categories
Method: GET
OAuth2 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with the results array of TaxCategory
Query Parameters:

Create TaxCategory

Endpoint: /{projectKey}/tax-categories
Method: POST
OAuth2 Scopes: manage_products:{projectKey}
Request Representation: TaxCategoryDraft
Response Representation: TaxCategory

Update TaxCategory

Update TaxCategory by ID

Endpoint: /{projectKey}/tax-categories/{id}
Method: POST
OAuth2 Scopes: manage_products:{projectKey}
Response Representation: TaxCategory
Fields:

  • version - Number - Required
    The expected version of the TaxCategory on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the TaxCategory.

Update TaxCategory by Key

Endpoint: /{projectKey}/tax-categories/key={key}
Method: POST
OAuth2 Scopes: manage_products:{projectKey}
Response Representation: TaxCategory
Fields:

  • version - Number - Required
    The expected version of the TaxCategory on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the TaxCategory.

Update Actions

Change Name

  • action - String - "changeName"
  • name - String - Required

Set Key

  • action - String - "setKey"
  • key - String - Optional
    If key is absent or null, it is removed if it exists.

Set Description

  • action - String - "setDescription"
  • description - String - Optional

Add TaxRate

  • action - String - "addTaxRate"
  • taxRate - TaxRateDraft - Required

Replace TaxRate

  • action - String - "replaceTaxRate"
  • taxRateId - String
  • taxRate - TaxRateDraft - Required

Remove TaxRate

  • action - String - "removeTaxRate"
  • taxRateId - String - Required

Delete TaxCategory

Delete TaxCategory by ID

Endpoint: /{projectKey}/tax-categories/{id}
Method: DELETE
OAuth2 Scopes: manage_products:{projectKey}
Query Parameters:

  • version - Number - Required

Delete TaxCategory by Key

Endpoint: /{projectKey}/tax-categories/key={key}
Method: DELETE
OAuth2 Scopes: manage_products:{projectKey}
Query Parameters:

  • version - Number - Required