--- title: Tax calculations description: >- Learn how to format the requests that initiate tax calculations for your tax app. source_url: html: 'https://shopify.dev/docs/apps/build/tax/tax-calculations' md: 'https://shopify.dev/docs/apps/build/tax/tax-calculations.md' --- ExpandOn this page * [Tax calculation request](https://shopify.dev/docs/apps/build/tax/tax-calculations.md#tax-calculation-request) * [Tax calculation response](https://shopify.dev/docs/apps/build/tax/tax-calculations.md#tax-calculation-response) * [Error handling](https://shopify.dev/docs/apps/build/tax/tax-calculations.md#error-handling) # Tax calculations Note Shopify's Tax Platform is available by invitation only. To request access, contact . 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. *** ## Tax 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](https://shopify.dev/docs/apps/build/tax/build-tax-app#step-2-configure-your-tax-app-extension). This request contains cart, customer, and delivery details. ### Example request ## Tax calculation request ## Request ```http POST https://your-tax-app.com/your_calculate_taxes_api_endpoint ``` ## Request headers ```http 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: 2025-07 ``` ## Request body ```json { "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": [] }, "purchasing_company": null }, "billing_address": { "address1": "123 Sweet Street", "address2": "Suite B", "city": "Montreal", "province_code": "QC", "country_code": "CA", "zip": "H2Z 0B3" }, "delivery_groups": [ { "id": "05b63f9e002a970b7d05c851aab2d30e", "selected_delivery_option": { "subtotal_amount": { "amount": "10.0", "currency_code": "CAD" }, "total_amount": { "amount": "10.0", "currency_code": "CAD" }, "delivery_method_type": "SHIPPING" }, "origin_address": { "address1": "62 Royal Mount", "address2": null, "city": "Westbury", "province_code": "MB", "country_code": "CA", "zip": "R4K 4A5" }, "delivery_address": { "address1": "290 Bremner Blvd", "address2": null, "city": "Toronto", "province_code": "ON", "country_code": "CA", "zip": "M5V 3L9" }, "cart_lines": [ { "id": "ccebfdf4e2da4ee8c663612ef657ed09", "quantity": 2, "cost": { "amount_per_quantity": { "amount": "82.99", "currency_code": "CAD" }, "subtotal_amount": { "amount": "165.98", "currency_code": "CAD" }, "total_amount": { "amount": "165.98", "currency_code": "CAD" } }, "discount_allocations": [], "merchandise": { "id": "5", "sku": null, "product": { "id": "2", "handle": "Awesome Sneakers", "is_gift_card": false, "metafields": [] }, "requires_shipping": true, "tax_exempt": false, "metafields": [], "__type": "PRODUCT_VARIANT" } } ] } ] } } ``` ## Response body ```json { "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": [] } ``` ### Request headers | Header | Description | | - | - | | `X-Shopify-Shop-Domain`required | The permanent domain of the merchant's shop. | | `X-Shopify-Shop-Id`required | 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-Count`required | The total number of line items in the tax calculation request. | | `X-Shopify-Request-Id`required | The unique request ID used to track specific requests for troubleshooting purposes. | | `X-Shopify-Hmac-SHA256`required | 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-Version`required | 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](https://shopify.dev/docs/api/usage/versioning) for more information. | ### Request body | Attribute | Description | Type | | - | - | - | | `idempotent_key`required | A unique identifier for the tax calculation request. Requests with the same ID are identical to previous requests with that ID. | `String` | | `request`required | Metadata about the tax calculation request. Refer to [request hash](#request-hash) for more information. | `Object` | | `shop`required | Information about the merchant's shop. Refer to [shop hash](#shop-hash) for more information. | `Object` | | `cart`required | Contains buyer information, addresses, and delivery groups. Refer to [cart hash](#cart-hash) for more information. | `Object` | #### `request` hash | Attribute | Description | Type | | - | - | - | | `datetime_created_utc`required | The UTC timestamp when the request was created. | `String (ISO-8601)` | | `tax_included`required | Indicates if prices include tax. | `Boolean` | | `currency_code`required | 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](#app-hash) for more information. | `Object` | #### `app` hash | Attribute | Description | Type | | - | - | - | | `id`required | The unique identifier for the app. | `String` | | `handle`required | The handle of the app. | `String` | #### `shop` hash | Attribute | Description | Type | | - | - | - | | `billing_address`required | 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](#address-hash) for more information. | `Object` | #### `cart` hash | Attribute | Description | Type | | - | - | - | | `buyer_identity` | Information about the buyer including customer details and tax exemption status. Refer to [buyer identity hash](#buyer_identity-hash) for more information. | `Object` | | `billing_address` | The billing address for the order. Refer to [address hash](#address-hash) for more information. | `Object` | | `delivery_groups`required | An array of delivery groups, each containing items being delivered to the same address with the same delivery method. | `Array` | #### `buyer_identity` hash | Attribute | Description | Type | | - | - | - | | `customer` | Customer information if the buyer is logged in. Refer to [customer hash](#customer-hash) for more information. | `Object` | | `purchasing_company` | Company information for B2B transactions. Refer to [purchasing company hash](#purchasing_company-hash) for more information. | `Object` | | `tax_exempt`required | Indicates if the buyer is tax exempt. | `Boolean` | #### `customer` hash | Attribute | Description | Type | | - | - | - | | `id`required | The unique identifier for the customer. | `String` | | `exemptions` | A list of tax exemptions for the customer. Refer to [exemption hash](#exemption-hash) for more information. | `Array` | #### `exemption` hash | Attribute | Description | Type | | - | - | - | | `external_id`required | The identifier for the tax exemption type. Refer to the full list of [supported tax exemption codes](https://shopify.dev/docs/apps/build/tax/tax-exemptions#supported-tax-exemption-codes). | `String` | #### `purchasing_company` hash | Attribute | Description | Type | | - | - | - | | `company`required | Company details including ID and VAT number. Refer to [company hash](#company-hash) for more information. | `Object` | | `company_location` | Specific company location details if applicable. Refer to [company\_location hash](#company_location-hash) for more information. | `Object` | | `exemptions` | A list of tax exemptions for the company location. Refer to [exemption hash](#exemption-hash) for more information. | `Array` | #### `company` hash | Attribute | Description | Type | | - | - | - | | `id`required | 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` | #### `company_location` hash | Attribute | Description | Type | | - | - | - | | `id`required | 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` | #### `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_code`required | The country code (2-3 characters). | `String` | | `zip` | The postal or zip code. | `String` | #### `delivery_group` hash | Attribute | Description | Type | | - | - | - | | `id`required | The unique identifier for the delivery group. | `String` | | `selected_delivery_option`required | The delivery option selected for this group. Refer to [selected delivery option hash](#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](#address-hash) for more information. | `Object` | | `delivery_address` | The destination address for the delivery. Refer to [address hash](#address-hash) for more information. | `Object` | | `cart_lines`required | An array of line items in the delivery group. | `Array` | #### `selected_delivery_option` hash | Attribute | Description | Type | | - | - | - | | `subtotal_amount`required | The subtotal amount for delivery before discounts. Refer to [money hash](#money-hash) for more information. | `Object` | | `total_amount`required | The total amount for delivery after discounts. Refer to [money hash](#money-hash) for more information. | `Object` | | `delivery_method_type`required | The type of delivery method. Possible values:- `LOCAL` - `NONE` - `PICKUP_POINT` - `RETAIL` - `SHIPPING` - `SHIPPING_AND_HANDLING` | `String` | #### `cart_line` hash | Attribute | Description | Type | | - | - | - | | `id`required | The unique identifier for the line item. | `String` | | `merchandise`required | The product or custom item being purchased. Refer to [merchandise hash](#merchandise-hash) for more information. | `Object` | | `quantity`required | The quantity of the item being purchased. | `Integer` | | `cost`required | The cost information for the line item. Refer to [cart line cost hash](#cart_line_cost-hash) for more information. | `Object` | | `discount_allocations` | An array of discounts applied to this line item. | `Array` | #### `cart_line_cost` hash | Attribute | Description | Type | | - | - | - | | `amount_per_quantity`required | The price per unit of the item. Refer to [money hash](#money-hash) for more information. | `Object` | | `subtotal_amount`required | The subtotal before discounts (quantity × amount\_per\_quantity). Refer to [money hash](#money-hash) for more information. | `Object` | | `total_amount`required | The total after discounts are applied. Refer to [money hash](#money-hash) for more information. | `Object` | #### `money` hash | Attribute | Description | Type | | - | - | - | | `amount`required | The monetary amount as a decimal string. | `String` | | `currency_code`required | The three-letter ISO 4217 currency code. | `String` | #### `merchandise` hash The merchandise hash can be either a product variant or a custom product. Both types share some common attributes but have different structures. ##### Product variant merchandise | Attribute | Description | Type | | - | - | - | | `__type`required | The type of resource. Must be `PRODUCT_VARIANT` for product variants. | `String` | | `id`required | The unique identifier for the product variant. | `String` | | `sku` | The SKU (stock keeping unit) of the variant. | `String` | | `product`required | The product that this variant belongs to. Refer to [product hash](#product-hash) for more information. | `Object` | | `requires_shipping`required | 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_exempt`required | Indicates if the product variant is tax exempt. | `Boolean` | | `metafields` | An array of metafield data for the variant. | `Array` | ##### Custom product merchandise | Attribute | Description | Type | | - | - | - | | `__type`required | The type of resource. Must be `CUSTOM_PRODUCT` for custom products. | `String` | | `title`required | The title of the custom product. | `String` | | `is_gift_card`required | 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_exempt`required | Indicates if the custom product is tax exempt. | `Boolean` | ##### `product` hash | Attribute | Description | Type | | - | - | - | | `id`required | The unique identifier for the product. | `String` | | `handle`required | The handle (URL slug) of the product. | `String` | | `is_gift_card`required | Indicates whether the product is a gift card. | `Boolean` | | `metafields`required | An array of metafield data for the product. | `Array` | #### `metafield` hash | Attribute | Description | Type | | - | - | - | | `namespace`required | 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` | | `key`required | The name of the property. Maximum key size is 30 characters. | `String` | | `type`required | The type of the metafield value. See [metafield types](https://shopify.dev/docs/apps/build/custom-data/metafields/list-of-data-types) for all possible values. | `String` | | `value`required | The value of the property. Maximum value size is 1000 characters. | `String` | #### `discount_allocation` hash | Attribute | Description | Type | | - | - | - | | `discounted_amount`required | The amount of discount applied to the line item. Refer to [money hash](#money-hash) for more information. | `Object` | *** ## Tax calculation response ### Response schema | Attribute | Description | Type | | - | - | - | | `idempotent_key`required | The unique identifier for the tax calculation request. Must match the `idempotent_key` from the request. | `String` | | `currency`required | The three-letter ISO 4217 currency code. | `String` | | `delivery_group_taxes`required | An array of tax calculations for each delivery group. | `Array` | | `taxes`required | An array of unique tax definitions referenced in tax lines. | `Array` | | `partner_errors` | An array of errors if tax calculation failed. | `Array` | #### `delivery_group_taxes` hash | Attribute | Description | Type | | - | - | - | | `id`required | The delivery group ID. Must match the delivery group ID from the request. | `String` | | `tax_lines`required | An array of tax line items for this delivery group. | `Array` | #### `tax_line` hash | Attribute | Description | Type | | - | - | - | | `line_id`required | The cart line ID. Must match the cart line ID from the request. | `String` | | `tax_id`required | A reference to a tax definition in the taxes array. | `String` | | `calculated_tax`required | The total tax amount for this line item. | `String` | | `calculated_tax_refundable`required | The refundable portion of the tax (usually same as `calculated_tax`). | `String` | | `amount_exempt`required | The amount that's exempt from tax. | `String` | | `amount_taxable`required | The amount subject to the tax. | `String` | | `amount_non_taxable`required | The amount not subject to the tax. | `String` | #### `tax_definition` hash | Attribute | Description | Type | | - | - | - | | `id`required | The unique identifier for the tax definition. | `String` | | `title`required | The name for the tax. | `String` | | `rate`required | The tax rate information. Refer to [tax rate hash](#tax_rate-hash) for more information. | `Object` | | `source`required | The tax source information including jurisdiction. Refer to [tax source hash](#tax_source-hash) for more information. | `Object` | | `liability` | Indicates who's responsible for remitting the tax. Possible values are `Merchant` and `Marketplace`. | `String` | #### `tax_rate` hash | Attribute | Description | Type | | - | - | - | | `type`required | The tax type. Possible values:- `USE_TAX` - `SALES_TAX` - `EXCISE_TAX` - `FEE` - `VAT` - `UNKNOWN` | `String` | | `structure`required | The way the tax is calculated. Possible values:- `STANDARD` - `FLAT` - `QUANTITY` | `String` | | `amount`required | The tax rate as decimal (for example, `0.05` for 5%). | `String` | #### `tax_source` hash | Attribute | Description | Type | | - | - | - | | `tax_jurisdiction`required | The jurisdiction information for the tax. Refer to [tax jurisdiction hash](#tax_jurisdiction-hash) for more information. | `Object` | | `tax_registration` | The tax registration details if applicable. Refer to [tax\_registration hash](#tax_registration-hash) for more information. | `Object` | | `tax_authority` | The tax authority information. Refer to [tax\_authority hash](#tax_authority-hash) for more information. | `Object` | | `situs` | The tax location basis. Possible values:- `ORIGIN` - `DESTINATION` - `SHOP` | `String` | #### `tax_registration` hash | Attribute | Description | Type | | - | - | - | | `code`required | A unique code for the tax registration. | `String` | | `registration_number`required | The tax registration number. | `String` | #### `tax_authority` hash | Attribute | Description | Type | | - | - | - | | `code`required | The code for the tax authority to which the taxes would be remitted. | `String` | #### `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` | | `name`required | The name of the tax jurisdiction. | `String` | | `type`required | Type of jurisdiction. Possible values:- `APO` - `BOROUGH` - `CITY` - `COUNTRY` - `COUNTY` - `DISTRICT` - `FPO` - `LOCAL_IMPROVEMENT_DISTRICT` - `PARISH` - `PROVINCE` - `SPECIAL_PURPOSE_DISTRICT` - `STATE` - `TERRITORY` - `TOWNSHIP` - `TRANSIT_DISTRICT` - `TRADE_BLOCK` | `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` | *** ## Error 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: ```json { "idempotent_key": "8ec2ef67f35980ea6a7842b122f2549f", "currency": "CAD", "delivery_group_taxes": [], "taxes": [], "partner_errors": [ { "code": "MALFORMED_ADDRESS", "message": "Address is not valid" } ] } ``` #### Error schema | Attribute | Description | Type | | - | - | - | | `code`required | The code identifying the class of error. Possible values:- `MALFORMED_ADDRESS`: The address is malformed. For example, it has a non-existent zip code or lacks enough fields to determine the location. - `BAD_DATA`: Field validation failed. Examples include future dates in the creation field or negative money amounts. - `MALFORMED_PAYLOAD`:The request is malformed due to conflicting field relationships. For example, the origin and delivery addresses are in different states, but the delivery method is `LOCAL`. | `String` | | `message`required | A description of what happened in this instance. Includes details about the part of the request that was the cause. | `String` | *** * [Tax calculation request](https://shopify.dev/docs/apps/build/tax/tax-calculations.md#tax-calculation-request) * [Tax calculation response](https://shopify.dev/docs/apps/build/tax/tax-calculations.md#tax-calculation-response) * [Error handling](https://shopify.dev/docs/apps/build/tax/tax-calculations.md#error-handling)