BigCommerce Subscribers is a service that allows online business owners to build and maintain a subscriber list for their e-commerce website. By collecting and organizing customer contact information, BigCommerce Subscribers enables businesses to communicate with their audience through targeted email marketing campaigns.
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: [email protected]
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