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

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

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

Response

Body

array | application/json

    example

    [
  {
    "id": 1,
    "name": "This is a banner",
    "content": "<p>This is a banner</p>",
    "page": "home_page",
    "item_id": "0",
    "location": "top",
    "date_created": "1522169082",
    "date_type": "always",
    "date_from": "0",
    "date_to": "0",
    "visible": "1"
  },
  {
    "id": 2,
    "name": "Banner #2",
    "content": "<p>Banner # 2</p>",
    "page": "category_page",
    "item_id": "23",
    "location": "top",
    "date_created": "1522169169",
    "date_type": "always",
    "date_from": "0",
    "date_to": "0",
    "visible": "1"
  }
]

    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

    example

    {
  "name": "Sale Banner",
  "content": "<p> Sale! Tuesday at 9am! </p>",
  "page": "home_page",
  "location": "top",
  "date_type": "always",
  "date_from": "0",
  "date_to": "0",
  "visible": "1"
}

    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.

    • 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: 0

    • 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

      example

      {
  "id": 1,
  "name": "Sale Banner",
  "content": "<p> Sale! Tuesday at 9am! </p>",
  "page": "home_page",
  "item_id": "0",
  "location": "top",
  "date_created": "1522169082",
  "date_type": "always",
  "date_from": "0",
  "date_to": "0",
  "visible": "1"
}

      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

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

      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

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

      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.

      • 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: 0

      • 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

        example

        {
  "id": 1,
  "name": "Sale Banner",
  "content": "<p> Sale! Tuesday at 9am! </p>",
  "page": "home_page",
  "item_id": "0",
  "location": "top",
  "date_created": "1522169082",
  "date_type": "always",
  "date_from": "0",
  "date_to": "0",
  "visible": "1"
}

        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

        • 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: 0

        • 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

          example

          {
  "item_id": "0",
  "name": "Sale Banner",
  "content": "<p> Sale! Tuesday at 9am! </p>",
  "page": "home_page",
  "location": "top",
  "date_type": "always",
  "date_from": "0",
  "date_to": "0",
  "visible": "1"
}

          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.

          • 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: 0

          • 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

            example

            {
  "id": 1,
  "name": "Sale Banner",
  "content": "<p> Sale! Tuesday at 9am! </p>",
  "page": "home_page",
  "item_id": "0",
  "location": "top",
  "date_created": "Tue, 13 Mar 2018 16:18:59 +0000",
  "date_type": "always",
  "date_from": "0",
  "date_to": "0",
  "visible": "1"
}

            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

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

            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

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

            Response

            Body

            object | application/json

            • count              integer

            example

            {
  "count": 27
}