Docs
Contract APIs
Tax provider

Tax Provider API

Use BigCommerce’s platform-to-platform Tax Provider API to integrate a tax calculation engine into the BigCommerce storefront and control panel. Supports estimate, adjust, commit, and void operations. For more information, see Tax Provider API Overview.

Note

  • Document submission operations are only triggered when the Submit Order Data provider setting is enabled.

Estimate taxes

POST /estimate

Request

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

  • in header

Parameters

  • app_domain in path - string
  • X-Bc-Store-Hash in header - string
    required
    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.
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.

Body

object | application/json
Each QuoteRequest represents an order. In addition to transaction details, it contains a documents array of one or more DocumentRequest objects, which represent distinct combinations of origin and fulfillment addresses and the tax-relevant contents of those consignments. This is similar to an "order" in other BigCommerce APIs.

  • id    string
    required

    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_code    string
    required

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

  • customer    object
    required

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

  • transaction_date    string
    required

    ISO 8601 formatted date the shopper placed this order. Dates will be provided in UTC.

  • documents    array[object]
    required

    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.

example

{
"id": "3f0c857e-2c55-443e-a89b-c3c4d8a29605",
"currency_code": "USD",
"customer": {
"customer_id": "0",
"customer_group_id": "0",
"taxability_code": ""
},
"transaction_date": "2019-08-13T03:17:37+00:00",
"documents": [
{
"id": "5d522b889d3d9",
"billing_address": {
"line1": "",
"line2": "",
"city": "",
"region_name": "",
"region_code": "",
"country_name": "",
"country_code": "",
"postal_code": "",
"company_name": "",
"type": "RESIDENTIAL"
},
"destination_address": {
"line1": "",
"line2": "",
"city": "Van Wert",
"region_name": "Ohio",

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.

Body

object | application/json

  • id    string
    required

    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.

  • documents    array[object]
    required

    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.

response

{
"documents": [
{
"id": "5d522b889d3d9",
"items": [
{
"id": "088c7465-e5b8-4624-a220-0d9faa82e7cb",
"price": {
"amount_inclusive": 675,
"amount_exclusive": 450,
"total_tax": 225,
"tax_rate": 0.5,
"sales_tax_summary": [
{
"name": "Brutal Tax",
"rate": 0.5,
"amount": 225,
"tax_class": {
"class_id": "0",
"name": "Brutal Tax",
"code": "US"
},
"id": "Brutal Tax"
}
]
},
"type": "item",

Void tax quote

POST /void

Request

Invalidate the persisted tax quote as identified by the given unique ID. Relevant to order cancellations, full refunds, or moving an order from a paid status to an unpaid status.

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.

Authentication

  • in header

Parameters

  • app_domain in path - string
  • id in query - string
    required
    Unique ID identifying the existing, persisted tax quote that will be voided.
  • X-Bc-Store-Hash in header - string
    required
    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.

Response

OK

Commit Tax Quote

POST /commit

Request

Submit the quote request to be persisted by the enabled third-party tax provider. A commit operation is intended to be submitted once only, when the Order has been confirmed and paid.

Merchants may adjust when commit operations occur by adjusting the document submission strategy in their store tax settings. The selected document submission strategy will adjust whether order status or payment status is used to determine if the order is paid. For more information, see the Tax Settings API Reference.

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.

Authentication

  • in header

Parameters

  • app_domain in path - string
  • X-Bc-Store-Hash in header - string
    required
    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.

Body

object | application/json
Each QuoteRequest represents an order. In addition to transaction details, it contains a documents array of one or more DocumentRequest objects, which represent distinct combinations of origin and fulfillment addresses and the tax-relevant contents of those consignments. This is similar to an "order" in other BigCommerce APIs.

  • id    string
    required

    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_code    string
    required

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

  • customer    object
    required

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

  • transaction_date    string
    required

    ISO 8601 formatted date the shopper placed this order. Dates will be provided in UTC.

  • documents    array[object]
    required

    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.

example

{
"id": "113",
"currency_code": "USD",
"customer": {
"customer_id": "0",
"customer_group_id": "0",
"taxability_code": ""
},
"transaction_date": "2019-08-13T03:40:15+00:00",
"documents": [
{
"id": "shipping_14",
"billing_address": {
"line1": "402 S Vine St",
"line2": "",
"city": "Van Wert",
"region_name": "Ohio",
"region_code": "OH",
"country_name": "United States",
"country_code": "US",
"postal_code": "45891",
"company_name": "",
"type": "RESIDENTIAL"
},
"destination_address": {
"line1": "402 S Vine St",
"line2": "",
"city": "Van Wert",

Response

OK

Body

object | application/json

  • id    string
    required

    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.

  • documents    array[object]
    required

    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.

response

{
"documents": [
{
"external_id": "sample-doc-123456789",
"id": "shipping_14",
"items": [
{
"id": "product_13",
"price": {
"amount_inclusive": 675,
"amount_exclusive": 450,
"total_tax": 225,
"tax_rate": 0.5,
"sales_tax_summary": [
{
"name": "Brutal Tax",
"rate": 0.5,
"amount": 225,
"tax_class": {
"class_id": "0",
"name": "Brutal Tax",
"code": "US"
},
"id": "Brutal Tax"
}
]
},

Adjust Tax Quote

POST /adjust

Request

Replace the persisted tax quote (identified by the given unique ID) with the provided quote request (represented by the AdjustRequest).

Relevant for returns, partial refunds, and other Order modifications where there have been changes to the tax liabilities.

The returned Tax Quote response is expected to be the same to a response returned by an equivalent response to estimate or commit methods.

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.

Authentication

  • in header

Parameters

  • app_domain in path - string
  • X-Bc-Store-Hash in header - string
    required
    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.
  • id in query - string
    required
    Unique ID identifying the existing, persisted tax quote that will be adjusted.

Body

object | application/json
An AdjustRequest contains the same data as a standard QuoteRequest with added detail of the adjustment operation.

  • adjust_description    string

    Specifies the reason for the adjustment operation, for auditing purposes. May be a custom, user-entered description.

  • id    string
    required

    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_code    string
    required

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

  • customer    object
    required

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

  • transaction_date    string
    required

    ISO 8601 formatted date the shopper placed this order. Dates will be provided in UTC.

  • documents    array[object]
    required

    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.

example

{
"adjust_description": "string",
"id": "string",
"currency_code": "string",
"customer": {
"customer_id": "string",
"customer_group_id": "0",
"taxability_code": "string"
},
"transaction_date": "2019-08-24T14:15:22Z",
"documents": [
{
"id": "string",
"billing_address": {
"line1": "string",
"line2": "string",
"city": "Sydney",
"region_name": "New South Wales",
"region_code": "NSW",
"country_name": "Australia",
"country_code": "AU",
"postal_code": "2007",
"company_name": "string",
"type": "RESIDENTIAL"
},
"destination_address": {
"line1": "string",

Response

Returned Tax Quote response matches the updated QuoteRequest provided to the service method.

Body

object | application/json

  • id    string
    required

    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.

  • documents    array[object]
    required

    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.

response

{
"documents": [
{
"id": "5d522b889d3d9",
"items": [
{
"id": "088c7465-e5b8-4624-a220-0d9faa82e7cb",
"price": {
"amount_inclusive": 675,
"amount_exclusive": 450,
"total_tax": 225,
"tax_rate": 0.5,
"sales_tax_summary": [
{
"name": "Brutal Tax",
"rate": 0.5,
"amount": 225,
"tax_class": {
"class_id": "0",
"name": "Brutal Tax",
"code": "US"
},
"id": "Brutal Tax"
}
]
},
"type": "item",

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?
Validate connection optionsEstimate taxes