Unique ID identifying the existing, persisted tax quote that will be adjusted.

Unique ID identifying the existing, persisted tax quote that will be voided.

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.

X-Bc-Store-Hash

Requests may have partial Address data. For example, the BigCommerce Cart page has the "Estimate Shipping & Tax" feature which is only expected to supply Country, Region and Postal Code.

If this is a commercial address, the associated company’s name.

Apartment, unit, suite, building, floor, etc.

If available, the short code/acronym for the region. For example, "CA" for "California" or "NSW" for "New South Wales".

The absolute amount of tax applied to the item this SalesTax component is attached to, for this component rate. For example, if an item was $10 and this was a 5% component tax rate, the amount would be 0.50 (50 cents)

Optional unique identifier for this sales tax, describing the relevant tax classification rule on the tax provider platform.

Supplying an identifier allows BigCommerce to group related taxes together from all items in the order.

This identifier is persisted by BigCommerce and may be desirable for auditing purposes between BigCommerce and the tax provider. Currently supports persisting integer values only (the string type indicates we may support UUID values in the future).

The human-readable name of this tax. Used for reporting. Depending on store configuration, may also be visible in the itemization of taxes at checkout, on invoices, and in control panel views. May not be empty.

Decimal tax rate applied by this component tax rate. Tax rates support up to four decimal places. For example "0.1" for 10% and "0.0125" for 1.25%.

The ID of the tax class defined in the merchant’s BigCommerce store. May have a UUID value.

The provider-specific tax code for this item. Items can be classified with tax codes relevant to each tax provider, configured by the merchant, and assigned to their products within BigCommerce. A tax code is intended to apply to multiple products. This code should match the tax codes provided by the third-party integration.

The human-readable name of this tax class in the merchant’s BigCommerce store.

The type of item for the line item in the document.

The type of item for the line item in the document.

Tax estimate requests for order-level refunds have an additional line item with the type `refund`.

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

An **AdjustRequest** contains the same data as a standard **QuoteRequest** with added detail of the adjustment operation.

AdjustRequest

Each **DocumentRequest** represents an order or part of an order of items fulfilled from a single origin address to a single destination address. In addition to shipping and billing details, a document request includes the collection of items in the shipment, with tax-relevant information for each item. Multi-address orders, in which items ship to or from multiple addresses, require at least one **DocumentRequest** per combination of sender-recipient addresses. These are similar to "consignments" or "shipments" in other BigCommerce APIs.

Handling line item present in each document request.

A unique identifier for this consignment. This value can be expected to be unique within an individual quote request but may be duplicated within subsequent quote requests. A digital consignment will see a prefix **DigitalDelivery_** followed by the Order ID.

Collection of one or more items contained within this consignment that need to be assessed for tax liabilities. An item may or may not have gift wrapping.

Shipping line item present in each document request.

DocumentRequest

An **ItemRequest** represents required information relating to completing tax calculations for a specific line item.

A unique identifier for this item used to map responses back to the corresponding item on the order.

The UPC or SKU of the item. The UPC is used when both UPC and SKU values are available on the item. Empty string if both UPC and SKU are not available.

The SKU of the item. Empty string if SKU is not available.

The final sale price (after discounts, bulk pricing, price lists, etc.) prior to having taxes calculated. If the merchant lists prices inclusive of tax, this price will already be tax inclusive, and so the tax provider will instead calculate the amount of tax that was already included in this price. For multiple quantities, this price includes that multiplication.

Note: This amount will be **negative** for order-level refunds and may be **zero** for line item refunds.

Note: **Tax Inclusive** and **Tax Exclusive** prices cannot be added together.

Flag whether or not this item is always tax-exempt. For example, gift certificate purchases and order-level refunds are tax-exempt. Tax-exempt items are included in the request for auditing purposes.

Merchants may opt to include additional properties that a tax provider can choose to support, factoring these values into tax calculation.

ItemRequest

A simple key value pairing allowing merchants to provide an additional input into a tax providerʼs tax calculation.

Used by tax providers to programmatically identify a specific calculation input.

The value that will be factored into the tax providerʼs tax calculation rules, where supported.

TaxProperty

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.

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

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

The BigCommerce customer group ID assigned to this customer. The default value will be provided if the customer has no group assigned. May be provided as a UUID.

The ID of the shoppers customer account in BigCommerce. May be provided as a UUID.

If applicable, the tax exemption code of the shopper’s customer account. A taxability code is intended to apply to multiple customers. This code should match the exemption codes provided by the third-party integration.

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.

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.

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

QuoteRequest

An optional unique identifier for the document stored in the external provider’s system. Currently not used in any end-to-end operation, but may be logged by BigCommerce and thus be helpful when resolving issues.

A unique identifier for this consignment. Must match the ID of the corresponding Document Request.

Collection of items contained within this consignment that have had tax liabilities calculated. An item may or may not have gift wrapping.

Document

The tax liabilities calculated for a specific item.

Note: Tax liabilities should be calculated with **quantity** accounted for.

A unique identifier for the line item these tax liabilities are calculated for. Must match the corresponding request line item ID.

Item

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.

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.

Quote

The price of this line item exclusive of tax. Must be equal to **amount_inclusive** - **total_tax**.

The price of this line item inclusive of tax. Must be equal to **amount_exclusive** + **total_tax**.

Breakdown of the sales taxes that applied to this item.

The total tax rate that applied to this item. This is the aggregated rate of the individual rates in **sales_tax_summary**.

The total amount of tax that applied to this line item. Must be equal to **amount_inclusive** - **amount_exclusive**.

TaxPrice

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](/docs/rest-contracts/tax-app-connection#update-a-connection) request. `profile` is an optional field and will be used with supporting providers only.

For more, see [developer-configured authentication](/docs/start/authentication#developer-configured-authentication) for Provider APIs.

BigCommerce

Use BigCommerce’s platform-to-platform Tax Provider API to integrate a tax calculation engine into the BigCommerce storefront and control panel. Supports [estimate](/docs/rest-contracts/tax#estimate-taxes), [adjust](/docs/rest-contracts/tax#adjust-tax-quote), [commit](/docs/rest-contracts/tax#commit-tax-quote), and [void](/docs/rest-contracts/tax#void-tax-quote) operations. For more information, see [Tax Provider API Overview](/docs/integrations/tax).

Tax Provider API

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.

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

General response that points to an issue with the incoming request that means a valid response is unable to be returned.

Response to indicate that the merchant’s authentication credentials are invalid. The merchant will receive an update in their Store Logs.

General response that points to an error on the tax provider side. These types of errors should be promptly resolved by the tax provider.

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.

> 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.

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.

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.

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.

Fallback Tax will be used for this transaction. General response that points to an issue with the incoming request that means a valid response is unable to be returned.

Fallback Tax will be used for this transaction. General response that points to an error on the tax provider side. These types of errors should be promptly resolved by the tax provider.

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.

The [URL authority](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#authority) of your appʼs server.

Tax Provider API

Estimate taxes

Void tax quote

Commit Tax Quote

Adjust Tax Quote