Sites

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

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 - required

Parameters

store_hash in path - string
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
Meta data relating to pagination.

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",
    "ssl_status": "dedicated",
    "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",
        "updated_at": "2021-08-31T21:46:50Z"
      }
    ],
    "is_checkout_url_customized": true
  },
  "meta": {
    "pagination": {
      "offset": 0,
      "limit": 50,
      "total_items": 1
    }
  }
}

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 - required

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 - integer
Filters returned sites by channel ID.
url_type:in in query - string
Filters sites returned in the data.urls array by their URL type.

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: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

dataarray[object]
metaobject
Meta data relating to pagination.

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 - required

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: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

dataobject
metaobject
Meta data relating to pagination.

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",
    "ssl_status": "dedicated",
    "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",
        "updated_at": "2021-08-31T21:46:50Z"
      }
    ],
    "is_checkout_url_customized": true
  },
  "meta": {
    "pagination": {
      "offset": 0,
      "limit": 50,
      "total_items": 1
    }
  }
}

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 - required

Parameters

store_hash in path - string
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
Meta data relating to pagination.

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",
    "ssl_status": "dedicated",
    "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",
        "updated_at": "2021-08-31T21:46:50Z"
      }
    ],
    "is_checkout_url_customized": true
  },
  "meta": {
    "pagination": {
      "offset": 0,
      "limit": 50,
      "total_items": 1
    }
  }
}

Delete a Site

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

Request

Delete a site with site ID {site_id}.

Authentication

X-Auth-Token in header - required

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: xxxxxxxxxxxxxxxxx'

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