BigCommerce Banners API

openapi: 3.2.0
info:
  title: BigCommerce Marketing Banners API
  description: 'Manage coupons, banners, and gift certificates.


    ## Subresources


    ### Coupons

    Category or product discounts that can be applied to orders for customers who enter a given code.


    ### Banners

    Banners available to display on a store.


    ### Gift Certificates

    Gift certificates available to offer to a store’s customers.'
  termsOfService: https://www.bigcommerce.com/terms
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
  version: ''
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v2
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Banners
paths:
  /banners:
    parameters:
    - $ref: '#/components/parameters/Accept'
    get:
      tags:
      - Banners
      summary: BigCommerce Get All Banners
      description: Returns a list of *Banners*. Default sorting is by banner id, from lowest to highest.
      operationId: getBanners
      parameters:
      - name: min_id
        in: query
        description: Optional filter param `/api/v2/banners?min_id={value}`
        schema:
          type: integer
      - name: max_id
        in: query
        description: Optional filter param `/api/v2/banners?max_id={value}`
        schema:
          type: integer
      - name: page
        in: query
        description: Optional filter param `/api/v2/banners?page={number}`
        schema:
          type: number
      - name: limit
        in: query
        description: Optional filter param `/api/v2/banners?limit={count}`
        schema:
          type: number
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/banner_Full'
              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'
    post:
      tags:
      - Banners
      summary: BigCommerce Create a Banner
      description: 'Creates a *Banner*.


        **Required Fields**

        * name

        * content

        * page

        * location

        * date_type


        **Read Only Fields**

        * date_created

        * id'
      operationId: createBanner
      parameters:
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/banner_Base'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/banner_Full'
              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'
      x-codegen-request-body-name: body
    delete:
      tags:
      - Banners
      summary: BigCommerce Delete All Banners
      description: By default, it deletes all *Banners*.
      operationId: deleteBanners
      responses:
        '204':
          description: ''
          content: {}
  /banners/{id}:
    parameters:
    - $ref: '#/components/parameters/Accept'
    - name: id
      in: path
      description: ID of the banner.
      required: true
      schema:
        type: integer
    get:
      tags:
      - Banners
      summary: BigCommerce Get a Banner
      description: Returns a single *Banner*
      operationId: getBanner
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/banner_Full'
              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'
    put:
      tags:
      - Banners
      summary: BigCommerce Update a Banner
      description: 'Updates a *Banner*.


        **Read Only Fields**

        * date_created

        * id'
      operationId: updateBanner
      parameters:
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/banner_Put'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/banner_Full'
              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'
      x-codegen-request-body-name: body
    delete:
      tags:
      - Banners
      summary: BigCommerce Delete a Banner
      description: Deletes a *Banner*.
      operationId: deleteBanner
      responses:
        '204':
          description: ''
          content: {}
  /banners/count:
    parameters:
    - $ref: '#/components/parameters/Accept'
    get:
      tags:
      - Banners
      summary: BigCommerce Get a Count of Store Banners
      description: Returns a count of *Banners*.
      operationId: getBannersCount
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    minimum: 0
                    type: integer
              example:
                count: 27
components:
  schemas:
    banner_Base:
      title: banner_Base
      required:
      - content
      - date_type
      - location
      - name
      - page
      type: object
      properties:
        name:
          type: string
          description: Name of the banner.
          example: Sale Banner
        content:
          type: string
          description: Contains the banner content. Returned as a string and includes HTML formatting.
          example: <p> Sale! Tuesday at 9am! </p>
        page:
          type: string
          description: Page the Banner is located on.
          enum:
          - home_page
          - category_page
          - brand_page
          - search_page
        location:
          type: string
          description: Location on the page.
          example: top
          enum:
          - top
          - bottom
        date_type:
          type: string
          description: This specifies whether the banner should be visible during a specific date range.
          enum:
          - always
          - custom
        date_from:
          type: string
          description: 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:
          type: string
          description: 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:
          type: string
          description: 'Integer value denoting whether or not the banner is visible on the storefront: 1 = visible; 0 = not visible'
          example: '1'
        item_id:
          type: string
          description: If the banner is on a specific category or brand page, then the item_id will correspond the category or brand ID.
          example: '35'
      x-internal: false
    banner_Full:
      title: banner_Full
      allOf:
      - type: object
        properties:
          id:
            type: integer
            description: '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:
            type: string
            description: Date the banner is created.
      - $ref: '#/components/schemas/banner_Base'
      x-internal: false
    banner_Put:
      title: banner_Put
      allOf:
      - type: object
      - $ref: '#/components/schemas/banner_Base'
      x-internal: false
  parameters:
    Accept:
      name: Accept
      in: header
      required: true
      description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.
      schema:
        type: string
        default: application/json
    ContentType:
      name: Content-Type
      in: header
      required: true
      description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.
      schema:
        type: string
        default: application/json
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: '### OAuth scopes


        | UI Name | Permission | Parameter |

        |:--|:--|:-|

        |  Marketing | modify | `store_v2_marketing` |

        |  Marketing | read-only | `store_v2_marketing_read_only` |


        ### Authentication header


        | Header | Argument | Description |

        |:-|:|:|

        | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). |


        ### Further reading


        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests).


        For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes).


        For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).'
      type: apiKey
      in: header