Managing Store Configuration

Settings API reference documentation

BigCommerce's Settings APIs can manage many of the configuration settings that are exposed to merchants in their store control panel, such as the store's name and contact information, SEO settings, and search filters.

These Settings APIs can be used to simplify the setup of new storefronts and other new sales channels, as well as to automate ongoing configuration changes. They enable developers to build configuration management tools that may be more efficient than the store control panel for a particular use case.

They are also useful for app developers who want to build integrations that can understand, respect, and work with the potentially complex states of a store's configuration. For example, knowing the settings that relate to the display of pricing in a storefront or other sales channel can be useful for an application that also displays pricing, automates the application of promotions, or sends emails containing prices.

Unlike many of BigCommerce's APIs, Settings APIs usually don't involve large collections of objects that can be created, deleted, and paginated. Instead, these APIs deal with a limited, static set of configurable properties that affect various aspects of store operations. They can be configured both on the global level and as channel-specific contextual overrides that apply to only one sales channel.

Global settings and channel-specific settings

The majority of BigCommerce merchants sell their products exclusively through the storefront website that comes preconfigured with their plan. When these merchants configure their store settings, they're modifying the global default versions of their settings.

Once a merchant starts to take advantage of multi-storefront or other multi-channel functionality, they often want to configure settings differently for each sales channel.

Each new channel will use the store's global default values unless the merchant chooses to override them by defining channel-specific settings.

The Settings APIs use query parameters to distinguish which set of settings a request is accessing.

Consider the following request to the Get store profile settings endpoint:

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/settings/store/profile
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Because the request did not specify any query parameters, the API returned the global default configuration for this merchant. Responses that return global configuration data will contain values for all properties of the requested object.

The merchant's global configuration is used for all storefronts and other channels that have not specified different, channel-specific configuration settings.

To check whether channel-specific values for a setting are defined, send the channel_id as a query parameter in your requests to settings endpoints.

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/settings/store/profile?channel_id=122
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

The response's empty data object indicates that no channel-specific store profile settings are configured for the specified channel. It is safe to infer that this channel is using the global default store profile settings. When the global default store profile settings change, this channel's profile will reflect those changes. For example, if the global default value for the store name changed, the store name would change at each place it appears in this channel.

The following request-response pair shows an example of a channel that does have channel-specific store profile settings configured.

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/settings/store/profile?channel_id=123
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Because a custom store name exists for channel 123, the channel-specific store name overrides the global default. Shoppers who interact with this channel will see the custom store name at each place it appears in the channel. When the global default store_name in the merchant's store profile settings changes, this channel will not reflect that change. However, any other changes to the global default store profile will affect channel 123, because store_name is the only channel-specific value defined.

The following request-response pair shows an example of a channel with a complete set of channel-specific store profile settings configured.

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/settings/store/profile?channel_id=124
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Because channel-specific values exist for all store profile object properties, this channel is configured to override all the global default store profile configuration settings. Changes to the global defaults will not affect this channel.

Editing store configuration settings

You can modify global and channel-specific settings alike by sending PUT requests to the relevant endpoints.

The following example uses the Update store profile settings endpoint to modify a store's global default configuration:

PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/settings/store/profile
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "store_name": "The new global store name",
}

To update channel-specific settings, send a request to the same endpoint along with a value for the channel_id query parameter.

PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/settings/store/profile?channel_id=123
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "store_name": "A different Channel-Specific Name for Channel 123",
}

If you wish to restore global defaults on a channel with a channel-specific configuration, you can "un-override" the channel's settings by sending a PUT request. Use the following in the request:

• the channel_id query parameter
• null as a value for all fields. The endpoint does not support partial updates; you must remove overrides for all fields.

PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/settings/store/profile?channel_id=124
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
 
{
  "store_address": null,
  "store_email": null,
  "store_name": null,
  "store_phone": null
}

The cumulative effect of global and channel-specific settings

At every point of contact a shopper has with a storefront or other sales channel, channel-specific settings are displayed first. Global default settings will only appear to shoppers when channel-specific values for those properties are not defined. This goes for viewing the storefront or product feed, reading a transactional email, receiving a packing slip, and all other interactions with the channel.

The Settings APIs discussed in this article are primarily for use cases involved with the management or administration of store settings. If your application's proposed implementation of the Settings APIs is mostly concerned with presenting the correct shopper-facing details at their "touch point" with a storefront or other sales channel, consider using the GraphQL Storefront API to simplify your integration. Storefront API requests are run in the context of the shopper's active channel, so the relevant configuration is already correctly integrated with the data it returns. Stencil-powered storefront themes are also equipped with objects that represent the shopper-facing experience in context.