BigCommerce Tax Provider is a powerful tool designed to simplify the complicated process of managing taxes for online businesses. This software seamlessly integrates with the BigCommerce platform to automatically calculate and apply the appropriate tax rates for each transaction based on the customer's location. With this tool, businesses can ensure compliance with tax regulations, reduce the risk of errors, and streamline their tax reporting processes.
openapi: 3.0.3
info:
title: BigCommerce Tax Provider API
version: '1.0'
description: >-
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).
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: [email protected]
tags:
- name: Tax Provider
servers:
- url: https://{app_domain}
variables:
app_domain:
default: your_app.example.com
description: >-
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.
paths:
/estimate:
post:
summary: BigCommerce Estimate Taxes
tags:
- Tax Provider
description: >-
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.
operationId: estimateTaxes
parameters:
- $ref: '#/components/parameters/header-storehash'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/request-quote'
examples:
example:
value:
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
region_code: OH
country_name: United States
country_code: US
postal_code: '45892'
company_name: ''
type: RESIDENTIAL
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'
company_name: ''
type: COMMERCIAL
shipping:
id: 5d522b889d3d9
item_code: Flat Rate
name: Shipping to Van Wert, United States 45891
price:
amount: 10
tax_inclusive: false
quantity: 1
tax_class:
code: ''
class_id: '6'
name: Shipping
tax_exempt: false
type: shipping
handling:
id: 5d522b889d3d9
item_code: Flat Rate
name: Handling for Van Wert, United States 45891
price:
amount: 0
tax_inclusive: false
quantity: 1
tax_class:
code: ''
class_id: '6'
name: Handling
tax_exempt: false
type: handling
items:
- id: 088c7465-e5b8-4624-a220-0d9faa82e7cb
item_code: ABS
name: '[Sample] Able Brewing System'
price:
amount: 450
tax_inclusive: false
quantity: 2
tax_class:
code: ''
class_id: '0'
name: Default Tax Class
tax_exempt: false
type: item
wrapping:
id: d2675662-6326-4a23-9107-ab71fa6a21a1
item_code: ''
name: 'Wrapping: [Sample] Canvas Laundry Cart'
price:
amount: 5
tax_inclusive: false
quantity: 1
tax_class:
code: ''
class_id: '6'
name: Wrapping
tax_exempt: false
type: wrapping
- id: d2675662-6326-4a23-9107-ab71fa6a21a1
item_code: CLC
name: '[Sample] Canvas Laundry Cart'
price:
amount: 200
tax_inclusive: false
quantity: 1
tax_class:
code: ''
class_id: '0'
name: Default Tax Class
tax_exempt: false
type: item
wrapping:
id: d2675662-6326-4a23-9107-ab71fa6a21a1
item_code: ''
name: 'Wrapping: [Sample] Canvas Laundry Cart'
price:
amount: 5
tax_inclusive: false
quantity: 1
tax_class:
code: ''
class_id: '6'
name: Wrapping
tax_exempt: false
type: wrapping
description: >-
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.
required: true
responses:
'200':
description: >-
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.
content:
application/json:
schema:
$ref: '#/components/schemas/response-quote'
examples:
response:
value:
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
wrapping:
id: d2675662-6326-4a23-9107-ab71fa6a21a1
price:
amount_exclusive: 5
amount_inclusive: 7.5
sales_tax_summary:
- amount: 2.5
id: '1'
name: BRUTAL TAX
rate: 0.5
tax_class:
class_id: '6'
code: US
name: Wrapping
tax_rate: 0.5
total_tax: 2.5
type: wrapping
- id: d2675662-6326-4a23-9107-ab71fa6a21a1
price:
amount_inclusive: 300
amount_exclusive: 200
total_tax: 100
tax_rate: 0.5
sales_tax_summary:
- name: Brutal Tax
rate: 0.5
amount: 100
tax_class:
class_id: '0'
name: Brutal Tax
code: US
id: Brutal Tax
type: item
wrapping:
id: d2675662-6326-4a23-9107-ab71fa6a21a1
price:
amount_exclusive: 5
amount_inclusive: 7.5
sales_tax_summary:
- amount: 2.5
id: '1'
name: BRUTAL TAX
rate: 0.5
tax_class:
class_id: '6'
code: US
name: Wrapping
tax_rate: 0.5
total_tax: 2.5
type: wrapping
shipping:
id: 5d522b889d3d9
price:
amount_inclusive: 15
amount_exclusive: 10
total_tax: 5
tax_rate: 0.5
sales_tax_summary:
- name: Brutal Tax
rate: 0.5
amount: 5
tax_class:
class_id: '0'
name: Brutal Tax
code: US
id: Brutal Tax
type: shipping
handling:
id: 5d522b889d3d9
price:
amount_inclusive: 0
amount_exclusive: 0
total_tax: 0
tax_rate: 0.5
sales_tax_summary:
- name: Brutal Tax
rate: 0.5
amount: 0
tax_class:
class_id: '0'
name: Brutal Tax
code: US
id: Brutal Tax
type: handling
id: 3f0c857e-2c55-443e-a89b-c3c4d8a29605
'400':
description: >-
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.
'401':
description: >-
Response to indicate that the merchant’s authentication credentials
are invalid. The merchant will receive an update in their Store
Logs.
'500':
description: >-
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.
/void:
post:
summary: BigCommerce Void Tax Quote
description: >-
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.
operationId: voidTaxQuote
parameters:
- name: id
in: query
description: >-
Unique ID identifying the existing, persisted Tax Quote that will be
voided.
required: true
schema:
type: string
- $ref: '#/components/parameters/header-storehash'
responses:
'200':
description: OK
'400':
description: >-
General response that points to an issue with the incoming request
that means a valid response is unable to be returned.
'401':
description: >-
Response to indicate that the merchant’s authentication credentials
are invalid. The merchant will receive an update in their Store
Logs.
'500':
description: >-
General response that points to an error on the tax provider side.
These types of errors should be promptly resolved by the tax
provider.
tags:
- Tax Provider
/commit:
post:
summary: BigCommerce Commit Tax Quote
description: >-
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.
operationId: commitTaxQuote
parameters:
- $ref: '#/components/parameters/header-storehash'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/request-quote'
examples:
example:
value:
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
region_name: Ohio
region_code: OH
country_name: United States
country_code: US
postal_code: '45891'
company_name: ''
type: RESIDENTIAL
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'
company_name: ''
type: COMMERCIAL
shipping:
id: shipping_14
item_code: Flat Rate
name: Shipping to Van Wert, United States 45891
price:
amount: 10
tax_inclusive: false
quantity: 1
tax_class:
code: ''
class_id: '6'
name: Shipping
tax_exempt: false
type: shipping
handling:
id: handling_14
item_code: Flat Rate
name: Handling for Van Wert, United States 45891
price:
amount: 0
tax_inclusive: false
quantity: 1
tax_class:
code: ''
class_id: '6'
name: Handling
tax_exempt: false
type: handling
items:
- id: product_13
item_code: ABS
name: '[Sample] Able Brewing System'
price:
amount: 450
tax_inclusive: false
quantity: 2
tax_class:
code: ''
class_id: '0'
name: Default Tax Class
tax_exempt: false
type: item
wrapping:
id: product_14
item_code: ''
name: 'Wrapping: Holiday'
price:
amount: 5
tax_inclusive: false
quantity: 1
tax_class:
code: ''
class_id: '6'
name: Wrapping
tax_exempt: false
type: wrapping
- id: product_14
item_code: CLC
name: '[Sample] Canvas Laundry Cart'
price:
amount: 200
tax_inclusive: false
quantity: 1
tax_class:
code: ''
class_id: '0'
name: Default Tax Class
tax_exempt: false
type: item
wrapping:
id: product_14
item_code: ''
name: 'Wrapping: Holiday'
price:
amount: 5
tax_inclusive: false
quantity: 1
tax_class:
code: ''
class_id: '6'
name: Wrapping
tax_exempt: false
type: wrapping
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/response-quote'
examples:
response:
value:
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
type: item
wrapping:
id: product_14
price:
amount_exclusive: 5
amount_inclusive: 7.5
sales_tax_summary:
- amount: 2.5
id: '1'
name: BRUTAL TAX
rate: 0.5
tax_class:
class_id: '6'
code: US
name: Wrapping
tax_rate: 0.5
total_tax: 2.5
type: wrapping
- id: product_14
price:
amount_inclusive: 300
amount_exclusive: 200
total_tax: 100
tax_rate: 0.5
sales_tax_summary:
- name: Brutal Tax
rate: 0.5
amount: 100
tax_class:
class_id: '0'
name: Brutal Tax
code: US
id: Brutal Tax
type: item
wrapping:
id: product_14
price:
amount_exclusive: 5
amount_inclusive: 7.5
sales_tax_summary:
- amount: 2.5
id: '1'
name: BRUTAL TAX
rate: 0.5
tax_class:
class_id: '6'
code: US
name: Wrapping
tax_rate: 0.5
total_tax: 2.5
type: wrapping
shipping:
id: shipping_14
price:
amount_inclusive: 15
amount_exclusive: 10
total_tax: 5
tax_rate: 0.5
sales_tax_summary:
- name: Brutal Tax
rate: 0.5
amount: 5
tax_class:
class_id: '0'
name: Brutal Tax
code: US
id: Brutal Tax
type: shipping
handling:
id: handling_14
price:
amount_inclusive: 0
amount_exclusive: 0
total_tax: 0
tax_rate: 0.5
sales_tax_summary:
- name: Brutal Tax
rate: 0.5
amount: 0
tax_class:
class_id: '0'
name: Brutal Tax
code: US
id: Brutal Tax
type: handling
id: '113'
'400':
description: >-
General response that points to an issue with the incoming request
that means a valid response is unable to be returned.
'401':
description: >-
Response to indicate that the merchant’s authentication credentials
are invalid. The merchant will receive an update in their Store
Logs.
'500':
description: >-
General response that points to an error on the tax provider side.
These types of errors should be promptly resolved by the tax
provider.
tags:
- Tax Provider
/adjust:
post:
responses:
'200':
description: >-
Returned Tax Quote response matches the updated QuoteRequest
provided to the service method.
content:
application/json:
schema:
$ref: '#/components/schemas/response-quote'
examples:
response:
value:
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
wrapping:
id: d2675662-6326-4a23-9107-ab71fa6a21a1
price:
amount_exclusive: 5
amount_inclusive: 7.5
sales_tax_summary:
- amount: 2.5
id: '1'
name: BRUTAL TAX
rate: 0.5
tax_class:
class_id: '6'
code: US
name: Wrapping
tax_rate: 0.5
total_tax: 2.5
type: wrapping
- id: d2675662-6326-4a23-9107-ab71fa6a21a1
price:
amount_inclusive: 300
amount_exclusive: 200
total_tax: 100
tax_rate: 0.5
sales_tax_summary:
- name: Brutal Tax
rate: 0.5
amount: 100
tax_class:
class_id: '0'
name: Brutal Tax
code: US
id: Brutal Tax
type: item
wrapping:
id: d2675662-6326-4a23-9107-ab71fa6a21a1
price:
amount_exclusive: 5
amount_inclusive: 7.5
sales_tax_summary:
- amount: 2.5
id: '1'
name: BRUTAL TAX
rate: 0.5
tax_class:
class_id: '6'
code: US
name: Wrapping
tax_rate: 0.5
total_tax: 2.5
type: wrapping
shipping:
id: 5d522b889d3d9
price:
amount_inclusive: 15
amount_exclusive: 10
total_tax: 5
tax_rate: 0.5
sales_tax_summary:
- name: Brutal Tax
rate: 0.5
amount: 5
tax_class:
class_id: '0'
name: Brutal Tax
code: US
id: Brutal Tax
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/tax-provider-openapi-original.yml