Queries and mutations for managing Tax Categories in the platform.

Queries

Query Tax Categories

QUERYtaxCategories
Arguments
where​
String​
sort​
Array of String​
limit​
Int​
offset​
Int​

Get Tax Category

QUERYtaxCategory
Arguments
id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Mutations

Create Tax Category

MUTATIONcreateTaxCategory
Arguments
draft​

Update Tax Category

MUTATIONupdateTaxCategory
Arguments
version​
Long​
actions​
id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Delete Tax Category

MUTATIONdeleteTaxCategory
Arguments
version​
Long​
id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output types

TaxCategory

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

name​
String​

Name of the TaxCategory.

description​
String​

Description of the TaxCategory.

rates​
Array of TaxRate​

Tax rates and subrates of states and countries. Each TaxRate in the array has a unique ID.

key​
String​

User-defined unique identifier of the TaxCategory.

id​
String​

Unique identifier of the TaxCategory.

version​
Long​

Current version of the TaxCategory.

createdAt​

Date and time (UTC) the TaxCategory was initially created.

lastModifiedAt​

Date and time (UTC) the TaxCategory was last updated.

createdBy​

IDs and references that created the TaxCategory.

lastModifiedBy​

IDs and references that last modified the TaxCategory.

TaxRate

name​
String​

Name of the TaxRate.

amount​
Float​
Tax rate. If subrates are used, the amount is the sum of all rates in subRates.
includedInPrice​
Boolean​
Whether tax is included in Embedded Prices or Standalone Prices, and the taxedPrice is present on LineItems. In this case, the totalNet price on TaxedPrice includes the TaxRate.
country​
state​
String​
State within the country, such as Texas in the United States. The value is case-sensitive and must use the same casing as the state value in the Cart shippingAddress.
A TaxRate whose state is omitted does not act as a wildcard: it only matches a Cart whose shippingAddress also has no state value. To apply the same rate across states, either define an individual TaxRate for each state, or use the region field or a Custom Field on the shipping address as described in Address matching.
id​
String​
Present if the TaxRate is part of a TaxCategory. Absent for external TaxRates in LineItem, CustomLineItem, and ShippingInfo.
key​
String​
User-defined identifier of the TaxRate. Unique within the TaxCategory containing it. Present when set using TaxRateDraft. Not available for external TaxRates created using ExternalTaxRateDraft.
subRates​
Array of SubRate​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
taxRoundingTarget​
Determines which of the net price and the tax amount the taxRoundingMode of the Cart or Order is applied to, when this TaxRate is included in the price. Ignored if includedInPrice is false.
Always returned by the API. Can be omitted when a TaxRate is supplied as input, such as in OrderImportDraft, and then defaults to Net.
Can be Net, or Tax​

SubRate

It is used to calculate the taxPortions field in a Cart or Order.
name​
String​

Name of the SubRate.

amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

Tax Category Query Result

offset​
Int​
count​
Int​
total​
Long​
exists​
Boolean​
results​
Array of TaxCategory​

Input types

TaxCategoryDraft

name​
String​

Name of the TaxCategory.

If the provided name is used by another TaxCategory in the Project, an InvalidOperation error is returned.
description​
String​

Description of the TaxCategory.

rates​
Array of TaxRateDraft​

Tax rates and subrates of states and countries.

key​
String​

User-defined unique identifier for the TaxCategory.

If the value is used by another TaxCategory in the Project, a DuplicateField error is returned.

TaxRateDraft

name​
String​

Name of the TaxRate.

amount​
Float​

Tax rate.

Either amount or subRates must be defined. If both are defined, the value of this field must be equal to the sum of the subRates amounts; otherwise, an InvalidOperation error is returned.
includedInPrice​
Boolean​
Whether tax is included in Embedded Prices or Standalone Prices, and the taxedPrice is present on LineItems. In this case, the totalNet price on TaxedPrice includes the TaxRate.
country​
If the provided combination of country and state exists for the TaxCategory, a DuplicateField error is returned.
state​
String​
State within the country, such as Texas in the United States. The value is case-sensitive and must use the same casing as the state value in the Cart shippingAddress. Empty strings are treated as if state was omitted.
If state is omitted, the resulting TaxRate does not act as a wildcard: it only matches a Cart whose shippingAddress also has no state value. To apply the same rate across states, either define an individual TaxRate for each state, or use the region field or a Custom Field on the shipping address as described in Address matching.
If the provided combination of country and state exists for the TaxCategory, a DuplicateField error is returned.
subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). If amount is defined, the total of all subrates must equal amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
key​
String​

User-defined identifier of the TaxRate.

If the provided key is used by another TaxRate in the TaxCategory, a DuplicateField error is returned.
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when this TaxRate is included in the price. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

TaxCategoryUpdateAction

changeName​
setDescription​
addTaxRate​
replaceTaxRate​
removeTaxRate​
setKey​

Update actions

Change Name

name​
String​

Set Description

description​
String​

Add Tax Rate

taxRate​

TaxRateDraft

name​
String​

Name of the TaxRate.

amount​
Float​

Tax rate.

Either amount or subRates must be defined. If both are defined, the value of this field must be equal to the sum of the subRates amounts; otherwise, an InvalidOperation error is returned.
includedInPrice​
Boolean​
Whether tax is included in Embedded Prices or Standalone Prices, and the taxedPrice is present on LineItems. In this case, the totalNet price on TaxedPrice includes the TaxRate.
country​
If the provided combination of country and state exists for the TaxCategory, a DuplicateField error is returned.
state​
String​
State within the country, such as Texas in the United States. The value is case-sensitive and must use the same casing as the state value in the Cart shippingAddress. Empty strings are treated as if state was omitted.
If state is omitted, the resulting TaxRate does not act as a wildcard: it only matches a Cart whose shippingAddress also has no state value. To apply the same rate across states, either define an individual TaxRate for each state, or use the region field or a Custom Field on the shipping address as described in Address matching.
If the provided combination of country and state exists for the TaxCategory, a DuplicateField error is returned.
subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). If amount is defined, the total of all subrates must equal amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
key​
String​

User-defined identifier of the TaxRate.

If the provided key is used by another TaxRate in the TaxCategory, a DuplicateField error is returned.
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when this TaxRate is included in the price. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

Replace Tax Rate

taxRateId​
String​
taxRateKey​
String​
taxRate​

TaxRateDraft

name​
String​

Name of the TaxRate.

amount​
Float​

Tax rate.

Either amount or subRates must be defined. If both are defined, the value of this field must be equal to the sum of the subRates amounts; otherwise, an InvalidOperation error is returned.
includedInPrice​
Boolean​
Whether tax is included in Embedded Prices or Standalone Prices, and the taxedPrice is present on LineItems. In this case, the totalNet price on TaxedPrice includes the TaxRate.
country​
If the provided combination of country and state exists for the TaxCategory, a DuplicateField error is returned.
state​
String​
State within the country, such as Texas in the United States. The value is case-sensitive and must use the same casing as the state value in the Cart shippingAddress. Empty strings are treated as if state was omitted.
If state is omitted, the resulting TaxRate does not act as a wildcard: it only matches a Cart whose shippingAddress also has no state value. To apply the same rate across states, either define an individual TaxRate for each state, or use the region field or a Custom Field on the shipping address as described in Address matching.
If the provided combination of country and state exists for the TaxCategory, a DuplicateField error is returned.
subRates​
Array of SubRateDraft​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). If amount is defined, the total of all subrates must equal amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.
Default: []​
key​
String​

User-defined identifier of the TaxRate.

If the provided key is used by another TaxRate in the TaxCategory, a DuplicateField error is returned.
taxRoundingTarget​
Determines whether the taxRoundingMode of the Cart or Order is applied to the net price or the tax amount when this TaxRate is included in the price. The field is ignored if includedInPrice is false.
Can be Net, or Tax​Default: Net​

SubRateDraft

name​
String​
amount​
Float​

TaxRoundingTarget

Net
Default. `taxRoundingMode` is applied to the net price and the tax amount is the exact remainder. E.g. at 20% on `1.23`, the net rounds to `1.02` and the tax is `0.21`.
Tax
`taxRoundingMode` is applied to the tax amount and the net price is the exact remainder. E.g. at 20% on `1.23`, the tax rounds to `0.20` and the net is `1.03`. Has no effect when the rate is not included in the price.

Remove Tax Rate

taxRateId​
String​
taxRateKey​
String​

Set Key

key​
String​

Value to set. If omitted, any existing value is removed.

If the value is used by another TaxCategory in the Project, a DuplicateField error is returned.