Queries and mutations for managing Tax Categories in the platform.
Queries
Query Tax Categories
| Arguments | |
|---|---|
whereString | |
sortArray of String | |
limitInt | |
offsetInt | |
Get Tax Category
| Arguments | |
|---|---|
idString | Queries with specified ID |
keyString | Queries with specified key |
Mutations
Create Tax Category
Update Tax Category
| Arguments | |
|---|---|
versionLong | |
actionsArray of TaxCategoryUpdateAction | |
idString | Queries with specified ID |
keyString | Queries with specified key |
Delete Tax Category
| Arguments | |
|---|---|
versionLong | |
idString | Queries with specified ID |
keyString | Queries with specified key |
Output types
TaxCategory
Tax Categories define how products are to be taxed in different countries.
nameString | Name of the TaxCategory. |
descriptionString | Description of the TaxCategory. |
ratesArray of TaxRate | Tax rates and subrates of states and countries. Each TaxRate in the array has a unique ID. |
keyString | User-defined unique identifier of the TaxCategory. |
idString | Unique identifier of the TaxCategory. |
versionLong | 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
nameString | Name of the TaxRate. |
amountFloat | Tax rate. If subrates are used, the amount is the sum of all rates in subRates. |
includedInPriceBoolean | 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 | Country in which the tax rate is applied in ISO 3166-1 alpha-2 format. |
stateString | 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. |
idString | Present if the TaxRate is part of a TaxCategory.
Absent for external TaxRates in LineItem, CustomLineItem, and ShippingInfo. |
keyString | 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. |
subRatesArray 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 Can be Net.Net, or Tax |
SubRate
nameString | Name of the SubRate. |
amountFloat |
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
offsetInt | |
countInt | |
totalLong | |
existsBoolean | |
resultsArray of TaxCategory |
Input types
TaxCategoryDraft
nameString | Name of the TaxCategory. If the provided name is used by another TaxCategory in the Project, an InvalidOperation error is returned. |
descriptionString | Description of the TaxCategory. |
ratesArray of TaxRateDraft | Tax rates and subrates of states and countries. |
keyString | User-defined unique identifier for the TaxCategory. If the value is used by another TaxCategory in the Project, a DuplicateField error is returned. |
TaxRateDraft
nameString | Name of the TaxRate. |
amountFloat | 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. |
includedInPriceBoolean | 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 | Country in which the tax rate is applied in ISO 3166-1 alpha-2 format.
If the provided combination of country and state exists for the TaxCategory, a DuplicateField error is returned. |
stateString | 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. |
subRatesArray of SubRateDraft | Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). If Default: 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.[] |
keyString | 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 Can be 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.Net, or TaxDefault: Net |
SubRateDraft
nameString | |
amountFloat |
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
nameString |
Set Description
descriptionString |
Add Tax Rate
taxRate |
TaxRateDraft
nameString | Name of the TaxRate. |
amountFloat | 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. |
includedInPriceBoolean | 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 | Country in which the tax rate is applied in ISO 3166-1 alpha-2 format.
If the provided combination of country and state exists for the TaxCategory, a DuplicateField error is returned. |
stateString | 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. |
subRatesArray of SubRateDraft | Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). If Default: 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.[] |
keyString | 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 Can be 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.Net, or TaxDefault: Net |
SubRateDraft
nameString | |
amountFloat |
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
taxRateIdString | |
taxRateKeyString | |
taxRate |
TaxRateDraft
nameString | Name of the TaxRate. |
amountFloat | 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. |
includedInPriceBoolean | 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 | Country in which the tax rate is applied in ISO 3166-1 alpha-2 format.
If the provided combination of country and state exists for the TaxCategory, a DuplicateField error is returned. |
stateString | 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. |
subRatesArray of SubRateDraft | Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). If Default: 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.[] |
keyString | 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 Can be 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.Net, or TaxDefault: Net |
SubRateDraft
nameString | |
amountFloat |
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
taxRateIdString | |
taxRateKeyString |
Set Key
keyString | 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. |