Tax calculations
Note
Shopify's Tax Platform is available by invitation only to select tax software companies integrating with Shopify.
Note:
Shopify's Tax Platform is available by invitation only to select tax software companies integrating with Shopify.
This guide covers the HTTP POST requests that Shopify sends to your tax app for tax calculations. These requests are triggered by operations like cart checkouts, order edits that add items or increase quantities, and item exchanges within orders.
Anchor to Tax calculation requestTax calculation request
The tax calculation flow starts when Shopify sends an HTTP POST request to the calculate_taxes_api_endpoint configured in your tax calculation app extension. This request contains cart, customer, and delivery details.
Anchor to Example requestExample request
Tax calculation request
Request
POST https://your-tax-app.com/your_calculate_taxes_api_endpoint
Request headers
X-Shopify-Shop-Domain: example.myshopify.com
X-Shopify-Shop-Id: 123456789
X-Shopify-Line-Item-Count: 1
X-Shopify-Request-Id: b1626615b389d34d21602cf8f81a930f
X-Shopify-Hmac-SHA256: base64-encoded-hmac
X-Shopify-API-Version: 2026-04
Request body
{
"idempotent_key": "bbf8e3a2485c1a07c5c964f59e651eb0",
"request": {
"datetime_created_utc": "2022-12-13T05:43:12.000Z",
"tax_included": false,
"currency_code": "CAD",
"session_id": "97e8923d-7fe7-481d-9913-16125bb4641c",
"app": {
"id": "gid://shopify/App/1354745",
"handle": "shopify-draft-orders"
}
},
"shop": {
"billing_address": {
"address1": "62 Royal Mount",
"address2": null,
"city": "Westbury",
"province_code": "MB",
"country_code": "CA",
"zip": "R4K 4A5"
}
},
"cart": {
"buyer_identity": {
"tax_exempt": false,
"customer": {
"id": "593934299",
"exemptions": [],
"metafields": [
{
"namespace": "custom",
"key": "has_prescription",
"type": "boolean",
"value": "true"
}
]
Response body
{
"idempotent_key": "8ec2ef67f35980ea6a7842b122f2549f",
"currency": "CAD",
"delivery_group_taxes": [
{
"id": "05b63f9e002a970b7d05c851aab2d30e",
"tax_lines": [
{
"line_id": "ccebfdf4e2da4ee8c663612ef657ed09",
"tax_id": "fce50938252583cb567a31018db9088e",
"calculated_tax": "21.5774",
"calculated_tax_refundable": "21.5774",
"amount_exempt": "0.0",
"amount_taxable": "165.98",
"amount_non_taxable": "0.0"
},
{
"line_id": "05b63f9e002a970b7d05c851aab2d30e",
"tax_id": "fce50938252583cb567a31018db9088e",
"calculated_tax": "1.3",
"calculated_tax_refundable": "1.3",
"amount_exempt": "0.0",
"amount_taxable": "10.0",
"amount_non_taxable": "0.0"
}
]
}
],
"taxes": [
{
"id": "fce50938252583cb567a31018db9088e",
"title": "HST",
"rate": {
"type": "SALES_TAX",
"structure": "STANDARD",
"amount": "0.13"
},
"source": {
"tax_registration": {
"code": "CA-GST",
"registration_number": "CA4276576354"
},
"tax_authority": {
"code": "CA-GST"
},
"tax_jurisdiction": {
"id": "CA-ON",
"code": "CA-ON",
"type": "PROVINCE",
"name": "ONTARIO"
},
"situs": "DESTINATION"
},
"liability": "Merchant"
}
],
"partner_errors": []
}
Anchor to Request headersRequest headers
| Header | Description |
|---|---|
X-Shopify-Shop-Domainrequired | The permanent domain of the merchant's shop. |
X-Shopify-Shop-Idrequired | The unique integer ID of the merchant's shop. Can be used to identify which shop is initiating the tax calculation. |
X-Shopify-Line-Item-Countrequired | The total number of line items in the tax calculation request. |
X-Shopify-Request-Idrequired | The unique request ID used to track specific requests for troubleshooting purposes. |
X-Shopify-Hmac-SHA256required | The token that's generated using the HMAC algorithm with SHA-256. The token is used to hash the request body using the app's secret. |
X-Shopify-API-Versionrequired | Indicates the API version of the tax calculation request specified in your tax calculation app extension. If the version is outdated, then it defaults to the oldest supported version (current version - 1 year). If no version is specified, then it defaults to the most current stable version. See API versioning for more information. |
Anchor to Request bodyRequest body
| Attribute | Description | Type |
|---|---|---|
idempotent_keyrequired | A unique identifier for the tax calculation request. Requests with the same ID are identical to previous requests with that ID. | String |
requestrequired | Metadata about the tax calculation request. Refer to request hash for more information. | Object |
shoprequired | Information about the merchant's shop. Refer to shop hash for more information. | Object |
cartrequired | Contains buyer information, addresses, and delivery groups. Refer to cart hash for more information. | Object |
Anchor to [object Object], hashrequest hash
request hash| Attribute | Description | Type |
|---|---|---|
datetime_created_utcrequired | The UTC timestamp when the request was created. | String (ISO-8601) |
tax_includedrequired | Indicates if prices include tax. | Boolean |
currency_coderequired | The three-letter ISO 4217 currency code for all monetary values in the request. | String |
session_id | A unique identifier for the session. | String |
app | Information about the app initiating the request. Refer to app hash for more information. | Object |
Anchor to [object Object], hashapp hash
app hash| Attribute | Description | Type |
|---|---|---|
idrequired | The unique identifier for the app. | String |
handlerequired | The handle of the app. | String |
Anchor to [object Object], hashshop hash
shop hash| Attribute | Description | Type |
|---|---|---|
billing_addressrequired | The merchant's billing address. Origin-based states use the merchant's location to determine tax rates instead of the customer's delivery address. For example, if a merchant is located in Austin, Texas (an origin-based state), their Austin address determines the tax rate applied to sales, regardless of where in Texas the customer is located. Refer to address hash for more information. | Object |
Anchor to [object Object], hashcart hash
cart hash| Attribute | Description | Type |
|---|---|---|
buyer_identity | Information about the buyer including customer details and tax exemption status. Refer to buyer identity hash for more information. | Object |
billing_address | The billing address for the order. Refer to address hash for more information. | Object |
delivery_groupsrequired | An array of delivery groups, each containing items being delivered to the same address with the same delivery method. | Array |
Anchor to [object Object], hashbuyer_identity hash
buyer_identity hash| Attribute | Description | Type |
|---|---|---|
customer | Customer information if the buyer is logged in. Refer to customer hash for more information. | Object |
purchasing_company | Company information for B2B transactions. Refer to purchasing company hash for more information. | Object |
tax_exemptrequired | Indicates if the buyer is tax exempt. | Boolean |
Anchor to [object Object], hashcustomer hash
customer hash| Attribute | Description | Type |
|---|---|---|
idrequired | The unique identifier for the customer. | String |
exemptions | A list of tax exemptions for the customer. Refer to exemption hash for more information. | Array |
metafields | Custom metafields associated with the customer, containing merchant-defined attributes that may affect tax calculations (for example, prescription status or tax exemption certificates). Available as of API version 2026-04. Refer to metafield hash and the metafields documentation for more information. | Array |
Anchor to [object Object], hashexemption hash
exemption hash| Attribute | Description | Type |
|---|---|---|
external_idrequired | The identifier for the tax exemption type. Refer to the full list of supported tax exemption codes. | String |
Anchor to [object Object], hashpurchasing_company hash
purchasing_company hash| Attribute | Description | Type |
|---|---|---|
companyrequired | Company details including ID and VAT number. Refer to company hash for more information. | Object |
company_location | Specific company location details if applicable. Refer to company_location hash for more information. | Object |
exemptions | A list of tax exemptions for the company location. Refer to exemption hash for more information. | Array |
Anchor to [object Object], hashcompany hash
company hash| Attribute | Description | Type |
|---|---|---|
idrequired | The unique identifier for the company. | String |
external_id | The external identifier for the company. | String |
vat_number | The VAT number of the company. | String |
metafields | Custom metafields associated with the company, containing merchant-defined attributes for B2B tax calculations (for example, wholesale status or resale certificates). Available as of API version 2026-04. Refer to metafield hash and the metafields documentation for more information. | Array |
Anchor to [object Object], hashcompany_location hash
company_location hash| Attribute | Description | Type |
|---|---|---|
idrequired | The unique identifier for the company location. | String |
external_id | The external identifier for the company location. | String |
vat_number | The VAT number for this company location. | String |
Anchor to [object Object], hashmetafield hash
metafield hash| Attribute | Description | Type |
|---|---|---|
namespacerequired | The namespace of the metafield (for example, custom or tax_partners). | String |
keyrequired | The key of the metafield (for example, has_prescription or tax_code). | String |
typerequired | The data type of the metafield value (for example, boolean, single_line_text_field). | String |
valuerequired | The value of the metafield, serialized as a string. | String |
Anchor to [object Object], hashaddress hash
address hash| Attribute | Description | Type |
|---|---|---|
address1 | The first line of the address. | String |
address2 | The second line of the address. | String |
city | The city name. | String |
province_code | The province or state code (2-3 characters). | String |
country_coderequired | The country code (2-3 characters). | String |
zip | The postal or zip code. | String |
Anchor to [object Object], hashdelivery_group hash
delivery_group hash| Attribute | Description | Type |
|---|---|---|
idrequired | The unique identifier for the delivery group. | String |
selected_delivery_optionrequired | The delivery option selected for this group. Refer to selected delivery option hash for more information. | Object |
origin_address | The origin address for the delivery (e.g., warehouse or store location). Refer to address hash for more information. | Object |
delivery_address | The destination address for the delivery. Refer to address hash for more information. | Object |
cart_linesrequired | An array of line items in the delivery group. | Array |
Anchor to [object Object], hashselected_delivery_option hash
selected_delivery_option hash| Attribute | Description | Type |
|---|---|---|
subtotal_amountrequired | The subtotal amount for delivery before discounts. Refer to money hash for more information. | Object |
total_amountrequired | The total amount for delivery after discounts. Refer to money hash for more information. | Object |
delivery_method_typerequired | The type of delivery method. Possible values:
| String |
Anchor to [object Object], hashcart_line hash
cart_line hash| Attribute | Description | Type |
|---|---|---|
idrequired | The unique identifier for the line item. | String |
merchandiserequired | The product or custom item being purchased. Refer to merchandise hash for more information. | Object |
quantityrequired | The quantity of the item being purchased. | Integer |
costrequired | The cost information for the line item. Refer to cart line cost hash for more information. | Object |
discount_allocations | An array of discounts applied to this line item. | Array |
properties | Custom name-value pairs on the line item. Tax partner apps configure which property keys they want to receive, up to a maximum of five keys. When a configured key is present on a line item, its value is included in the request. Available as of API version 2026-04. | Object |
Anchor to [object Object], hashcart_line_cost hash
cart_line_cost hash| Attribute | Description | Type |
|---|---|---|
amount_per_quantityrequired | The price per unit of the item. Refer to money hash for more information. | Object |
amount_per_quantity_set | The price for each unit in both shop and presentment currencies. Available as of API version 2026-01 when the shop has multi-currency enabled. Refer to money bag hash for more information. | Object |
subtotal_amountrequired | The subtotal before discounts (quantity × amount_per_quantity). Refer to money hash for more information. | Object |
subtotal_amount_set | The subtotal before discounts in both shop and presentment currencies. Available as of API version 2026-01 when the shop has multi-currency enabled. Refer to money bag hash for more information. | Object |
total_amountrequired | The total after discounts are applied. Refer to money hash for more information. | Object |
total_amount_set | The total after discounts in both shop and presentment currencies. Available as of API version 2026-01 when the shop has multi-currency enabled. Refer to money bag hash for more information. | Object |
Anchor to [object Object], hashmoney_bag hash
money_bag hash| Attribute | Description | Type |
|---|---|---|
shop_moneyrequired | The amount in the shop's accounting currency. Refer to money hash for more information. | Object |
presentment_moneyrequired | The amount in the customer-facing currency. Refer to money hash for more information. | Object |
Anchor to [object Object], hashmoney hash
money hash| Attribute | Description | Type |
|---|---|---|
amountrequired | The monetary amount as a decimal string. | String |
currency_coderequired | The three-letter ISO 4217 currency code. | String |
Anchor to [object Object], hashmerchandise hash
merchandise hashThe merchandise hash can be either a product variant or a custom product. Both types share some common attributes but have different structures.
Anchor to Product variant merchandiseProduct variant merchandise
| Attribute | Description | Type |
|---|---|---|
__typerequired | The type of resource. Must be PRODUCT_VARIANT for product variants. | String |
idrequired | The unique identifier for the product variant. | String |
sku | The SKU (stock keeping unit) of the variant. | String |
productrequired | The product that this variant belongs to. Refer to product hash for more information. | Object |
requires_shippingrequired | Indicates whether the item requires shipping. | Boolean |
weight | The weight of the item. | Number |
weight_unit | The unit of weight. Possible values: GRAMS, KILOGRAMS, OUNCES, POUNDS | String |
tax_exemptrequired | Indicates if the product variant is tax exempt. | Boolean |
metafields | An array of metafield data for the variant. | Array |
Anchor to Custom product merchandiseCustom product merchandise
| Attribute | Description | Type |
|---|---|---|
__typerequired | The type of resource. Must be CUSTOM_PRODUCT for custom products. | String |
titlerequired | The title of the custom product. | String |
is_gift_cardrequired | Indicates whether the item is a gift card. | Boolean |
requires_shipping | Indicates whether the item requires shipping. | Boolean |
weight | The weight of the item. | Number |
weight_unit | The unit of weight. | String |
tax_exemptrequired | Indicates if the custom product is tax exempt. | Boolean |
Anchor to [object Object], hashproduct hash
product hash| Attribute | Description | Type |
|---|---|---|
idrequired | The unique identifier for the product. | String |
handlerequired | The handle (URL slug) of the product. | String |
is_gift_cardrequired | Indicates whether the product is a gift card. | Boolean |
metafieldsrequired | An array of metafield data for the product. | Array |
Anchor to [object Object], hashmetafield hash
metafield hash| Attribute | Description | Type |
|---|---|---|
namespacerequired | A grouping of metafields. Used with the metafield key to find a metafield on a resource and prevent conflicts with other metafields using the same key. Must be 3-255 characters long and contain only alphanumeric characters, hyphens, and underscores. | String |
keyrequired | The name of the property. Maximum key size is 30 characters. | String |
typerequired | The type of the metafield value. See metafield types for all possible values. | String |
valuerequired | The value of the property. Maximum value size is 1000 characters. | String |
Anchor to [object Object], hashdiscount_allocation hash
discount_allocation hash| Attribute | Description | Type |
|---|---|---|
discounted_amountrequired | The amount of discount applied to the line item. Refer to money hash for more information. | Object |
Anchor to Tax calculation responseTax calculation response
Anchor to Response schemaResponse schema
| Attribute | Description | Type |
|---|---|---|
idempotent_keyrequired | The unique identifier for the tax calculation request. Must match the idempotent_key from the request. | String |
currencyrequired | The three-letter ISO 4217 currency code. | String |
delivery_group_taxesrequired | An array of tax calculations for each delivery group. | Array |
taxesrequired | An array of unique tax definitions referenced in tax lines. | Array |
partner_errors | An array of errors if tax calculation failed. | Array |
Anchor to [object Object], hashdelivery_group_taxes hash
delivery_group_taxes hash| Attribute | Description | Type |
|---|---|---|
idrequired | The delivery group ID. Must match the delivery group ID from the request. | String |
tax_linesrequired | An array of tax line items for this delivery group. | Array |
Anchor to [object Object], hashtax_line hash
tax_line hash| Attribute | Description | Type |
|---|---|---|
line_idrequired | The cart line ID. Must match the cart line ID from the request. | String |
tax_idrequired | A reference to a tax definition in the taxes array. | String |
calculated_taxrequired | The total tax amount for this line item. | String |
calculated_tax_refundablerequired | The refundable portion of the tax (usually same as calculated_tax). | String |
amount_exemptrequired | The amount that's exempt from tax. | String |
amount_taxablerequired | The amount subject to the tax. | String |
amount_non_taxablerequired | The amount not subject to the tax. | String |
Anchor to [object Object], hashtax_definition hash
tax_definition hash| Attribute | Description | Type |
|---|---|---|
idrequired | The unique identifier for the tax definition. | String |
titlerequired | The name for the tax. | String |
raterequired | The tax rate information. Refer to tax rate hash for more information. | Object |
sourcerequired | The tax source information including jurisdiction. Refer to tax source hash for more information. | Object |
liability | Indicates who's responsible for remitting the tax. Possible values are Merchant and Marketplace. | String |
Anchor to [object Object], hashtax_rate hash
tax_rate hash| Attribute | Description | Type |
|---|---|---|
typerequired | The tax type. Possible values:
| String |
structurerequired | The way the tax is calculated. Possible values:
| String |
amountrequired | The tax rate as decimal (for example, 0.05 for 5%). | String |
Anchor to [object Object], hashtax_source hash
tax_source hash| Attribute | Description | Type |
|---|---|---|
tax_jurisdictionrequired | The jurisdiction information for the tax. Refer to tax jurisdiction hash for more information. | Object |
tax_registration | The tax registration details if applicable. Refer to tax_registration hash for more information. | Object |
tax_authority | The tax authority information. Refer to tax_authority hash for more information. | Object |
situs | The tax location basis. Possible values:
| String |
Anchor to [object Object], hashtax_registration hash
tax_registration hash| Attribute | Description | Type |
|---|---|---|
coderequired | A unique code for the tax registration. | String |
registration_numberrequired | The tax registration number. | String |
| Attribute | Description | Type |
|---|---|---|
coderequired | The code for the tax authority to which the taxes would be remitted. | String |
Anchor to [object Object], hashtax_jurisdiction hash
tax_jurisdiction hash| Attribute | Description | Type |
|---|---|---|
id | A unique identifier for the tax jurisdiction. | String |
code | A unique code to identify the tax jurisdiction. For countries, provinces, and states it would be expected this to be the ISO3166-2 Alpha Code (e.g. CA or US-FL). For counties and cities this should be the alpha code for the state (US-FL) plus a reporting code or FIPS. | String |
namerequired | The name of the tax jurisdiction. | String |
typerequired | Type of jurisdiction. Possible values:
| String |
reporting_code | The state assigned reporting code for this jurisdiction. This is what will be used by merchants to file taxes for this jurisdiction. | String |
Anchor to Error handlingError handling
Shopify must receive an HTTP 2xx response for the tax calculation to be successful. If there are errors with the tax calculation, the app must respond with a partner_errors array in the response that includes a code and message for the error.
This is an example of an expected error response:
{
"idempotent_key": "8ec2ef67f35980ea6a7842b122f2549f",
"currency": "CAD",
"delivery_group_taxes": [],
"taxes": [],
"partner_errors": [
{
"code": "MALFORMED_ADDRESS",
"message": "Address is not valid"
}
]
}
Anchor to Error schemaError schema
| Attribute | Description | Type |
|---|---|---|
coderequired | The code identifying the class of error. Possible values:
| String |
messagerequired | A description of what happened in this instance. Includes details about the part of the request that was the cause. | String |
Was this page helpful?