Thanks for being patient while we implement your feedback to improve the developer experience.

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 /content/scripts

Request

Creates a Script.

Required Fields

  • name

Read Only Fields

  • uuid

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

application/json

  • name    string
    required

    The user-friendly name.

    >= 1 characters<= 255 characters

  • description    string

    The user-friendly description.

  • html    string

    An HTML string containing exactly one script tag. Present when the script kind is script_tag.

    >= 0 characters<= 65536 characters

  • src    string

    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_uninstall    boolean

    It will enable automatic cleanup of the script when the single click app is uninstalled or OAuth token is revoked.

  • load_method    string

    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

  • location    string

    Where on the page to place the script. Values are head or footer.

    Allowed: head | footer

  • visibility    string

    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

  • kind    string

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

    The client id of the API user that created this script, or blank if created by other means.

  • consent_category    string

    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

  • enabled    boolean

    Whether the script is enabled or disabled on the storefront.

  • channel_id    integer

    Example: 1

    Script Source URL

    {
  "name": "Bootstrap",
  "description": "Build responsive websites",
  "src": "https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js",
  "auto_uninstall": true,
  "load_method": "default",
  "location": "footer",
  "visibility": "all_pages",
  "kind": "src",
  "consent_category": "essential"
}

    HTML Script Tag

    {
  "name": "Bootstrap",
  "description": "Build responsive websites",
  "html": "",
  "auto_uninstall": true,
  "load_method": "default",
  "location": "footer",
  "visibility": "all_pages",
  "kind": "script_tag",
  "consent_category": "essential"
}

    Response

    Body

    object | application/json

    For a list of all locations visit Scripts Visibility.

    • data

    • meta      object

      Response metadata.

    example

    {
  "data": {
    "name": "string",
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "date_created": "2019-08-24T14:15:22Z",
    "date_modified": "2019-08-24T14:15:22Z",
    "description": "string",
    "html": "string",
    "src": "https://code.jquery.com/jquery-3.2.1.min.js",
    "auto_uninstall": true,
    "load_method": "default",
    "location": "head",
    "visibility": "storefront",
    "kind": "src",
    "api_client_id": "string",
    "consent_category": "essential",
    "enabled": true,
    "channel_id": 1
  },
  "meta": {}
}

    Get All Scripts

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

    • direction in query - string

      Sort direction. Acceptable values are: asc, desc.

    • channel_id:in in query - array

      Filters list of scripts by the associated channel_id.

    example

    curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/content/scripts' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

    Response

    Body

    object | application/json

    • data      array[object]

    • meta      object

      Data about the response, including pagination and collection totals.

    example

    {
  "data": [
    {
      "name": "string",
      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
      "date_created": "2019-08-24T14:15:22Z",
      "date_modified": "2019-08-24T14:15:22Z",
      "description": "string",
      "html": "string",
      "src": "https://code.jquery.com/jquery-3.2.1.min.js",
      "auto_uninstall": true,
      "load_method": "default",
      "location": "head",
      "visibility": "storefront",
      "kind": "src",
      "api_client_id": "string",
      "consent_category": "essential",
      "enabled": true,
      "channel_id": 1
    }
  ],
  "meta": {
    "pagination": {
      "total": 36,
      "count": 36,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "previous": "string",
        "current": "?page=1&limit=50",
        "next": "string"
      }
    }
  }
}

    Get a Script

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

    curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/content/scripts/[uuid]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

    Response

    Success

    Body

    object | application/json

    For a list of all locations visit Scripts Visibility.

    • data

    • meta      object

      Response metadata.

    example

    {
  "data": {
    "name": "string",
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "date_created": "2019-08-24T14:15:22Z",
    "date_modified": "2019-08-24T14:15:22Z",
    "description": "string",
    "html": "string",
    "src": "https://code.jquery.com/jquery-3.2.1.min.js",
    "auto_uninstall": true,
    "load_method": "default",
    "location": "head",
    "visibility": "storefront",
    "kind": "src",
    "api_client_id": "string",
    "consent_category": "essential",
    "enabled": true,
    "channel_id": 1
  },
  "meta": {}
}

    Update a Script

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

    application/json

    • name      string

      The user-friendly name.

      >= 1 characters<= 255 characters

    • description      string

      The user-friendly description.

    • html      string

      An HTML string containing exactly one script tag. Present when the script kind is script_tag.

      >= 0 characters<= 65536 characters

    • src      string

      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_uninstall      boolean

      It will enable automatic cleanup of the script when the single click app is uninstalled or OAuth token is revoked.

    • load_method      string

      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

    • location      string

      Where on the page to place the script. Values are head or footer.

      Allowed: head | footer

    • visibility      string

      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

    • kind      string

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

      The client id of the API user that created this script, or blank if created by other means.

    • consent_category      string

      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

    • enabled      boolean

      Whether the script is enabled or disabled on the storefront.

    • channel_id      integer

      Example: 1

      example

      {
  "name": "string",
  "description": "string",
  "html": "string",
  "src": "https://code.jquery.com/jquery-3.2.1.min.js",
  "auto_uninstall": true,
  "load_method": "default",
  "location": "head",
  "visibility": "storefront",
  "kind": "src",
  "api_client_id": "string",
  "consent_category": "essential",
  "enabled": true,
  "channel_id": 1
}

      Response

      Body

      object | application/json

      For a list of all locations visit Scripts Visibility.

      • data

      • meta        object

        Response metadata.

      example

      {
  "data": {
    "name": "string",
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "date_created": "2019-08-24T14:15:22Z",
    "date_modified": "2019-08-24T14:15:22Z",
    "description": "string",
    "html": "string",
    "src": "https://code.jquery.com/jquery-3.2.1.min.js",
    "auto_uninstall": true,
    "load_method": "default",
    "location": "head",
    "visibility": "storefront",
    "kind": "src",
    "api_client_id": "string",
    "consent_category": "essential",
    "enabled": true,
    "channel_id": 1
  },
  "meta": {}
}

      Delete a Script

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

      curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/content/scripts/[uuid]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

      Response

      Body

      object | application/json

      No-content response for the BigCommerce API.

      • status        integer

        204 HTTP status code.

        Example: 204

      • title        string

        The error title describing the situation.

      • type        string

      • instance        string

      example

      {
  "status": 204,
  "title": "string",
  "type": "string",
  "instance": "string"
}