BigCommerce
Theme & Content APIs
Banners

Marketing

Get All Banners

GET /banners

Request

Returns a list of Banners. Default sorting is by banner id, from lowest to highest.

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.

  • min_id in query - integer

    Optional filter param /api/v2/banners?min_id={value}

  • max_id in query - integer

    Optional filter param /api/v2/banners?max_id={value}

  • page in query - number

    Optional filter param /api/v2/banners?page={number}

  • limit in query - number

    Optional filter param /api/v2/banners?limit={count}

example

Response

Body

array | application/json

    example

    Create a Banner

    POST /banners

    Request

    Creates a Banner.

    Required Fields

    • name
    • content
    • page
    • location
    • date_type

    Read Only Fields

    • date_created
    • id

    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

    object | application/json
    • name
      string
      required

      Name of the banner.

      Example: Sale Banner

    • content
      string
      required

      Contains the banner content. Returned as a string and includes HTML formatting.

      Example: <p> Sale! Tuesday at 9am! </p>

    • page
      string
      required

      Page the Banner is located on.

      Allowed: home_page | category_page | brand_page | search_page

    • location
      string
      required

      Location on the page.

      Allowed: top | bottom

      Example: top

    • date_type
      string
      required

      This specifies whether the banner should be visible during a specific date range.

      Allowed: always | custom

    • date_from
      string

      If the datetype is set as 'custom’, this field specifies the date when the banner should become visible on the storefront.

      Example: 0

    • date_to
      string

      If the datetype is set as 'custom’, this field specifies the date when the banner should stop being visible on the storefront.

      Example: 0

    • visible
      string

      Integer value denoting whether or not the banner is visible on the storefront: 1 = visible; 0 = not visible

      Example: 1

    • item_id
      string

      If the banner is on a specific category or brand page, then the item_id will correspond the category or brand ID.

      Example: 35

    example

    Response

    Body

    application/json
    • id
      integer

      Id of the banner. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request.

      Example: 1

    • date_created
      string

      Date the banner is created.

    • name
      string
      required

      Name of the banner.

      Example: Sale Banner

    • content
      string
      required

      Contains the banner content. Returned as a string and includes HTML formatting.

      Example: <p> Sale! Tuesday at 9am! </p>

    • page
      string
      required

      Page the Banner is located on.

      Allowed: home_page | category_page | brand_page | search_page

    • location
      string
      required

      Location on the page.

      Allowed: top | bottom

      Example: top

    • date_type
      string
      required

      This specifies whether the banner should be visible during a specific date range.

      Allowed: always | custom

    • date_from
      string

      If the datetype is set as 'custom’, this field specifies the date when the banner should become visible on the storefront.

      Example: 0

    • date_to
      string

      If the datetype is set as 'custom’, this field specifies the date when the banner should stop being visible on the storefront.

      Example: 0

    • visible
      string

      Integer value denoting whether or not the banner is visible on the storefront: 1 = visible; 0 = not visible

      Example: 1

    • item_id
      string

      If the banner is on a specific category or brand page, then the item_id will correspond the category or brand ID.

      Example: 35

      example

      Delete All Banners

      DELETE /banners

      Request

      By default, it deletes all Banners.

      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.

      example

      Response

      Get a Banner

      GET /banners/{id}

      Request

      Returns a single Banner

      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.

      • id in path - integer - required

        ID of the banner.

      example

      Response

      Body

      application/json
      • id
        integer

        Id of the banner. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request.

        Example: 1

      • date_created
        string

        Date the banner is created.

      • name
        string
        required

        Name of the banner.

        Example: Sale Banner

      • content
        string
        required

        Contains the banner content. Returned as a string and includes HTML formatting.

        Example: <p> Sale! Tuesday at 9am! </p>

      • page
        string
        required

        Page the Banner is located on.

        Allowed: home_page | category_page | brand_page | search_page

      • location
        string
        required

        Location on the page.

        Allowed: top | bottom

        Example: top

      • date_type
        string
        required

        This specifies whether the banner should be visible during a specific date range.

        Allowed: always | custom

      • date_from
        string

        If the datetype is set as 'custom’, this field specifies the date when the banner should become visible on the storefront.

        Example: 0

      • date_to
        string

        If the datetype is set as 'custom’, this field specifies the date when the banner should stop being visible on the storefront.

        Example: 0

      • visible
        string

        Integer value denoting whether or not the banner is visible on the storefront: 1 = visible; 0 = not visible

        Example: 1

      • item_id
        string

        If the banner is on a specific category or brand page, then the item_id will correspond the category or brand ID.

        Example: 35

        example

        Update a Banner

        PUT /banners/{id}

        Request

        Updates a Banner.

        Read Only Fields

        • date_created
        • id

        Authentication

        • X-Auth-Token in header - required

        Parameters

        • store_hash in path - string
        • id in path - integer - required

          ID of the banner.

        • Content-Type in header with default of application/json - string - required

          The MIME type of the request body.

        Body

        application/json
          • name
            string
            required

            Name of the banner.

            Example: Sale Banner

          • content
            string
            required

            Contains the banner content. Returned as a string and includes HTML formatting.

            Example: <p> Sale! Tuesday at 9am! </p>

          • page
            string
            required

            Page the Banner is located on.

            Allowed: home_page | category_page | brand_page | search_page

          • location
            string
            required

            Location on the page.

            Allowed: top | bottom

            Example: top

          • date_type
            string
            required

            This specifies whether the banner should be visible during a specific date range.

            Allowed: always | custom

          • date_from
            string

            If the datetype is set as 'custom’, this field specifies the date when the banner should become visible on the storefront.

            Example: 0

          • date_to
            string

            If the datetype is set as 'custom’, this field specifies the date when the banner should stop being visible on the storefront.

            Example: 0

          • visible
            string

            Integer value denoting whether or not the banner is visible on the storefront: 1 = visible; 0 = not visible

            Example: 1

          • item_id
            string

            If the banner is on a specific category or brand page, then the item_id will correspond the category or brand ID.

            Example: 35

            example

            Response

            Body

            application/json
            • id
              integer

              Id of the banner. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request.

              Example: 1

            • date_created
              string

              Date the banner is created.

            • name
              string
              required

              Name of the banner.

              Example: Sale Banner

            • content
              string
              required

              Contains the banner content. Returned as a string and includes HTML formatting.

              Example: <p> Sale! Tuesday at 9am! </p>

            • page
              string
              required

              Page the Banner is located on.

              Allowed: home_page | category_page | brand_page | search_page

            • location
              string
              required

              Location on the page.

              Allowed: top | bottom

              Example: top

            • date_type
              string
              required

              This specifies whether the banner should be visible during a specific date range.

              Allowed: always | custom

            • date_from
              string

              If the datetype is set as 'custom’, this field specifies the date when the banner should become visible on the storefront.

              Example: 0

            • date_to
              string

              If the datetype is set as 'custom’, this field specifies the date when the banner should stop being visible on the storefront.

              Example: 0

            • visible
              string

              Integer value denoting whether or not the banner is visible on the storefront: 1 = visible; 0 = not visible

              Example: 1

            • item_id
              string

              If the banner is on a specific category or brand page, then the item_id will correspond the category or brand ID.

              Example: 35

              example

              Delete a Banner

              DELETE /banners/{id}

              Request

              Deletes a Banner.

              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.

              • id in path - integer - required

                ID of the banner.

              example

              Response

              Get a Count of Store Banners

              GET /banners/count

              Request

              Returns a count of Banners.

              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.

              example

              Response

              Body

              object | application/json
              • count
                integer

              example

              Did you find what you were looking for?