BigCommerce Settings is a section within the BigCommerce platform that allows users to customize and control various aspects of their online store. Users can adjust settings related to shipping, tax calculation, payment methods, email notifications, and more. This tool gives merchants the flexibility to tailor their store to their specific needs and preferences, ensuring a seamless and efficient shopping experience for their customers.
openapi: 3.0.3
info:
description: >-
Manage settings and configuration for BigCommerce hosted stores and headless
storefronts.
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: [email protected]
title: BigCommerce Settings V3
version: 3.0.0
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
variables:
store_hash:
default: store_hash
description: Permanent ID of the BigCommerce store.
description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Analytics
- name: Catalog
- name: Email Statuses
- name: Favicon Image
- name: Inventory
- name: Inventory Notifications
- name: Logo
- name: Logo Image
- name: Search Filters
- name: Store Locale
- name: Store Profile
- name: Storefront Category
- name: Storefront Product
- name: Storefront Robotstxt
- name: Storefront Search
- name: Storefront Security
- name: Storefront SEO
- name: Storefront Status
- name: Units of Measurement
paths:
/settings/analytics:
parameters:
- $ref: '#/components/parameters/Accept'
get:
summary: BigCommerce Get All Web Analytics Providers
description: Returns a list of web analytics providers.
operationId: getAnalyticsProviders
parameters:
- $ref: '#/components/parameters/ChannelIdParam'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/AnalyticsProviders'
meta:
$ref: '#/components/schemas/MetaOpen'
tags:
- Analytics
/settings/analytics/{id}:
parameters:
- $ref: '#/components/parameters/Accept'
- name: id
in: path
description: Web Analytics Provider ID.
required: true
schema:
type: integer
get:
summary: BigCommerce Get a Web Analytics Provider
description: Returns a single web analytics provider data for a default channel.
operationId: getAnalyticsProvider
parameters:
- $ref: '#/components/parameters/ChannelIdParam'
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsProvider'
'400':
description: Bad request. Authentication Required.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse400'
'404':
description: >-
The requested resource was not found. Please specify valid Web
Analytics Provider ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse404'
tags:
- Analytics
put:
summary: BigCommerce Update a Web Analytics Provider
description: Updates a single web analytics provider data for a default channel.
operationId: updateAnalyticsProvider
parameters:
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/ChannelIdParam'
requestBody:
content:
application/json:
schema:
description: ''
type: object
properties:
channel_id:
type: number
code:
type: string
minLength: 1
data_tag_enabled:
type: boolean
enabled:
type: boolean
id:
type: number
is_oauth_connected: {}
name:
type: string
minLength: 1
version:
type: number
x-examples:
example-1:
channel_id: 1
code: GA-1234567890
data_tag_enabled: false
enabled: false
id: 2
is_oauth_connected:
name: Visual Website Optimizer
version: 1
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsProvider'
'400':
description: Bad request. Authentication Required.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse400'
'404':
description: >-
The requested resource was not found. Please specify valid Web
Analytics Provider ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse404'
'409':
description: >-
Web Analytics Provider was in conflict with another Web Analytics
Provider. This can be caused by duplicated unique values (such as
ID).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse409'
'422':
description: >-
Web Analytics Provider data was not valid. This is the result of
missing required fields, or of invalid data. See the response for
more details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse422'
tags:
- Analytics
/settings/catalog:
parameters:
- $ref: '#/components/parameters/Accept'
get:
summary: BigCommerce Get Catalog Settings
operationId: getSettingsCatalog
description: |-
Returns catalog settings.
- Channel ID can be used as a query parameter for getting channel-specific setting. If omitted, you will interact with the global setting only.
- `null` indicates that a particular field has not been overridden on a channel level when channel level settings are requested and values are inherited from global level.
parameters:
- $ref: '#/components/parameters/ChannelIdParam'
responses:
'200':
description: >-
OK. `null` indicates that a particular field has not been overridden
on a channel level when channel level settings are requested
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/CatalogSettings'
meta:
$ref: '#/components/schemas/MetaOpen'
tags:
- Catalog
put:
summary: BigCommerce Update Catalog Settings
operationId: updateSettingsCatalog
description: |-
Updates catalog settings.
- Channel ID can be used as a query parameter for updating channel-specific setting. If omitted, you will interact with the global setting only.
- `null` should be supplied to delete overrides per given channel and to inherit values from global level. Partial updates are not supported and all settings should be supplied with `null` value in order to delete overrides per channel.
parameters:
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/ChannelIdParam'
requestBody:
description: >-
null set for a particular field removes override on a channel level
and means inheritance from a global level
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogSettings'
responses:
'200':
description: >-
OK. `null` indicates that a particular field has not been overridden
on a channel level when channel level settings are requested
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/CatalogSettings'
meta:
$ref: '#/components/schemas/MetaOpen'
tags:
- Catalog
/settings/email-statuses:
parameters:
- $ref: '#/components/parameters/Accept'
get:
operationId: getSettingsEmailStatuses
summary: BigCommerce Get Transactional Email Settings
description: >-
Get global transactional email settings or channel specific overrides by
`channel_id`.
parameters:
- $ref: '#/components/parameters/ChannelIdParam'
responses:
'200':
description: >-
OK, null indicates that a particular field has not been overridden
on a channel level when channel level settings are requested
content:
application/json:
examples:
Example:
value:
data:
abandoned_cart_email: true
account_details_changed_email: true
combined_order_status_email: true
createaccount_email: true
createguestaccount_email: true
giftcertificate_email: true
invoice_email: true
ordermessage_notification: true
product_review_email: false
return_confirmation_email: true
return_statuschange_email: true
meta: {}
schema:
type: object
properties:
data:
$ref: '#/components/schemas/EnabledTransactionalEmails'
meta:
$ref: '#/components/schemas/MetaOpen'
tags:
- Email Statuses
put:
operationId: updateSettingsEmailStatuses
summary: BigCommerce Update Transactional Email Settings
description: >-
Update global transactional email settings or create channel specific
overrides by `channel_id`.
parameters:
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/ChannelIdParam'
requestBody:
content:
application/json:
examples:
Example:
value:
abandoned_cart_email: true
account_details_changed_email: true
combined_order_status_email: true
createaccount_email: true
createguestaccount_email: true
giftcertificate_email: true
invoice_email: true
ordermessage_notification: true
product_review_email: false
return_confirmation_email: true
return_statuschange_email: true
schema:
$ref: '#/components/schemas/EnabledTransactionalEmails'
responses:
'200':
description: OK
content:
application/json:
examples:
Example:
value:
data:
abandoned_cart_email: true
account_details_changed_email: true
combined_order_status_email: true
createaccount_email: true
createguestaccount_email: true
giftcertificate_email: true
invoice_email: true
ordermessage_notification: true
product_review_email: false
return_confirmation_email: true
return_statuschange_email: true
meta: {}
schema:
type: object
properties:
data:
$ref: '#/components/schemas/EnabledTransactionalEmails'
meta:
$ref: '#/components/schemas/MetaOpen'
tags:
- Email Statuses
/settings/favicon/image:
parameters:
- $ref: '#/components/parameters/Accept'
post:
operationId: createSettingsFaviconImage
summary: BigCommerce Create Favicon Image
description: >-
Uploads an image file to use as the storefront favicon. Supported MIME
types include GIF, JPEG, and PNG.
- Channel ID can be used as a query parameter for updating channel-specific setting. If omitted, you will interact with the global setting only.
parameters:
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/ChannelIdParam'
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
FaviconFile:
type: string
format: binary
responses:
'204':
description: OK
tags:
- Favicon Image
/settings/inventory/notifications:
parameters:
- $ref: '#/components/parameters/Accept'
get:
summary: BigCommerce Get Inventory Notifications Settings
operationId: getSettingsInventoryNotifications
description: >-
Returns inventory notification settings.
* `channel_id` can be used as a query parameter to get inventory
notification settings per channel. If omitted, you will interact with
the global setting only.
parameters:
- $ref: '#/components/parameters/ChannelIdParam'
responses:
'200':
description: >-
OK. `null` indicates that a particular field has not been overridden
on a channel level when channel level settings are requested
content:
application/json:
examples: {}
schema:
type: object
properties:
data:
$ref: '#/components/schemas/InventoryNotificationsSettings'
meta:
$ref: '#/components/schemas/MetaOpen'
tags:
- Inventory Notifications
put:
summary: BigCommerce Update Inventory Notifications Settings
operationId: updateSettingsInventoryNotifications
description: >-
Updates inventory notification settings.
* `channel_id` can be used as a query parameter to get inventory
notification settings per channel. If omitted, you will interact with
the global setting only.
* Supplying `null` settings values per channel will delete overrides per
given channel and values will be inherited from global level.
* Partial updates are not supported within the given endpoint. In order
to delete overrides per channel, `null` should be supplied for all the
settings within the given endpoint.
parameters:
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/ChannelIdParam'
requestBody:
description: >-
null set for a particular field removes override on a channel level
and means inheritance from a global level
content:
application/json:
schema:
$ref: '#/components/schemas/InventoryNotificationsSettings'
responses:
'200':
description: OK
tags:
- Inventory Notifications
/settings/logo:
parameters:
- $ref: '#/components/parameters/Accept'
get:
operationId: getSettingsLogo
summary: BigCommerce Get Store Logo Settings
description: |-
Returns store logo settings.
- Channel ID can be used as a query parameter for getting channel-specific setting. If omitted, you will interact with the global setting only.
- `null` indicates that a particular field has not been overridden on a channel level when channel level settings are requested and values are inherited from global level.
parameters:
- $ref: '#/components/parameters/ChannelIdParam'
responses:
'200':
description: >-
OK, null indicates that a particular field has not been overridden
on a channel level when channel level settings are requested
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/LogoSettings'
meta:
$ref: '#/components/schemas/MetaOpen'
tags:
- Logo
put:
operationId: updateSettingsLogo
summary: BigCommerce Update Store Logo Settings
description: >-
Updates the logo type and logo text for a textual logo. To upload new
images, use the dedicated image POST endpoints.
- Channel ID can be used as a query parameter for updating channel-specific setting. If omitted, you will interact with the global setting only.
- `null` should be supplied to delete overrides per given channel and to inherit values from global level. Partial updates are not supported and all settings should be supplied with `null` value in order to delete overrides per channel.
parameters:
- $ref: '#/components/parameters/ChannelIdParam'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LogoSettingsUpdate'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/LogoSettings'
meta:
$ref: '#/components/schemas/MetaOpen'
tags:
- Logo
/settings/logo/image:
parameters:
- $ref: '#/components/parameters/Accept'
post:
operationId: createSettingsLogoImage
summary: BigCommerce Create Logo Image
description: >-
Uploads an image file to use as the storefront logo. Supported MIME
types include GIF, JPEG, and PNG.
- Channel ID can be used as a query parameter for updating channel-specific setting. If omitted, you will interact with the global setting only.
parameters:
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/ChannelIdParam'
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
LogoFile:
type: string
format: binary
responses:
'204':
description: OK
tags:
- Logo Image
/settings/search/filters:
get:
operationId: getSettingsEnabledSearchFilters
summary: BigCommerce Get Enabled Filters
description: >-
Returns a list of enabled default [Product
Filtering](https://support.bigcommerce.com/s/article/Product-Filtering-Settings)
filters. These filters will be used if a store does not have contextual
overrides.
responses:
'200':
description: ''
content:
application/json:
examples:
example-1:
value:
data:
- collapsed_by_default: false
display_name: Size
display_product_count: true
id: U123=
is_enabled: true
items_to_show: 10
sort_by: alpha
type: product
- collapsed_by_default: false
display_name: Brand
display_product_count: true
id: Y123=
is_enabled: true
items_to_show: 12
sort_by: alpha
type: brand
- collapsed_by_default: false
display_name: Color
display_product_count: true
id: Q123=
is_enabled: true
items_to_show: 10
sort_by: alpha
type: product
- collapsed_by_default: true
display_name: Ships for Free
display_product_count: false
id: Y456=
is_enabled: true
show_free_shipping_filter: true
show_in_stock_filter: true
show_is_featured_filter: true
type: other
meta: {}
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ConfiguredFilters'
meta:
$ref: '#/components/schemas/MetaOpen'
tags:
- Search Filters
put:
operationId: updateSettingsEnabledSearchFilters
summary: BigCommerce Update Enabled Filters
description: >-
Updates enabled default [Product
Filtering](https://support.bigcommerce.com/s/article/Product-Filtering-Settings)
filters.
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
examples:
example-1:
value:
- collapsed_by_default: false
display_name: Size
display_product_count: true
id: U123=
is_enabled: true
items_to_show: 12
sort_by: alpha
type: product
- collapsed_by_default: false
display_name: Brand
display_product_count: true
id: Y123=
is_enabled: true
items_to_show: 10
sort_by: alpha
type: brand
- collapsed_by_default: false
display_name: Color
display_product_count: true
id: Q123=
is_enabled: true
items_to_show: 10
sort_by: alpha
type: product
- collapsed_by_default: true
display_name: Ships for Free
display_product_count: true
id: Y456=
is_enabled: true
show_free_shipping_filter: true
show_in_stock_filter: true
show_is_featured_filter: true
type: other
schema:
$ref: '#/components/schemas/ConfiguredFilters'
responses:
'200':
description: ''
content:
application/json:
examples:
example-1:
value:
data:
- collapsed_by_default: false
display_name: Size
display_product_count: true
id: U123==
is_enabled: true
items_to_show: 12
sort_by: alpha
type: product
- collapsed_by_default: false
display_name: Brand
display_product_count: true
id: Y123=
is_enabled: true
items_to_show: 10
sort_by: alpha
type: brand
- collapsed_by_default: false
display_name: Color
display_product_count: true
id: Q123=
is_enabled: true
items_to_show: 10
sort_by: alpha
type: product
- collapsed_by_default: true
display_name: Ships for Free
display_product_count: true
id: Y456=
is_enabled: true
show_free_shipping_filter: true
show_in_stock_filter: true
show_is_featured_filter: true
type: other
meta: {}
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ConfiguredFilters'
meta:
$ref: '#/components/schemas/MetaOpen'
tags:
- Search Filters
/settings/search/filters/available:
parameters:
- $ref: '#/components/parameters/Accept'
get:
operationId: getSettingsAvailableFilters
summary: BigCommerce Get Available Filters
description: >-
Returns a list of filters available to power [Product
Filtering](https://support.bigcommerce.com/s/article/Product-Filtering-Settings).
parameters:
- $ref: '#/components/parameters/ContentType'
- name: channel_id
in: query
description: >-
Narrows the list of available filters based on channel ID. Only
products currently assigned to the given Channel will be considered.
schema:
type: integer
- name: category_id
in: query
description: >-
Narrows the list of available filters based on category ID. You can
display settings to show products from the provided category,
subcategories only, or both the category and its child categories.
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
examples:
example-1:
value:
data:
- id: Y2F0Zooo123=
name: Category
product_count: 7
type: category
- id: YnJh123=
name: Brand
product_count: 8
type: brand
- id: cmF0a123
name: Rating
product_count: 1
type: rating
- id: cHJp123=
name: Price
price_range_max: 300.99
price_range_min: 6.75
type: price
- id: U2l123==
name: Size
product_count: 3
type: product
- id: Q29s123=
name: Color
product_count: 2
type: product
- id: Ym9123==
name: Other
type: other
meta: {}
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AvailableFilter'
meta:
$ref: '#/components/schemas/MetaOpen'
tags:
- Search Filters
/settings/search/filters/contexts:
parameters:
- $ref: '#/components/parameters/Accept'
get:
operationId: getSettingsFiltersContexts
summary: BigCommerce Get Contextual Filters
description: >-
Returns a list of contextual filters enabled for a particular channel or
category.
**Usage Notes**
Contextual filters allow you to configure the enabled filters per
channel or category, so that shoppers can filter by the most relevant
criteria.
The order of the returned filters will match the sort order of the
filters on the storefront.
parameters:
- name: channel_id
in: query
description: Only return contextual overrides related to a particular Channel.
schema:
type: integer
- name: category_id
in: query
description: Only return contextual overrides related to a particular Category.
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ConfiguredFiltersOverride'
meta:
$ref: '#/components/schemas/MetaPaginationObject'
tags:
- Search Filters
put:
operationId: upsertSettingsFiltersContexts
summary: BigCommerce Upsert Contextual Filters
description: >-
Upserts contextual filters for a particular channel or category.
**Usage Notes**
Contextual filters allow you to configure the enabled filters per
channel or category, so that shoppers can filter by the most relevant
criteria.
You can change the order of the filters on the live site by changing the
order of the filters you send.
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ConfiguredFiltersOverride'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ConfiguredFiltersOverride'
meta:
$ref: '#/components/schemas/MetaOpen'
tags:
- Search Filters
/settings/store/locale:
get:
summary: BigCommerce Get Locale Settings
operationId: getSettingsLocale
description: Returns global locale settings.
parameters:
- $ref: '#/components/parameters/Accept'
responses:
'200':
description: ''
content:
application/json:
examples:
Example:
value:
data:
default_shopper_language: en
shopper_language_selection_method: default_shopper_language
store_country: United States
meta: {}
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Locale'
meta:
$ref: '#/components/schemas/MetaOpen'
tags:
- Store Locale
put:
summary: BigCommerce Update Locale Settings
operationId: updateSettingsLocale
description: Updates global locale settings.
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
examples:
Example:
value:
default_shopper_language: en
shopper_language_selection_method: default_shopper_language
store_country: United States
schema:
$ref: '#/components/schemas/Locale'
responses:
'200':
description: ''
content:
application/json:
examples:
Example:
value:
data:
default_shopper_
# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/settings-openapi-original.yml