Scripts

Add client-side code to a BigCommerce storefront page or associate a script with a channel. To learn more about scripts, see the Scripts API article.

Create a Script

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

Request

Creates a Script.

Required Fields

name

Read Only Fields

uuid

Limits

50 scripts per channel.

Notes

If the kind is src:
- Specify the src property.
- Optionally, you can supply a load_method.
- Do not specify the html field.
If the kind is script_tag:
- Specify the html property.
- Do not specify the src field.
Each app can have 10 scripts installed.
Multiple scripts can be created per call.

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

Script properties common to post, put, and get requests.

namestring
required
The user-friendly name.
>= 1 characters<= 255 characters
descriptionstring
The user-friendly description.
htmlstring
An HTML string containing exactly one script tag. Present when the script kind is script_tag.
>= 0 characters<= 65536 characters
srcstring
The src attribute of the script to load. Only present if kind is src.
Example: https://code.jquery.com/jquery-3.2.1.min.js
auto_uninstallboolean
It will enable automatic cleanup of the script when the single click app is uninstalled or OAuth token is revoked.
load_methodstring
The load method to use for the script. Values are default, async, or defer. It determines how the script should be loaded into the page.
Allowed: default | async | defer
locationstring
Where on the page to place the script. Values are head or footer.
Allowed: head | footer
visibilitystring
Which set of pages the script should load on.
Please note that you need to have Checkout content scope to use all_pages and checkout.
- The current visibility options are storefront, checkout, all_pages and order_confirmation.
  storefront: All pages that are not checkout or order_confirmation.
  
  For a list of all locations visit Scripts Visibility.
Allowed: storefront | all_pages | checkout | order_confirmation
kindstring
What type of script this is.
src - For scripts that use the src URL. A script tag will be generated with its src attribute set to the value of the src property. When your app provides a path to the script, we can optimize and add the script automatically for you. The load_method can vary.
script_tag - For scripts that include a raw HTML script tag-enclosed block of JavaScript. The value of html is added directly to the page. The load_method must be default.
Allowed: src | script_tag
Example: src
api_client_idstring
The client id of the API user that created this script, or blank if created by other means.
consent_categorystring
Consent category for GDPR and CCPA compliance. Defaults to unknown when not specified. Scripts with an unknown consent category do not display on stores with customer cookie consent banners enabled.
Allowed: essential | functional | analytics | targeting
Example: essential
enabledboolean
Whether the script is enabled or disabled on the storefront.
channel_idinteger
Min: 1
Example: 1
integrity_hashesarray[string]
Array of Subresource integrity (SRI) hashes for external SRC scripts that lets browsers validate the contents of the script.
The hash is the integrity attribute on the script tag. You can add up to five hashes for a script and generate them using any SRI standard-supported algorithm, including SHA-256, SHA-384, and SHA-512. If you provide more than one hash, they will all be added to the integrity attribute in order, separated by whitespace.
Type: array[string]
Example: ["sha384-DgtwqxoPLKnJSER+TUmSPIpE6ZbVb2ZZwR241HHiqJipLiZQPN/JkKX5xxrEHUTt","sha384-UiwrqEuzfCtJKLI+dXmPNOpE6ZvBh2IIqT371rJiqJxyKjZ6PP/JmSD5hdsEUPOl"]

Script Source URL

HTML Script Tag

Response

Body

object | application/json

For a list of all locations visit Scripts Visibility.

dataobject
Script properties common to post, put, and get requests.
metaobject
Response metadata.

example

Get All Scripts

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

Request

Returns a list of Scripts. Optional parameters can be passed in.

This operation will only return scripts generated by the API key and password used to create the script originally.

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 products.
limit in query - integer
Controls the number of items per page in a limited (paginated) list of products.
sort in query - string
Field name to sort the scripts by. Note: Since id increments when new scripts are added, you can use that field to sort by script create date.
Allowed: name | description | date_created | date_modified
direction in query - string
Sort direction. Acceptable values are: asc, desc.
Allowed: asc | desc
channel_id:in in query - array
Filters list of scripts by the associated channel ID.
Type: array[integer]

example

Response

Body

object | application/json

dataarray[object]
metaobject
Data about the response, including pagination and collection totals.

example

Get a Script

GET https://api.bigcommerce.com/stores/{store_hash}/v3/content/scripts/{uuid}

Request

Returns a single Script.

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.
uuid in path - string
required
The identifier for a specific script.
Example: 03805148-a592-4803-9482-e91fe5c1be12

example

Response

Success

Body

object | application/json

For a list of all locations visit Scripts Visibility.

dataobject
Script properties common to post, put, and get requests.
metaobject
Response metadata.

example

Update a Script

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/content/scripts/{uuid}

Request

Updates a Script.

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.
uuid in path - string
required
The identifier for a specific script.
Example: 03805148-a592-4803-9482-e91fe5c1be12
Content-Type in header with default of application/json - string
required
The MIME type of the request body.

Body

object | application/json

Script properties common to post, put, and get requests.

namestring
The user-friendly name.
>= 1 characters<= 255 characters
descriptionstring
The user-friendly description.
htmlstring
An HTML string containing exactly one script tag. Present when the script kind is script_tag.
>= 0 characters<= 65536 characters
srcstring
The src attribute of the script to load. Only present if kind is src.
Example: https://code.jquery.com/jquery-3.2.1.min.js
auto_uninstallboolean
It will enable automatic cleanup of the script when the single click app is uninstalled or OAuth token is revoked.
load_methodstring
The load method to use for the script. Values are default, async, or defer. It determines how the script should be loaded into the page.
Allowed: default | async | defer
locationstring
Where on the page to place the script. Values are head or footer.
Allowed: head | footer
visibilitystring
Which set of pages the script should load on.
Please note that you need to have Checkout content scope to use all_pages and checkout.
- The current visibility options are storefront, checkout, all_pages and order_confirmation.
  storefront: All pages that are not checkout or order_confirmation.
  
  For a list of all locations visit Scripts Visibility.
Allowed: storefront | all_pages | checkout | order_confirmation
kindstring
What type of script this is.
src - For scripts that use the src URL. A script tag will be generated with its src attribute set to the value of the src property. When your app provides a path to the script, we can optimize and add the script automatically for you. The load_method can vary.
script_tag - For scripts that include a raw HTML script tag-enclosed block of JavaScript. The value of html is added directly to the page. The load_method must be default.
Allowed: src | script_tag
Example: src
api_client_idstring
The client id of the API user that created this script, or blank if created by other means.
consent_categorystring
Consent category for GDPR and CCPA compliance. Defaults to unknown when not specified. Scripts with an unknown consent category do not display on stores with customer cookie consent banners enabled.
Allowed: essential | functional | analytics | targeting
Example: essential
enabledboolean
Whether the script is enabled or disabled on the storefront.
channel_idinteger
Min: 1
Example: 1
integrity_hashesarray[string]
Array of Subresource integrity (SRI) hashes for external SRC scripts that lets browsers validate the contents of the script.
The hash is the integrity attribute on the script tag. You can add up to five hashes for a script and generate them using any SRI standard-supported algorithm, including SHA-256, SHA-384, and SHA-512. If you provide more than one hash, they will all be added to the integrity attribute in order, separated by whitespace.
Type: array[string]
Example: ["sha384-DgtwqxoPLKnJSER+TUmSPIpE6ZbVb2ZZwR241HHiqJipLiZQPN/JkKX5xxrEHUTt","sha384-UiwrqEuzfCtJKLI+dXmPNOpE6ZvBh2IIqT371rJiqJxyKjZ6PP/JmSD5hdsEUPOl"]

example

Response

Body

object | application/json

For a list of all locations visit Scripts Visibility.

dataobject
Script properties common to post, put, and get requests.
metaobject
Response metadata.

example

Delete a Script

DELETE https://api.bigcommerce.com/stores/{store_hash}/v3/content/scripts/{uuid}

Request

Deletes a Script.

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.
uuid in path - string
required
The identifier for a specific script.
Example: 03805148-a592-4803-9482-e91fe5c1be12

example

Response

Body

object | application/json

No-content response for the BigCommerce API.

statusinteger
204 HTTP status code.
Example: 204
titlestring
The error title describing the situation.
typestring
instancestring

example

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?

Download Redirect Export Create a Script

Scripts

Create a Script

Request

Authentication

Parameters

Body

namestringrequired

descriptionstring

htmlstring

srcstring

auto_uninstallboolean

load_methodstring

locationstring

visibilitystring

kindstring

api_client_idstring

consent_categorystring

enabledboolean

channel_idinteger

integrity_hashesarray[string]

Script Source URL

HTML Script Tag

Response

Body

dataobject

metaobject

example

Get All Scripts

Request

Authentication

Parameters

example

Response

Body

dataarray[object]

metaobject

example

Get a Script

Request

Authentication

Parameters

example

Response

Body

dataobject

metaobject

example

Update a Script

Request

Authentication

Parameters

Body

namestring

descriptionstring

htmlstring

srcstring

auto_uninstallboolean

load_methodstring

locationstring

visibilitystring

kindstring

api_client_idstring

consent_categorystring

enabledboolean

channel_idinteger

integrity_hashesarray[string]

example

Response

Body

dataobject

metaobject

example

Delete a Script

Request

Authentication

Parameters

example

Response

Body

statusinteger

namestring
required