Docs
Management API
Tax settings

Tax Settings

Manage tax settings

Get Tax Settings

GET /tax/settings

Request

Retrieves global-level tax settings.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.

example

curl --request GET \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/tax/settings' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

OK

Body

object | application/json

  • data    object

  • meta    object

    Response metadata.

example

{
"data": {
"tax_entered_with_prices": true,
"price_display_settings": {
"control_panel_price_display_strategy": "ZONE",
"invoice_price_display_strategy": "ZONE"
},
"fallback_strategy": "FIXED",
"should_subtract_store_tax": true,
"should_use_geolocation_to_determine_guest_shopper_tax_zone": false,
"guest_shopper_tax_zone_id": 1,
"store_tax_zone_id": 1,
"document_submission_strategy": "ON_PAYMENT_CAPTURE"
},
"meta": {}
}

Update Tax Settings

PUT /tax/settings

Request

Updates global-level tax settings.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json

  • tax_entered_with_prices    boolean

    Whether prices entered on this store include a tax component or not.

  • price_display_settings    object

    Settings that describe how prices display at the global level.

  • fallback_strategy    string

    Describes the fallback behavior that applies when a tax provider produces an error. A merchant may decide to use a flat 10% fallback tax rate, their basic tax settings, or to block the transaction until they achieve a successful result.

    Allowed: FIXED | BASIC | DISABLE

    Default: FIXED

  • should_subtract_store_tax    boolean

    This setting applies only if a merchant enters tax-inclusive prices. When enabled, the store subtracts the itemʼs store tax rate before calculating tax using the shopperʼs tax zone. The tax-exclusive amount will be the same across all tax zones. When disabled, the tax-inclusive price remains the same across all tax zones; only the tax amount will vary based on the shopperʼs location. The tax-exclusive amount may vary among tax zones. These calculations are relevant for tax pricing and tax quotations that use basic tax.

    Default: true

  • should_use_geolocation_to_determine_guest_shopper_tax_zone    boolean

    This setting determines which tax zone a store uses to estimate tax for guest shoppers. When enabled, the store identifies a country-level tax zone based on the geolocation of a guest shopper. The store then applies the corresponding tax zone to estimate taxes. When disabled, the store identifies the zone using the provided guest_shopper_tax_zone_id field instead. Only the tax zones you configure can be matched to the guest shopper's geolocation.

    Default: false

  • guest_shopper_tax_zone_id    integer

    ID for the tax zone a store uses when estimating tax for guest shoppers. The store uses this zone if you disable should_use_geolocation_to_determine_guest_shopper_tax_zone. The store also uses this zone if there is no matching country-level tax zone for the geolocation.

    Default: 1

  • store_tax_zone_id    integer

    ID for the tax zone a store uses when subtracting store tax. This setting applies only if a merchant enters tax-inclusive prices and subtracts store tax before tax calculation.

    Default: 1

  • document_submission_strategy    string

    This setting determines whether BigCommerce submits tax documents to third-party tax providers when orders are created or when payments are captured online.

    Allowed: ON_PAYMENT_CAPTURE | ON_ORDER_CREATION

    Default: ON_PAYMENT_CAPTURE

example

{
"tax_entered_with_prices": true,
"price_display_settings": {
"control_panel_price_display_strategy": "ZONE",
"invoice_price_display_strategy": "ZONE"
},
"fallback_strategy": "FIXED",
"should_subtract_store_tax": true,
"should_use_geolocation_to_determine_guest_shopper_tax_zone": false,
"guest_shopper_tax_zone_id": 1,
"store_tax_zone_id": 1,
"document_submission_strategy": "ON_PAYMENT_CAPTURE"
}

Response

OK

Body

object | application/json

  • data    object

  • meta    object

    Response metadata.

example

{
"data": {
"tax_entered_with_prices": true,
"price_display_settings": {
"control_panel_price_display_strategy": "ZONE",
"invoice_price_display_strategy": "ZONE"
},
"fallback_strategy": "FIXED",
"should_subtract_store_tax": true,
"should_use_geolocation_to_determine_guest_shopper_tax_zone": false,
"guest_shopper_tax_zone_id": 1,
"store_tax_zone_id": 1,
"document_submission_strategy": "ON_PAYMENT_CAPTURE"
},
"meta": {}
}

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?
Delete Product Tax PropertiesGet Tax Settings