BigCommerce Sites is a website development company that specializes in building high-quality, customized e-commerce websites for online businesses. With a team of experienced web designers and developers, BigCommerce Sites creates visually appealing and easy-to-navigate websites that are optimized for driving sales and increasing revenue.
openapi: 3.0.3
info:
title: BigCommerce Sites
version: ''
description: >-
Create and manage [sites](#sites) and [routes](#routes) for [headless
storefront](https://support.bigcommerce.com/s/article/The-Headless-Approach#what-mean)
sales [channels](/docs/rest-management/channels).
## [Sites](/docs/rest-management/sites)
Sites link [headless storefronts](/docs/storefront/headless) to sales
[channels](/docs/rest-management/channels). To [create a
site](/docs/rest-management/sites#create-a-site), send a `POST` request to
`/stores/{{STORE_HASH}}/v3/sites`.
```http
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**
```json
{
"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](/docs/rest-management/sites#get-sites), send a
`GET` request to `/stores/{{STORE_HASH}}/v3/sites`.
```http
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/sites
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
```
## Site routes
[Site routes](/docs/rest-management/sites/site-routes) tell BigCommerce how
to link to pages on a [headless storefront](/docs/storefront/headless). To
[create a
route](/docs/rest-management/sites/site-routes#create-a-site-route) for a
[site](#sites), send a `POST` request to
`/stores/{{STORE_HASH}}/v3/sites/{site_id}/routes`.
```http
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:**
```http
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
* [Channels and Listings Reference](/docs/rest-management/channels)
* [Channels Overview](/docs/integrations/channels)
* [Building Headless Storefronts Guide](/docs/storefront/headless)
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: [email protected]
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: Site Certificate
- name: Site Routes
- name: Sites
description: >-
Enables creation and management of external sites (domains) where shoppers
shop. Allows for the correct shopping experience to be delivered and
maintained (i.e. redirect URLs, email links) when a shopper goes through
the purchasing process.
paths:
/sites:
parameters:
- $ref: '#/components/parameters/Accept'
post:
summary: BigCommerce Create a Site
operationId: createSite
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/post_Site'
required: true
x-examples:
application/json:
url: http://store.example.com/
channel_id: 2
responses:
'201':
$ref: '#/components/responses/response_Site'
'400':
$ref: '#/components/responses/400_BadRequest'
'403':
$ref: '#/components/responses/403_Unauthorized'
'404':
$ref: '#/components/responses/404_NotFound'
'502':
description: ''
'504':
$ref: '#/components/responses/504_GatewayTimeout'
tags:
- Sites
description: >-
Create a site that links a [headless
storefront](/docs/storefront/headless) to a sales
[channel](/docs/rest-management/channels).
get:
responses:
'200':
$ref: '#/components/responses/site_RespCollection'
summary: BigCommerce Get Sites
description: >-
Get sites linked to a [headless storefront](/docs/storefront/headless)
sales channels.
operationId: getSites
tags:
- Sites
parameters:
- in: query
name: page
description: Specifies the page number in a limited (paginated) list of items.
schema:
type: integer
- in: query
name: limit
description: >-
Controls the number of items per page in a limited (paginated) list
of items.
schema:
type: integer
- schema:
type: integer
example: 1
in: query
name: channel_id:in
description: Filters returned sites by channel ID.
- schema:
type: string
in: query
name: url_type:in
description: Filters sites returned in the `data.urls` array by their URL type.
/sites/{site_id}:
get:
summary: BigCommerce Get a Site
operationId: getSite
responses:
'200':
$ref: '#/components/responses/response_Site'
tags:
- Sites
description: Get a site with site ID `{site_id}`.
put:
summary: BigCommerce Update a Site
operationId: updateSite
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/put_Site'
required: true
x-examples:
application/json:
url: https://remote-site.com/
responses:
'200':
$ref: '#/components/responses/response_Site'
tags:
- Sites
description: Update a site with site ID `{site_id}`.
delete:
summary: BigCommerce Delete a Site
operationId: deleteSite
responses:
'204':
description: ''
tags:
- Sites
description: Delete a site with site ID `{site_id}`.
parameters:
- $ref: '#/components/parameters/Accept'
- name: site_id
in: path
required: true
schema:
type: string
/sites/{site_id}/routes:
parameters:
- $ref: '#/components/parameters/Accept'
- name: site_id
in: path
required: true
schema:
type: integer
get:
summary: BigCommerce Get a Site’s Routes
operationId: getSiteRoutes
parameters:
- name: type
in: query
description: Filter routes by a specified resource type.
schema:
type: string
- in: query
name: page
description: Specifies the page number in a limited (paginated) list of items.
schema:
type: integer
- in: query
name: limit
description: >-
Controls the number of items per page in a limited (paginated) list
of items.
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/siteRoute_Full'
meta:
$ref: '#/components/schemas/_metaCollection'
examples:
response:
value:
data:
- id: 1
type: product
matching: '5'
route: /products?id={id}
- id: 2
type: category
matching: '44'
route: /category/{slug}
meta:
pagination:
total: 1
count: 1
per_page: 50
current_page: 1
total_pages: 1
tags:
- Site Routes
description: Get a site’s routes.
post:
summary: BigCommerce Create a Site Route
operationId: createSiteRoute
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/siteRoute_Base'
required: true
x-examples:
application/json:
type: returns
matching: '5'
route: /my-amazing-product
responses:
'201':
$ref: '#/components/responses/siteRoute_Resp'
'422':
$ref: '#/components/responses/ErrorResponse'
'502':
$ref: '#/components/responses/502_GatewayError'
tags:
- Site Routes
description: >-
Create routes that tell BigCommerce how to link to pages on a [headless
storefront](/docs/storefront/headless).
## Usage Notes
* For a list of supported route types, see [Route
types](/docs/rest-management/sites#route-types).
put:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/siteRoute_Full'
meta:
$ref: '#/components/schemas/_metaCollection'
examples:
response:
value:
data:
- id: 123
type: brand
matching: '5'
route: /my-amazing-product
- id: 345
type: blog
matching: '5'
route: /my-amazing-product
- id: 234
type: returns
matching: '5'
route: /my-amazing-product
meta:
pagination:
total: 80
count: 50
per_page: 50
current_page: 50
total_pages: 2
links:
current: '?page=1&limit=50'
next: '?page=2&limit=50'
'422':
$ref: '#/components/responses/BulkErrorResponse'
description: |-
Upsert routes for site with ID `{site_id}`.
## Usage Notes
* `id` is required when updating an existing route.
summary: BigCommerce Update a Site’s Routes
operationId: updateSiteRoutes
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/siteRoute_Full'
x-examples:
application/json:
- id: 1
type: product
matching: '*'
route: /products/{id}
- id: 2
type: product
matching: '10'
route: /products?id={id}
tags:
- Site Routes
/sites/{site_id}/routes/{route_id}:
get:
summary: BigCommerce Get a Site Route
operationId: getSiteRoute
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/siteRoute_Full'
meta:
$ref: '#/components/schemas/MetaOpen'
examples:
response:
value:
data:
id: 60474753
type: checkout
matching: '5'
route: /my-amazing-product
meta: {}
tags:
- Site Routes
description: Get a site’s route.
put:
summary: BigCommerce Update a Site Route
operationId: updateSiteRoute
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/siteRoutes_Route_Base'
required: true
x-examples:
application/json:
type: product
matching: '*'
route: /products/{id}
responses:
'201':
$ref: '#/components/responses/siteRoute_Resp'
tags:
- Site Routes
description: |
Update a site’s route.
delete:
summary: BigCommerce Delete a Site Route
operationId: deleteSiteRoute
responses:
'204':
description: ''
tags:
- Site Routes
description: Delete a site’s route.
parameters:
- $ref: '#/components/parameters/Accept'
- name: site_id
in: path
required: true
schema:
type: string
- name: route_id
in: path
required: true
schema:
type: string
/sites/{site_id}/certificate:
parameters:
- $ref: '#/components/parameters/Accept'
- in: path
name: site_id
schema:
type: integer
required: true
get:
summary: BigCommerce Get a Site’s SSL/TLS Certificate Information
description: Obtain information about a site’s SSL/TLS certificate.
tags:
- Site Certificate
operationId: getSiteCertificate
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CertificateResponse'
examples: {}
put:
summary: BigCommerce Upsert a Site’s SSL/TLS Certificate Information
operationId: upsertSiteCertificate
parameters:
- $ref: '#/components/parameters/ContentType'
tags:
- Site Certificate
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InstallCertificateData'
description: ''
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyResponse'
Example:
examples:
response:
value: |-
{
"data": {},
"meta": {}
}
description: >-
- If a value for `url` is not supplied, the saved certificate is
associated with the specified site’s `primary` URL.
- Use caution. Because this endpoint upserts, supplying an SSL
certificate for a domain that already has a certificate connected
overwrites the domain’s extant certificate.'
/sites/certificates:
parameters:
- $ref: '#/components/parameters/Accept'
get:
summary: BigCommerce Get Site Certificates
tags:
- Site Certificate
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetCertificatesResponse'
operationId: getSitesCertificates
description: Return all SSL certificates connected to domains within a store.
parameters:
- schema:
type: string
in: query
name: urls:in
description: Query certificates by one or more URLs
components:
schemas:
_metaCollection:
title: metaCollection
description: Meta data relating to pagination.
type: object
properties:
pagination:
type: object
properties:
total:
type: integer
description: Total number of items returned.
example: 3
count:
type: integer
description: Number of items returned on per page.
example: 1
per_page:
type: integer
description: Number of items to be displayed per page.
example: 1
current_page:
type: integer
description: Current page number.
example: 2
total_page:
type: integer
description: Total number of pages.
example: 3
links:
type: object
properties:
previous:
type: string
description: >-
Query string appended to the resource to return to the
previous page.
example: '?limit=1&page=1'
next:
type: string
description: >-
Query string appended to the resource to proceed to the next
page.
example: '?limit=1&page=3'
current:
type: string
description: >-
Query string appended to the resource to show the current
page.
example: '?limit=1&page=2'
x-internal: false
siteRoute_Full:
title: siteRoute_Full
description: Route object used in responses.
allOf:
- type: object
properties:
id:
type: integer
description: >-
Unique ID for this route. Required when updating an existing
route.
- $ref: '#/components/schemas/siteRoute_Base'
x-internal: false
put_Site:
type: object
properties:
url:
type: string
description: >-
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/
title: put_Site
x-internal: false
_site:
type: object
description: ''
title: ''
properties:
id:
type: integer
url:
type: string
description: >-
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:
type: integer
description: >-
The channel to which this site is attached. Each site belongs to a
single channel, and each channel can have either zero or more sites.
created_at:
type: string
description: >-
The date-time that this site was created, formatted as an
[RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.
example: '2022-01-04T04:15:50.000Z'
updated_at:
type: string
description: >-
The date-time that this site was last updated, formatted as an
[RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.
example: '2022-01-04T04:15:50.000Z'
ssl_status:
type: string
enum:
- dedicated
- shared
description: >-
Indicates whether a site is using a private/dedicated SSL or a
shared SSL.
urls:
type: array
description: >-
All URLs that belong to the site, including `primary`, `canonical`,
and `checkout` URLs.
items:
$ref: '#/components/schemas/Url'
is_checkout_url_customized:
type: boolean
description: >-
Indicates whether the channel uses a custom checkout domain. When
`false`, the checkout domain falls back to the default channel’s
primary URL.
_metaEmpty:
type: object
properties: {}
description: Empty meta object; may be used later.
title: _metaEmpty
x-internal: false
_pagination:
type: object
description: |
Data about the response, including pagination and collection totals.
properties:
total:
type: integer
description: |
Total number of items in the result set.
count:
type: integer
description: |
Total number of items in the collection response.
per_page:
type: integer
description: >
The amount of items returned in the collection per page, controlled
by the limit parameter.
current_page:
type: integer
description: |
The page you are currently on within the collection.
total_pages:
type: integer
description: |
The total number of pages in the collection.
links:
type: object
description: >
Pagination links for the previous and next parts of the whole
collection.
properties:
previous:
type: string
description: |
Link to the previous page returned in the response.
current:
type: string
description: |
Link to the current page returned in the response.
next:
type: string
description: |
Link to the next page returned in the response.
title: _pagination
x-internal: false
_errors:
type: object
description: >-
The keys and values in an errors object will vary depending on the error
received.
title: _errors
x-internal: false
EmptyResponse:
type: object
properties:
data:
type: object
properties: {}
meta:
type: object
properties: {}
error_Full:
type: object
title: error_Full
properties:
status:
description: |
The HTTP status code.
type: integer
title:
description: |
The error title describing the particular error.
type: string
type:
type: string
x-internal: false
errorDetailed_Full:
type: object
properties:
errors:
type: object
properties: {}
additionalProperties: true
title: DetailedErrors
title: errorDetailed_Full
x-internal: false
post_Site:
type: object
properties:
url:
type: string
description: >-
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:
type: integer
description: >-
The channel this site is attached to. Each site belongs to a single
channel, and each channel can have either zero or one sites.
title: post_Site
x-internal: false
siteRoute_Base:
type: object
title: siteRoute_Base
properties:
type:
type: string
description: >-
The type of resource being routed to; [supported
types](/docs/rest-management/sites#route-types).
enum:
- product
- brand
- category
- page
- blog
- home
- cart
- checkout
- search
- account
- login
- returns
- static
matching:
type: string
description: >-
Depending on the resource type, this can be an ID (matching a
specific item), or a "*" wildcard (matching all items of that type).
For example, a route with a type: "product" and matching: "5" will
be used for the product with the ID of 5.
example: '5'
route:
type: string
description: >-
The route template that will be used to generate the URL for the
requested resource.
Supports several tokens:
- `{id}` The **ID** of the requested item.
- `{slug}` The **slug** for the requested item (if available). Note:
the `slug` value may contain `/` slash.
- `{language}` The **language** string that the client is using.
example: /my-amazing-product
x-internal: false
siteRoutes_Route_Base:
title: siteRoutes_Route_Base
type: object
properties:
type:
type: string
description: >-
The type of resource being routed to; [supported
types](/docs/rest-management/sites#route-types).
enum:
- product
- brand
- category
- page
- blog
- home
- cart
- checkout
- search
- account
- login
- returns
- static
matching:
type: string
example: '5'
description: >-
Depending on the resource type, this can be an ID (matching a
specific item), or a "*" wildcard (matching all items of that type).
For example, a route with a type: "product" and matching: "5" will
be used for the product with the ID of 5.
route:
type: string
example: /my-amazing-product
description: >-
The route template that will be used to generate the URL for the
requested resource.
Supports several tokens:
- `{id}` The **ID** of the requested item.
- `{slug}` The **slug** for the requested item (if available). Note:
the `slug` value may contain `/` slash.
- `{language}` The **language** string that the client is using.
required:
- type
- matching
- route
x-internal: false
IndexMeta:
type: object
description: BC Meta payload for collection-type responses.
properties:
pagination:
type: object
properties:
total:
type: integer
example: 1
count:
type: integer
example: 1
per_page:
type: integer
example: 50
current_page:
type: integer
example: 1
total_pages:
type: integer
example: 1
links:
type: object
properties:
previous:
type: string
example: '?page=1&limit=50'
current:
type: string
example: '?page=1&limit=50'
next:
type: string
example: '?page=1&limit=50'
x-tags:
- Models
Url:
type: object
properties:
url:
type: string
description: URL of site.
type:
type: string
description: Specifies the URL type.
enum:
- primary
- canonical
- checkout
created_at:
type: string
description: >-
The date-time that this URL was created, formatted as an
[RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.
example: '2018-01-04T04:15:50.000Z'
format: date-time
updated_at:
type: string
description: >-
The date-time that this URL was last updated, formatted as an
[RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.
example: '2018-01-04T04:15:50.000Z'
format: date-time
SiteCreate:
type: object
properties:
url:
type: string
description: >-
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:
type: integer
description: >-
The channel this site is attached to. Each site belongs to a single
channel, and each channel can have either zero or one sites.
certificate:
$ref: '#/components/schemas/CertificateWrite'
x-tags:
- Models
CertificateWrite:
title: CertificateWrite
type: object
description: ''
properties:
certificate:
type: string
description: The primary certificate, as a string.
private_key:
type: string
description: >-
The private key, as a string. Is a "write-only" field, will never be
returned after write.
intermediate_certificates:
type: string
description: The intermediate certificate(s), as a string.
x-tags:
- Models
CertificateResponse:
title: CertificateResponse
type: object
description: ''
properties:
data:
type: object
properties:
status:
type: string
enum:
- shared
- dedicated
installed_certificate:
$ref: '#/components/schemas/InstalledCertificateDetail'
meta:
$ref: '#/components/schemas/MetaOpen'
x-tags:
- Models
InstallCertificateData:
type: object
properties:
url:
type: string
description: URL for the site.
example: kittens.mybigcommerce.com
certificate:
$ref: '#/components/schemas/CertificateWrite'
InstalledCertificateDetail:
title: CertificateInfo
description: >-
Details about the installed certificate, including the raw certificate
data, without the private key.
type: object
nullable: true
properties:
common_name:
type: string
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/sites-openapi-original.yml