Docs
Management API
Sites

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.

TypeDescription
productRoute for product details pages
brandRoute to brand pages
categoryRoute to category pages
blogRoute to blog page
homeRoute to storefront homepage
cartRoute to shopper’s cart
checkoutRoute to checkout page
searchRoute to store search page
accountRoute to account profile page
loginRoute to account login page
returnsRoute for return policy page
staticRoute to a static page
create_accountRoute to create new shopper account page
forgot_passwordRoute to shopper forgot password page
account_order_statusRoute for order status page
account_new_returnRoute for product returns page
recover_abandoned_cartRoute for URL in emails for a shopper to recover their abandoned cart

Route variables

The following route variables are supported.

VariableDescription
{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 /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

  • url    string

    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_id    integer

    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

Response

Body

object | application/json

  • data    object

  • meta    object

    Response metadata.

Example

Get Sites

GET /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

Response

Body

object | application/json

  • data    array[object]

  • meta    object

Get a Site

GET /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

Response

Body

object | application/json

  • data    object

  • meta    object

    Response metadata.

Example

Update a Site

PUT /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

  • url    string

    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

Response

Body

object | application/json

  • data    object

  • meta    object

    Response metadata.

Example

Delete a Site

DELETE /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

Response

No Content.

Body

object | application/json

  • data    object

  • meta    object

example

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?
Delete a Shipping ZoneCreate a Site