BigCommerce Subscribers API

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Cart Emails Subscribers API
  version: 3.0.0
  termsOfService: https://www.bigcommerce.com/terms
  description: Abandoned Cart Emails V3 API managing Handlebars-based emails.
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Subscribers
  description: BigCommerce Customers API Definition.
paths:
  /customers/subscribers:
    parameters:
    - $ref: '#/components/parameters/Accept'
    get:
      tags:
      - Subscribers
      summary: BigCommerce Get Subscribers
      description: Returns a list of *Subscribers*. Optional filter parameters can be passed in.
      operationId: getSubscribers
      parameters:
      - name: email
        in: query
        description: 'Filter items by email.

          '
        schema:
          type: string
      - name: first_name
        in: query
        description: 'Filter items by first_name.

          '
        schema:
          type: string
      - name: last_name
        in: query
        description: 'Filter items by last_name.

          '
        schema:
          type: string
      - name: source
        in: query
        description: 'Filter items by source.

          '
        schema:
          type: string
      - name: order_id
        in: query
        description: 'Filter items by order_id.

          '
        schema:
          type: integer
      - name: date_created
        in: query
        description: 'Filter items by date_created.

          '
        schema:
          type: string
          format: date-time
      - name: date_modified
        in: query
        description: Filter items by date_modified. For example `v3/catalog/products?date_last_imported:min=2018-06-15`
        schema:
          type: string
          format: date-time
      - name: page
        in: query
        description: Specifies the page number in a limited (paginated) list of products.
        schema:
          type: integer
      - name: limit
        in: query
        description: Controls the number of items per page in a limited (paginated) list of products.
        schema:
          type: integer
      - name: id
        in: query
        description: Filter items by id.
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: Subscriber Collection Response
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/subscriber_Full'
                  meta:
                    $ref: '#/components/schemas/CollectionMeta'
                description: 'Response payload for the BigCommerce API.

                  '
    post:
      tags:
      - Subscribers
      summary: BigCommerce Create a Subscriber
      description: 'Creates a *Subscriber*.


        **Required Fields**

        * email


        **Read Only Fields**

        * id'
      operationId: createSubscriber
      parameters:
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/subscriber_Post'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: Subscriber Response
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/subscriber_Full'
                  meta:
                    $ref: '#/components/schemas/OpenMeta'
        '409':
          description: 'The `Subscriber` was in conflict with another subscriber. This is the result of duplicate unique values, such as email.

            '
          content:
            application/json:
              schema:
                title: Error Response
                type: object
                properties:
                  errors:
                    title: Detailed Errors
                    type: object
                    properties: {}
                    additionalProperties: true
                  instance:
                    type: string
                  status:
                    type: integer
                    description: 'The HTTP status code.

                      '
                  title:
                    type: string
                    description: 'The error title describing the particular error.

                      '
                  type:
                    type: string
        '422':
          description: 'The `Subscriber` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.

            '
          content:
            application/json:
              schema:
                title: Error Response
                type: object
                properties:
                  errors:
                    title: Detailed Errors
                    type: object
                    properties: {}
                    additionalProperties: true
                  instance:
                    type: string
                  status:
                    type: integer
                    description: 'The HTTP status code.

                      '
                  title:
                    type: string
                    description: 'The error title describing the particular error.

                      '
                  type:
                    type: string
      x-codegen-request-body-name: subscriber
    delete:
      tags:
      - Subscribers
      summary: BigCommerce Delete Subscribers
      description: By default, it deletes all *Subscribers*. A filter should be added to avoid deleting all subscribers in a store.
      operationId: deleteSubscribers
      parameters:
      - name: email
        in: query
        description: 'Filter items by email.

          '
        schema:
          type: string
      - name: first_name
        in: query
        description: 'Filter items by first_name.

          '
        schema:
          type: string
      - name: last_name
        in: query
        description: 'Filter items by last_name.

          '
        schema:
          type: string
      - name: source
        in: query
        description: 'Filter items by source.

          '
        schema:
          type: string
      - name: order_id
        in: query
        description: 'Filter items by order_id.

          '
        schema:
          type: integer
      - name: date_created
        in: query
        description: 'Filter items by date_created.

          '
        schema:
          type: string
          format: date-time
      - name: date_modified
        in: query
        description: Filter items by date_modified. For example `v3/catalog/products?date_last_imported:min=2018-06-15`
        schema:
          type: string
          format: date-time
      responses:
        '204':
          description: ''
          content: {}
  /customers/subscribers/{subscriber_id}:
    parameters:
    - $ref: '#/components/parameters/Accept'
    get:
      tags:
      - Subscribers
      summary: BigCommerce Get a Subscriber
      description: Returns a *Subscriber*.
      operationId: getSubscriber
      parameters:
      - name: subscriber_id
        in: path
        description: 'The ID of the `Subscriber` requested.

          '
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: Subscriber Response
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/subscriber_Full'
                  meta:
                    $ref: '#/components/schemas/OpenMeta'
        '404':
          description: 'The resource was not found.

            '
          content:
            application/json:
              schema:
                title: Not Found
                type: object
                properties:
                  status:
                    type: integer
                    description: '404 HTTP status code.

                      '
                  title:
                    type: string
                    description: The error title describing the particular error.
                  type:
                    type: string
                  instance:
                    type: string
                description: Error payload for the BigCommerce API.
    put:
      tags:
      - Subscribers
      summary: BigCommerce Update a Subscriber
      description: 'Updates a *Subscriber*.


        **Read Only Fields**

        * id'
      operationId: updateSubscriber
      parameters:
      - name: subscriber_id
        in: path
        description: 'The ID of the `Subscriber` requested.

          '
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/subscriber_Put'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: Subscriber Response
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/subscriber_Full'
                  meta:
                    $ref: '#/components/schemas/OpenMeta'
        '404':
          description: 'The resource was not found.

            '
          content:
            application/json:
              schema:
                title: Not Found
                type: object
                properties:
                  status:
                    type: integer
                    description: '404 HTTP status code.

                      '
                  title:
                    type: string
                    description: The error title describing the particular error.
                  type:
                    type: string
                  instance:
                    type: string
                description: Error payload for the BigCommerce API.
        '409':
          description: 'The `Subscriber` was in conflict with another subscriber. This is the result of duplicate unique values, such as `email`.

            '
          content:
            application/json:
              schema:
                title: Error Response
                type: object
                properties:
                  errors:
                    title: Detailed Errors
                    type: object
                    properties: {}
                    additionalProperties: true
                  instance:
                    type: string
                  status:
                    type: integer
                    description: 'The HTTP status code.

                      '
                  title:
                    type: string
                    description: 'The error title describing the particular error.

                      '
                  type:
                    type: string
        '422':
          description: 'The `Subscriber` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.

            '
          content:
            application/json:
              schema:
                title: Error Response
                type: object
                properties:
                  errors:
                    title: Detailed Errors
                    type: object
                    properties:
                      additionalProperties:
                        type: string
                  instance:
                    type: string
                  status:
                    type: integer
                    description: 'The HTTP status code.

                      '
                  title:
                    type: string
                    description: 'The error title describing the particular error.

                      '
                  type:
                    type: string
      x-codegen-request-body-name: subscriber
    delete:
      tags:
      - Subscribers
      summary: BigCommerce Delete a Subscriber
      description: Deletes a *Subscriber*.
      operationId: deleteSubscriber
      parameters:
      - name: subscriber_id
        in: path
        description: 'The ID of the `Subscriber` requested.

          '
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: ''
          content: {}
components:
  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
  schemas:
    subscriber_Put:
      title: subscriber_Put
      description: 'The model for a PUT to update a subscriber.

        '
      allOf:
      - $ref: '#/components/schemas/subscriber_Base'
      x-internal: false
    OpenMeta:
      title: Response meta
      type: object
      properties: {}
      additionalProperties: true
      description: Response metadata.
    CollectionMeta:
      title: Collection Meta
      type: object
      properties:
        pagination:
          title: Pagination
          type: object
          properties:
            total:
              type: integer
              description: 'Total number of items in the result set.

                '
              example: 36
            count:
              type: integer
              description: 'Total number of items in the collection response.

                '
              example: 36
            per_page:
              type: integer
              description: 'The amount of items returned in the collection per page, controlled by the limit parameter.

                '
              example: 50
            current_page:
              type: integer
              description: 'The page you are currently on within the collection.

                '
              example: 1
            total_pages:
              type: integer
              description: 'The total number of pages in the collection.

                '
              example: 1
            links:
              type: object
              properties:
                previous:
                  type: string
                  description: 'Link to the previous page returned in the response.

                    '
                current:
                  type: string
                  description: 'Link to the current page returned in the response.

                    '
                  example: ?page=1&limit=50
                next:
                  type: string
                  description: 'Link to the next page returned in the response.

                    '
              description: 'Pagination links for the previous and next parts of the whole collection.

                '
          description: Data about the response, including pagination and collection totals.
      description: Data about the response, including pagination and collection totals.
      x-internal: false
    subscriber_Post:
      title: subscriber_Post
      description: 'The model for a POST to create a subscriber.

        '
      allOf:
      - $ref: '#/components/schemas/subscriber_Base'
      x-internal: false
    subscriber_Full:
      title: subscriber_Full
      description: Full subscriber object returned in responses.
      allOf:
      - $ref: '#/components/schemas/subscriber_Base'
      - type: object
        properties:
          id:
            type: integer
            description: The unique numeric ID of the subscriber; increments sequentially.
          date_modified:
            type: string
            description: 'The date on which the subscriber was modified.

              '
            format: date-time
          date_created:
            type: string
            description: 'The date of which the subscriber was created.

              '
            format: date-time
      x-internal: false
    subscriber_Base:
      title: subscriber_Base
      type: object
      properties:
        email:
          type: string
          description: 'The email of the subscriber. Must be unique.

            '
          x-required:
          - post
        first_name:
          maxLength: 255
          minLength: 0
          type: string
          description: 'The first name of the subscriber.

            '
        last_name:
          maxLength: 255
          minLength: 0
          type: string
          description: 'The last name of the subscriber.

            '
        source:
          maxLength: 255
          minLength: 0
          type: string
          description: 'The source of the subscriber. Values are: `storefront`, `order`, or `custom`.

            '
        order_id:
          maximum: 2147483647
          minimum: 1
          type: integer
          description: 'The ID of the source order, if source was an order.

            '
          nullable: true
        channel_id:
          maximum: 2147483647
          minimum: 1
          type: integer
          description: The channel ID where the subscriber was created.
      description: Common Subscriber properties.
      x-internal: false
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: '### OAuth scopes


        | UI Name | Permission | Parameter |

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

        | Information & Settings  | read-only  | `store_v2_information_read_only`|

        | Information & Settings  | modify     | `store_v2_information`          |


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