Sites

Create and manage sites and routes for headless storefront (opens in a new tab) sales channels.

Note: For the "urls" object, we no longer modify the www prefix of the primary URL. The API returns URLs exactly as the customer enters them, similar to the "url" field.

If the customer saves a URL with www, the API returns it with www.
If the customer saves a URL without www, the API returns it without www.

Sites

Sites link headless storefronts to sales channels. To create a site, send a POST request to /stores/{{STORE_HASH}}/v3/sites.

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/sites
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "url": "http://store.example.com/",
  "channel_id": 5
}

Response

{
  "id": 1,
  "url": "http://store.example.com/",
  "channel_id": 5,
  "created_at": "2022-01-04T04:15:50.000Z",
  "updated_at": "2022-01-04T04:15:50.000Z"
}

To get a list of sites, send a GET request to /stores/{{STORE_HASH}}/v3/sites.

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

Site routes

Site routes tell BigCommerce how to link to pages on a headless storefront. To create a route for a site, send a POST request to /stores/{{STORE_HASH}}/v3/sites/{site_id}/routes.

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/sites/{site_id}/routes
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "type": "product",
  "matching": "12",
  "route": "/en/product?id=12"
}

Route types

The following route types are supported.

Type	Description
`product`	Route for product details pages
`brand`	Route to brand pages
`category`	Route to category pages
`blog`	Route to blog page
`home`	Route to storefront homepage
`cart`	Route to shopper’s cart
`checkout`	Route to checkout page
`search`	Route to store search page
`account`	Route to account profile page
`login`	Route to account login page
`returns`	Route for return policy page
`static`	Route to a static page
`create_account`	Route to create new shopper account page
`forgot_password`	Route to shopper forgot password page
`account_order_status`	Route for order status page
`account_new_return`	Route for product returns page
`recover_abandoned_cart`	Route for URL in emails for a shopper to recover their abandoned cart

Route variables

The following route variables are supported.

Variable	Description
`{id}`	The ID of the requested item
`{slug}`	The slug for the requested item (if available). Note: the `slug` value may contain `/` slash
`{lang}`	The language string that the client is using

Example:

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/sites/{site_id}/routes
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "type": "product",
  "matching": "*",
  "route": "/{lang}/{slug}?id={id}"
}

Additional Information

Related resources

Create a Site

POST https://api.bigcommerce.com/stores/{store_hash}/v3/sites

Request

Create a site that links a headless storefront to a sales channel.

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

urlstring
The Fully Qualified URL (including host and scheme) where this site is hosted. All URLs generated for this site will be appended to this.
Example: http://kittens.mybigcommerce.com/
channel_idinteger
The channel this site is attached to. Each site belongs to a single channel, and each channel can have either zero or one sites.

example

{

"url": "http://kittens.mybigcommerce.com/",

"channel_id": 0

}

Response

Body

object | application/json

dataobject
metaobject
Response metadata.

Example

{

"data": {

"id": 23,

"url": "https://example.com",

"channel_id": 234,

"created_at": "2018-01-04T04:15:50.000Z",

"updated_at": "2018-01-04T04:15:50.000Z",

"urls": [

{

"url": "https://example.com",

"type": "primary",

"created_at": "2020-11-03T19:26:12Z",

"updated_at": "2021-08-31T21:46:50Z"

{

"url": "https://store-29i23fcz6.mybigcommerce.com",

"type": "canonical",

"created_at": "2020-11-03T19:26:12Z",

"updated_at": "2020-11-03T19:26:12Z"

{

"url": "https://checkout.example.com",

"type": "checkout",

"created_at": "2020-11-03T19:26:12Z",

Get Sites

GET https://api.bigcommerce.com/stores/{store_hash}/v3/sites

Request

Get sites linked to a headless storefront sales channels.

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.
page in query - integer
Specifies the page number in a limited (paginated) list of items.
limit in query - integer
Controls the number of items per page in a limited (paginated) list of items.
channel_id:in in query - array
A comma-separated list that returns sites by channel ID.
Type: array[integer]
url_type:in in query - array
A comma-separated list that returns sites by their URL type, specified in the data.urls array.
Type: array[string]

example

curl --request GET \

--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/sites' \

--header 'Accept: application/json' \

--header 'Content-Type: application/json' \

--header 'X-Auth-Token: {{token}}'

Response

Body

object | application/json

dataarray[object]
metaobject

Get a Site

GET https://api.bigcommerce.com/stores/{store_hash}/v3/sites/{site_id}

Request

Get a site with site ID {site_id}.

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.
site_id in path - string
required

example

curl --request GET \

--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/sites/[site_id]' \

--header 'Accept: application/json' \

--header 'Content-Type: application/json' \

--header 'X-Auth-Token: {{token}}'

Response

Body

object | application/json

dataobject
metaobject
Response metadata.

Example

{

"data": {

"id": 23,

"url": "https://example.com",

"channel_id": 234,

"created_at": "2018-01-04T04:15:50.000Z",

"updated_at": "2018-01-04T04:15:50.000Z",

"urls": [

{

"url": "https://example.com",

"type": "primary",

"created_at": "2020-11-03T19:26:12Z",

"updated_at": "2021-08-31T21:46:50Z"

{

"url": "https://store-29i23fcz6.mybigcommerce.com",

"type": "canonical",

"created_at": "2020-11-03T19:26:12Z",

"updated_at": "2020-11-03T19:26:12Z"

{

"url": "https://checkout.example.com",

"type": "checkout",

"created_at": "2020-11-03T19:26:12Z",

Update a Site

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/sites/{site_id}

Request

Update a site with site ID {site_id}.

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.
site_id in path - string
required
Content-Type in header with default of application/json - string
required
The MIME type of the request body.

Body

object | application/json

urlstring
The Fully Qualified URL (including host and scheme) where this site is hosted. All URLs generated for this site will be appended to this.
Example: http://kittens.mybigcommerce.com/

example

{

"url": "http://kittens.mybigcommerce.com/"

}

Response

Body

object | application/json

dataobject
metaobject
Response metadata.

Example

{

"data": {

"id": 23,

"url": "https://example.com",

"channel_id": 234,

"created_at": "2018-01-04T04:15:50.000Z",

"updated_at": "2018-01-04T04:15:50.000Z",

"urls": [

{

"url": "https://example.com",

"type": "primary",

"created_at": "2020-11-03T19:26:12Z",

"updated_at": "2021-08-31T21:46:50Z"

{

"url": "https://store-29i23fcz6.mybigcommerce.com",

"type": "canonical",

"created_at": "2020-11-03T19:26:12Z",

"updated_at": "2020-11-03T19:26:12Z"

{

"url": "https://checkout.example.com",

"type": "checkout",

"created_at": "2020-11-03T19:26:12Z",

Delete a Site

DELETE https://api.bigcommerce.com/stores/{store_hash}/v3/sites/{site_id}

Request

Delete a site with site ID {site_id}. Remove the URL set for a given site ID.

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.
site_id in path - string
required

example

curl --request DELETE \

--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/sites/[site_id]' \

--header 'Accept: application/json' \

--header 'Content-Type: application/json' \

--header 'X-Auth-Token: {{token}}'

Response

No Content.

Body

object | application/json

dataobject
metaobject

example

{

"data": {},

"meta": {}

}

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?

Delete a Shipping Zone Create a Site

Sites

Sites

Site routes

Route types

Route variables

Additional Information

Related resources

Create a Site

Request

Authentication

Parameters

Body

urlstring

channel_idinteger

example

Response

Body

dataobject

metaobject

Example

Get Sites

Request

Authentication

Parameters

example

Response

Body

dataarray[object]

metaobject

Get a Site

Request

Authentication

Parameters

example

Response

Body

dataobject

metaobject

Example

Update a Site

Request

Authentication

Parameters

Body

urlstring

example

Response

Body

dataobject

metaobject

Example

Delete a Site

Request

Authentication

Parameters

example

Response

Body

dataobject

metaobject

example