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 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
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
Example: 1
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 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 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 values: name | description | date_created | date_modified - direction in query - string
Sort direction. Acceptable values are:
asc
,desc
.Allowed values: asc | desc - channel_id:in in query - array
Filters list of scripts by the associated channel_id.
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 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.
- uuid in path - string - required
The identifier for a specific script.
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 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
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
Example: 1
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 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.
- uuid in path - string - required
The identifier for a specific script.
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