openapi: 3.0.1 info: title: BigCommerce Subscribers description: Manage subscribers. termsOfService: https://www.bigcommerce.com/terms contact: name: BigCommerce url: https://www.bigcommerce.com email: support@bigcommerce.com license: name: '' version: '' 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: schemas: 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 Subscriber: allOf: - title: Subscriber Base type: object properties: id: type: integer description: > The unique numeric ID of the subscriber; increments sequentially. x-required: - put 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 description: Common Subscriber properties. - type: object properties: 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_Post: title: subscriber_Post description: | The model for a POST to create a subscriber. allOf: - $ref: '#/components/schemas/subscriber_Base' x-internal: false subscriber_Put: title: subscriber_Put description: | The model for a PUT to update a subscriber. allOf: - $ref: '#/components/schemas/subscriber_Base' x-internal: false 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 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. x-internal: false OpenMeta: title: Response meta type: object properties: {} additionalProperties: true description: Response metadata. ErrorResponse: title: Error Response allOf: - title: Base Error type: object properties: status: type: integer description: | The 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. - type: object properties: errors: title: Detailed Errors type: object properties: {} additionalProperties: true x-internal: false BaseError: title: Base Error type: object properties: status: type: integer description: | The 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. x-internal: false NotFound: 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. x-internal: false DetailedErrors: title: Detailed Errors type: object properties: {} additionalProperties: true x-internal: false responses: subrscriberCollection_Resp: 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. subscriber_Resp: description: '' content: application/json: schema: title: Subscriber Response type: object properties: data: $ref: '#/components/schemas/subscriber_Full' meta: $ref: '#/components/schemas/OpenMeta' parameters: FilterEmailParam: name: email in: query description: | Filter items by email. schema: type: string FilterFirstNameParam: name: first_name in: query description: | Filter items by first_name. schema: type: string FilterLastNameParam: name: last_name in: query description: | Filter items by last_name. schema: type: string FilterSourceParam: name: source in: query description: | Filter items by source. schema: type: string FilterOrderIdParam: name: order_id in: query description: | Filter items by order_id. schema: type: integer FilterDateModifiedParam: 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 FilterDateCreatedParam: name: date_created in: query description: | Filter items by date_created. schema: type: string format: date-time PageParam: name: page in: query description: Specifies the page number in a limited (paginated) list of products. schema: type: integer LimitParam: name: limit in: query description: >- Controls the number of items per page in a limited (paginated) list of products. schema: type: integer ScriptsSortKeyParam: name: sort in: query description: | Scripts field name to sort by. schema: type: string enum: - name - description - date_created - date_modified DirectionParam: name: direction in: query description: | Sort direction. Acceptable values are: `asc`, `desc`. schema: type: string enum: - asc - desc SubscriberIdParam: name: subscriber_id in: path description: | The ID of the `Subscriber` requested. required: true schema: type: integer 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 | |:--|:--|:-| | Customers | modify | `store_v2_customers` | | Customers | read-only | `store_v2_customers_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