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 /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
issrc
:- Specify the
src
property. - Optionally, you can supply a
load_method
. - Do not specify the
html
field.
- Specify the
- If the
kind
isscript_tag
:- Specify the
html
property. - Do not specify the
src
field.
- Specify the
- Each app can have 10 scripts installed.
- Multiple scripts can be created per call.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- Content-Type in header with default of application/json - stringrequired
The MIME type of the request body.
Body
namestring
required>= 1 characters<= 255 charactersThe user-friendly name.
descriptionstring
The user-friendly description.
htmlstring
>= 0 characters<= 65536 charactersAn HTML string containing exactly one
script
tag. Present when the scriptkind
isscript_tag
.srcstring
The
src
attribute of the script to load. Only present ifkind
issrc
.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
, ordefer
. 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
orfooter
.Allowed: head | footer
visibilitystring
Which set of pages the script should load on.
Please note that you need to have
Checkout content
scope to useall_pages
andcheckout
.-
The current visibility options are
storefront
,checkout
,all_pages
andorder_confirmation
.storefront
: All pages that are notcheckout
ororder_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. Ascript
tag will be generated with itssrc
attribute set to the value of thesrc
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 HTMLscript
tag-enclosed block of JavaScript. The value ofhtml
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 anunknown
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: 1Example: 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 thescript
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 theintegrity
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
For a list of all locations visit Scripts Visibility.
data
metaobject
Response metadata.
example
Get All Scripts
GET /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 headerrequired
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequired
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
dataarray[object]
metaobject
Data about the response, including pagination and collection totals.
example
Get a Script
GET /stores/{store_hash}/v3/content/scripts/{uuid}
Request
Returns a single Script.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequired
The MIME type of the response body.
- uuid in path - stringrequired
The identifier for a specific script.
Example: 03805148-a592-4803-9482-e91fe5c1be12
example
Response
Success
Body
For a list of all locations visit Scripts Visibility.
data
metaobject
Response metadata.
example
Update a Script
PUT /stores/{store_hash}/v3/content/scripts/{uuid}
Request
Updates a Script.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- Content-Type in header with default of application/json - stringrequired
The MIME type of the request body.
Body
namestring
>= 1 characters<= 255 charactersThe user-friendly name.
descriptionstring
The user-friendly description.
htmlstring
>= 0 characters<= 65536 charactersAn HTML string containing exactly one
script
tag. Present when the scriptkind
isscript_tag
.srcstring
The
src
attribute of the script to load. Only present ifkind
issrc
.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
, ordefer
. 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
orfooter
.Allowed: head | footer
visibilitystring
Which set of pages the script should load on.
Please note that you need to have
Checkout content
scope to useall_pages
andcheckout
.-
The current visibility options are
storefront
,checkout
,all_pages
andorder_confirmation
.storefront
: All pages that are notcheckout
ororder_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. Ascript
tag will be generated with itssrc
attribute set to the value of thesrc
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 HTMLscript
tag-enclosed block of JavaScript. The value ofhtml
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 anunknown
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: 1Example: 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 thescript
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 theintegrity
attribute in order, separated by whitespace.Type: array[string]Example: ["sha384-DgtwqxoPLKnJSER+TUmSPIpE6ZbVb2ZZwR241HHiqJipLiZQPN/JkKX5xxrEHUTt","sha384-UiwrqEuzfCtJKLI+dXmPNOpE6ZvBh2IIqT371rJiqJxyKjZ6PP/JmSD5hdsEUPOl"]
example
Response
Body
For a list of all locations visit Scripts Visibility.
data
metaobject
Response metadata.
example
Delete a Script
DELETE /stores/{store_hash}/v3/content/scripts/{uuid}
Request
Deletes a Script.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequired
The MIME type of the response body.
- uuid in path - stringrequired
The identifier for a specific script.
Example: 03805148-a592-4803-9482-e91fe5c1be12
example
Response
Body
No-content response for the BigCommerce API.
statusinteger
204 HTTP status code.
Example: 204
titlestring
The error title describing the situation.
typestring
instancestring