For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dev Portal
DocsAPI ReferenceLearnCommunityChangelog
DocsAPI ReferenceLearnCommunityChangelog
    • About Our APIs
  • REST
    • Overview
      • Overview
      • Shipping Provider
      • Tax Provider
          • POSTEstimate Taxes
          • POSTVoid Tax Quote
          • POSTCommit Tax Quote
          • POSTAdjust Tax Quote
      • Webhooks
  • GraphQL
    • Overview
  • MCP
    • Overview
Dev Portal
LogoLogo
RESTIntegrationsTax Provider

Estimate Taxes

POST
https://your_app.example.com/estimate
POST
/estimate
$curl -X POST https://your_app.example.com/estimate \
>     -H "X-Bc-Store-Hash: X-Bc-Store-Hash" \
>     -H "Content-Type: application/json" \
>     -u "<username>:<password>" \
>     -d '{
>  "id": "3f0c857e-2c55-443e-a89b-c3c4d8a29605",
>  "currency_code": "USD",
>  "customer": {
>    "customer_id": "0",
>    "customer_group_id": "0",
>    "taxability_code": "",
>    "tax_properties": [
>      {
>        "code": "property123",
>        "value": "property-value"
>      }
>    ]
>  },
>  "transaction_date": "2019-08-13T03:17:37+00:00",
>  "documents": [
>    {
>      "id": "5d522b889d3d9",
>      "destination_address": {
>        "line1": "",
>        "line2": "",
>        "city": "Van Wert",
>        "region_name": "Ohio",
>        "region_code": "OH",
>        "country_name": "United States",
>        "country_code": "US",
>        "postal_code": "45892",
>        "type": "RESIDENTIAL",
>        "company_name": ""
>      },
>      "origin_address": {
>        "line1": "2139 W ANDERSON LN",
>        "line2": "",
>        "city": "AUSTIN",
>        "region_name": "Texas",
>        "region_code": "TX",
>        "country_name": "United States",
>        "country_code": "US",
>        "postal_code": "78757",
>        "type": "COMMERCIAL",
>        "company_name": ""
>      },
>      "shipping": {
>        "id": "5d522b889d3d9",
>        "price": {
>          "amount": 10,
>          "tax_inclusive": false
>        },
>        "quantity": 1,
>        "type": "shipping",
>        "item_code": "Flat Rate",
>        "name": "Shipping to Van Wert, United States 45891",
>        "tax_class": {
>          "code": "",
>          "class_id": "6",
>          "name": "Shipping"
>        },
>        "tax_exempt": false
>      },
>      "handling": {
>        "id": "5d522b889d3d9",
>        "price": {
>          "amount": 0,
>          "tax_inclusive": false
>        },
>        "quantity": 1,
>        "type": "handling",
>        "item_code": "Flat Rate",
>        "name": "Handling for Van Wert, United States 45891",
>        "tax_class": {
>          "code": "",
>          "class_id": "6",
>          "name": "Handling"
>        },
>        "tax_exempt": false
>      },
>      "items": [
>        {
>          "id": "088c7465-e5b8-4624-a220-0d9faa82e7cb",
>          "price": {
>            "amount": 450,
>            "tax_inclusive": false
>          },
>          "quantity": 2,
>          "type": "item",
>          "item_code": "ABS",
>          "name": "[Sample] Able Brewing System",
>          "tax_class": {
>            "code": "",
>            "class_id": "0",
>            "name": "Default Tax Class"
>          },
>          "tax_exempt": false,
>          "wrapping": {
>            "id": "d2675662-6326-4a23-9107-ab71fa6a21a1",
>            "price": {
>              "amount": 5,
>              "tax_inclusive": false
>            },
>            "quantity": 1,
>            "type": "wrapping",
>            "item_code": "",
>            "name": "Wrapping: [Sample] Canvas Laundry Cart",
>            "tax_class": {
>              "code": "",
>              "class_id": "6",
>              "name": "Wrapping"
>            },
>            "tax_exempt": false
>          }
>        },
>        {
>          "id": "d2675662-6326-4a23-9107-ab71fa6a21a1",
>          "price": {
>            "amount": 200,
>            "tax_inclusive": false
>          },
>          "quantity": 1,
>          "type": "item",
>          "item_code": "CLC",
>          "name": "[Sample] Canvas Laundry Cart",
>          "tax_class": {
>            "code": "",
>            "class_id": "0",
>            "name": "Default Tax Class"
>          },
>          "tax_exempt": false,
>          "wrapping": {
>            "id": "d2675662-6326-4a23-9107-ab71fa6a21a1",
>            "price": {
>              "amount": 5,
>              "tax_inclusive": false
>            },
>            "quantity": 1,
>            "type": "wrapping",
>            "item_code": "",
>            "name": "Wrapping: [Sample] Canvas Laundry Cart",
>            "tax_class": {
>              "code": "",
>              "class_id": "6",
>              "name": "Wrapping"
>            },
>            "tax_exempt": false
>          }
>        }
>      ],
>      "billing_address": {
>        "line1": "",
>        "line2": "",
>        "city": "",
>        "region_name": "",
>        "region_code": "",
>        "country_name": "",
>        "country_code": "",
>        "postal_code": "",
>        "type": "RESIDENTIAL",
>        "company_name": ""
>      }
>    }
>  ]
>}'
1{
2  "id": "3f0c857e-2c55-443e-a89b-c3c4d8a29605",
3  "documents": [
4    {
5      "id": "5d522b889d3d9",
6      "items": [
7        {
8          "id": "088c7465-e5b8-4624-a220-0d9faa82e7cb",
9          "price": {
10            "amount_inclusive": 675,
11            "amount_exclusive": 450,
12            "total_tax": 225,
13            "tax_rate": 0.5,
14            "sales_tax_summary": [
15              {
16                "name": "Brutal Tax",
17                "rate": 0.5,
18                "amount": 225,
19                "tax_class": {
20                  "code": "US",
21                  "class_id": "0",
22                  "name": "Brutal Tax"
23                },
24                "id": "Brutal Tax"
25              }
26            ]
27          },
28          "type": "item",
29          "wrapping": {
30            "id": "d2675662-6326-4a23-9107-ab71fa6a21a1",
31            "price": {
32              "amount_inclusive": 7.5,
33              "amount_exclusive": 5,
34              "total_tax": 2.5,
35              "tax_rate": 0.5,
36              "sales_tax_summary": [
37                {
38                  "name": "BRUTAL TAX",
39                  "rate": 0.5,
40                  "amount": 2.5,
41                  "tax_class": {
42                    "code": "US",
43                    "class_id": "6",
44                    "name": "Wrapping"
45                  },
46                  "id": "1"
47                }
48              ]
49            },
50            "type": "wrapping"
51          }
52        },
53        {
54          "id": "d2675662-6326-4a23-9107-ab71fa6a21a1",
55          "price": {
56            "amount_inclusive": 300,
57            "amount_exclusive": 200,
58            "total_tax": 100,
59            "tax_rate": 0.5,
60            "sales_tax_summary": [
61              {
62                "name": "Brutal Tax",
63                "rate": 0.5,
64                "amount": 100,
65                "tax_class": {
66                  "code": "US",
67                  "class_id": "0",
68                  "name": "Brutal Tax"
69                },
70                "id": "Brutal Tax"
71              }
72            ]
73          },
74          "type": "item",
75          "wrapping": {
76            "id": "d2675662-6326-4a23-9107-ab71fa6a21a1",
77            "price": {
78              "amount_inclusive": 7.5,
79              "amount_exclusive": 5,
80              "total_tax": 2.5,
81              "tax_rate": 0.5,
82              "sales_tax_summary": [
83                {
84                  "name": "BRUTAL TAX",
85                  "rate": 0.5,
86                  "amount": 2.5,
87                  "tax_class": {
88                    "code": "US",
89                    "class_id": "6",
90                    "name": "Wrapping"
91                  },
92                  "id": "1"
93                }
94              ]
95            },
96            "type": "wrapping"
97          }
98        }
99      ],
100      "shipping": {
101        "id": "5d522b889d3d9",
102        "price": {
103          "amount_inclusive": 15,
104          "amount_exclusive": 10,
105          "total_tax": 5,
106          "tax_rate": 0.5,
107          "sales_tax_summary": [
108            {
109              "name": "Brutal Tax",
110              "rate": 0.5,
111              "amount": 5,
112              "tax_class": {
113                "code": "US",
114                "class_id": "0",
115                "name": "Brutal Tax"
116              },
117              "id": "Brutal Tax"
118            }
119          ]
120        },
121        "type": "shipping"
122      },
123      "handling": {
124        "id": "5d522b889d3d9",
125        "price": {
126          "amount_inclusive": 0,
127          "amount_exclusive": 0,
128          "total_tax": 0,
129          "tax_rate": 0.5,
130          "sales_tax_summary": [
131            {
132              "name": "Brutal Tax",
133              "rate": 0.5,
134              "amount": 0,
135              "tax_class": {
136                "code": "US",
137                "class_id": "0",
138                "name": "Brutal Tax"
139              },
140              "id": "Brutal Tax"
141            }
142          ]
143        },
144        "type": "handling"
145      }
146    }
147  ]
148}
Submit the quote request to retrieve an estimate from the enabled third-party tax provider. Estimates are not expected to be persisted by the tax provider. > Server URL > - For supporting tax providers, the server URL contains the tax providerʼs profile field; for example, `your_profile.example.com`. > - The Try it feature is not currently supported for this endpoint. The following actions can trigger tax estimate requests multiple times during a standard checkout on a BigCommerce storefront, depending on the BigCommerce merchant’s settings. - After selecting a Shipping Method during the “Estimate Shipping & Tax” facility on the Cart page. - After specifying a Shipping Address during a Checkout. - After selecting a Shipping Method during a Checkout. - After specifying a Billing Address during a Checkout. The following actions are not expected to trigger estimate requests. - While anonymously browsing a store’s product catalog. - On the Cart page prior to a Shopper selecting a Shipping Method via “Estimate Shipping & Tax”. - On the Checkout page prior to specifying a Shipping Address. - On the Checkout page, when toggling any option related to using the shopper’s Shipping Address as their Billing Address. The following control panel actions can also trigger tax estimate requests. - Order refund. - Edit order. - Test connection feature in Tax Settings.
Was this page helpful?
Previous

Tax Provider API

Next

Void Tax Quote

Built with

Submit the quote request to retrieve an estimate from the enabled third-party tax provider. Estimates are not expected to be persisted by the tax provider.

Server URL

  • For supporting tax providers, the server URL contains the tax providerʼs profile field; for example, your_profile.example.com.
  • The Try it feature is not currently supported for this endpoint.

The following actions can trigger tax estimate requests multiple times during a standard checkout on a BigCommerce storefront, depending on the BigCommerce merchant’s settings.

  • After selecting a Shipping Method during the “Estimate Shipping & Tax” facility on the Cart page.
  • After specifying a Shipping Address during a Checkout.
  • After selecting a Shipping Method during a Checkout.
  • After specifying a Billing Address during a Checkout.

The following actions are not expected to trigger estimate requests.

  • While anonymously browsing a store’s product catalog.
  • On the Cart page prior to a Shopper selecting a Shipping Method via “Estimate Shipping & Tax”.
  • On the Checkout page prior to specifying a Shipping Address.
  • On the Checkout page, when toggling any option related to using the shopper’s Shipping Address as their Billing Address.

The following control panel actions can also trigger tax estimate requests.

  • Order refund.
  • Edit order.
  • Test connection feature in Tax Settings.

Authentication

AuthorizationBasic
The [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) (developer.mozilla.org) credentials used to authenticate each API request to the tax provider from the associated store; set and update `username`, `password`, and optionally `profile`, using the [Update a Connection](/developer/api-reference/rest/integrations/tax-provider/tax-provider-connection/update-tax-provider-connection) request. `profile` is an optional field and will be used with supporting providers only. For more, see [developer-configured authentication](/developer/docs/overview/api-fundamentals/api-accounts#developer-configured-authentication) for Provider APIs.

Headers

X-Bc-Store-HashstringRequired

BigCommerce will send through the store hash as part of all tax provider operations. Each BigCommerce store on the platform has a unique store hash value for the store’s lifetime. This value can assist in account verification or profile matching responsibilities.

Request

Estimates may not always contain complete data as these requests will be fired at different stages of the shopper checkout. For example, the **Estimate Shipping & Tax** function on the **Cart** page is not expected to provide any billing address data, but the tax provider will still be expected to return a valid estimate.
idstringRequired

Unique ID of the taxable document (order, cart, quote, etc) this tax quote request is being generated for. Will remain consistent for the lifetime of the entity being estimated.

currency_codestringRequired
ISO 4217 3 character currency code that all prices on this request are in.
customerobjectRequired

If the shopper is a registered customer in the merchant’s store, basic details for that customer.

transaction_datedatetimeRequired
ISO 8601 formatted date the shopper placed this order. Tax quotes are expected to reflect taxes applicable on this date. Dates will be provided in UTC.
documentslist of objectsRequired

One or more consignments containing items being purchased by the shopper, including shipping and handling fees that are charged for each consignment. Most orders will contain a single consignment (to a single shipping address), however the BigCommerce platform also supports “Multi-address orders” which allow shoppers to place a single order with items shipped to different addresses.

Response

Noteworthy is that the estimate response does not contain an external ID since there is no expectation that an estimate will result in any persisted tax documents by the tax provider.

idstring

The unique identifier of the tax quote that was requested. This value must either match the ID of the requested quote or be an external ID on the tax provider’s system. This value will be used for future adjust and void operations.

documentslist of objects

Represents an order quote or part of an order quote of tax-relevant items fulfilled from a single origin address to a single destination address, including arrays of shipping and handling fee objects for each item. Most order quotes contain a single document; however, BigCommerce supports “multi-address orders”, which may come from or go to distinct sets of addresses and thus require multiple documents per quote.

Errors

400
Bad Request Error
401
Unauthorized Error
500
Internal Server Error

The HTTP Basic Authentication (developer.mozilla.org) credentials used to authenticate each API request to the tax provider from the associated store; set and update username, password, and optionally profile, using the Update a Connection request. profile is an optional field and will be used with supporting providers only.

For more, see developer-configured authentication for Provider APIs.

Estimates may not always contain complete data as these requests will be fired at different stages of the shopper checkout. For example, the Estimate Shipping & Tax function on the Cart page is not expected to provide any billing address data, but the tax provider will still be expected to return a valid estimate.