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
        • Abandoned Carts
        • Carts
        • Channels
        • Checkouts
        • Currencies
        • Customer Segmentation
        • Geography
        • Infrastructure Hosting
        • Inventory
        • Orders
        • Order Operations
        • Pickup
        • Pickup Methods
        • Pickup Options
        • Pricing
        • Price Lists
        • Promotions
        • Promotion Settings
        • Redirects
        • Scripts
        • Settings
        • Shipping
        • Sites
        • Subscribers
        • System Logs
        • Tax
          • Tax Classes
              • GETGet Tax Settings
              • PUTUpdate Tax Settings
        • Wishlists
      • Payments
  • GraphQL
    • Overview
  • MCP
    • Overview
Dev Portal
LogoLogo
RESTAdminManagementTaxTax Settings

Update Tax Settings

PUT
https://api.bigcommerce.com/stores/:store_hash/v3/tax/settings
PUT
/stores/:store_hash/v3/tax/settings
$curl -X PUT https://api.bigcommerce.com/stores/store_hash/v3/tax/settings \
> -H "Accept: application/json" \
> -H "X-Auth-Token: <apiKey>" \
> -H "Content-Type: application/json" \
> -d '{}'
1{
2 "data": {
3 "tax_entered_with_prices": true,
4 "price_display_settings": {
5 "control_panel_price_display_strategy": "ZONE",
6 "invoice_price_display_strategy": "ZONE"
7 },
8 "fallback_strategy": "FIXED",
9 "should_subtract_store_tax": true,
10 "should_use_geolocation_to_determine_guest_shopper_tax_zone": false,
11 "guest_shopper_tax_zone_id": 5,
12 "store_tax_zone_id": 3,
13 "document_submission_strategy": "ON_PAYMENT_CAPTURE",
14 "rounding_strategy": "RATE_ROUNDING"
15 },
16 "meta": {}
17}

Updates global-level tax settings.

Was this page helpful?
Previous

Get Tax Settings

Next

Check Zone for Address

Built with

Authentication

X-Auth-Tokenstring
### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Information & Settings | modify | `store_v2_information` | | Information & Settings | read-only | `store_v2_information_read_only` | ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

Path parameters

store_hashstringRequired
Permanent ID of the BigCommerce store.

Headers

AcceptstringRequiredDefaults to application/json
The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.

Request

This endpoint expects an object.
tax_entered_with_pricesbooleanOptional
Whether prices entered on this store include a tax component or not.
price_display_settingsobjectOptional
Settings that describe how prices display at the global level.
fallback_strategyenumOptionalDefaults to FIXED

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 values:
should_subtract_store_taxbooleanOptionalDefaults to true

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.

should_use_geolocation_to_determine_guest_shopper_tax_zonebooleanOptionalDefaults to false

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.

guest_shopper_tax_zone_idintegerOptionalDefaults to 1

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.

store_tax_zone_idintegerOptionalDefaults to 1

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.

document_submission_strategyenumOptionalDefaults to ON_PAYMENT_CAPTURE

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

Allowed values:
rounding_strategyenumOptionalDefaults to RATE_ROUNDING

This setting affects the rounding behavior of tax amounts calculated by the basic tax provider. The NO_ROUNDING option offers a high accuracy total tax amount for orders. The RATE_ROUNDING option means every resulting tax rate amount has been rounded based on the active currency’s precision settings. Note that tax is always calculated on the line item amount after discounts.

Allowed values:

Response

OK
dataobject
metaobject
Response metadata.

Errors

422
Unprocessable Entity Error

OAuth scopes

UI NamePermissionParameter
Information & Settingsmodifystore_v2_information
Information & Settingsread-onlystore_v2_information_read_only

Authentication header

HeaderArgumentDescription
X-Auth-Tokenaccess_tokenFor more about API accounts that generate access_tokens, see our Guide to API Accounts.

Further reading

For example requests and more information about authenticating BigCommerce APIs, see Authentication and Example Requests.

For more about BigCommerce OAuth scopes, see our Guide to API Accounts.

For a list of API status codes, see API Status Codes.

The MIME type of the response body.