BigCommerce
Management API
Scripts

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

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

    HTML Script Tag

    Response

    Body

    object | application/json

    For a list of all locations visit Scripts Visibility.

    • data

    • meta
      object

      Response metadata.

    example

    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.

      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

    object | application/json
    • data
      array[object]

    • meta
      object

      Data about the response, including pagination and collection totals.

    example

    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

    Response

    Success

    Body

    object | application/json

    For a list of all locations visit Scripts Visibility.

    • data

    • meta
      object

      Response metadata.

    example

    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

      Response

      Body

      object | application/json

      For a list of all locations visit Scripts Visibility.

      • data

      • meta
        object

        Response metadata.

      example

      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

      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

      Did you find what you were looking for?