BigCommerce Abandoned Carts is a tool designed to help businesses recover potentially lost sales by targeting customers who have added items to their online shopping cart but have not completed the purchase. This tool sends automated emails to remind customers of their abandoned carts and encourages them to complete their purchase through personalized messages, discount offers, or incentives.
openapi: 3.0.0
info:
version: ''
title: BigCommerce Abandoned Carts
description: >-
Use `/abandoned-carts/{token}` on headless storefronts to retrieve the
`cart_id` using the abandoned cart `token` passed to the storefront when a
shopper clicks an abandoned cart email link. Once the cart ID has been
retrieved, your application can use it to fetch and display information
about the cart to the shopper using the REST Storefront API, the REST
Management API, or the GraphQL Storefront API.
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: [email protected]
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: Abandoned Cart Settings
- name: Abandoned Carts
- name: Abandoned Carts Settings
paths:
/abandoned-carts/settings:
get:
summary: BigCommerce Get Global Abandoned Cart Settings
description: Returns the global abandoned cart settings of a store.
operationId: getGlobalAbandonedCartSettings
tags:
- Abandoned Cart Settings
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalAbandonedCartSettingsResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
parameters: []
put:
summary: BigCommerce Update Global Abandoned Cart Settings
description: Updates the global abandoned cart settings of a store.
operationId: updateGlobalAbandonedCartSettings
tags:
- Abandoned Carts Settings
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalAbandonedCartSettingsRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalAbandonedCartSettingsResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Unprocessable entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
parameters:
- $ref: '#/components/parameters/ContentType'
parameters:
- $ref: '#/components/parameters/Accept'
/abandoned-carts/settings/channels/{channel_id}:
get:
summary: BigCommerce Get Channel Abandoned Cart Settings
description: >-
Returns the per-channel overrides for the abandoned cart settings of a
store.
operationId: getChannelAbandonedCartSettings
tags:
- Abandoned Carts Settings
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ChannelAbandonedCartSettingsResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
summary: BigCommerce Update Channel Abandoned Cart Settings
description: >-
Updates the per-channel overrides for the abandoned cart settings of a
store.
#### OAuth Scopes
| UI Name | Permission |
Parameter |
|-||--|
| Information & Settings | modify |
`store_v2_information` |
operationId: updateChannelAbandonedCartSettings
tags:
- Abandoned Carts Settings
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChannelAbandonedCartSettingsRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ChannelAbandonedCartSettingsResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Unprocessable entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security: []
parameters:
- $ref: '#/components/parameters/Accept'
- name: channel_id
description: The channel ID of the settings overrides
in: path
required: true
schema:
type: integer
/abandoned-carts/{token}:
get:
responses:
'200':
$ref: '#/components/responses/abandonedCart_Resp'
'400':
$ref: '#/components/responses/400_BadRequest'
'404':
$ref: '#/components/responses/404_NotFound'
'422':
$ref: '#/components/responses/422_UnprocessableEntity'
'502':
$ref: '#/components/responses/502_GatewayError'
'503':
$ref: '#/components/responses/503_ServiceUnavailable'
'504':
$ref: '#/components/responses/504_GatewayTimeout'
default:
description: ''
summary: BigCommerce Get an Abandoned Cart
description: >-
Returns the `cart_id` corresponding to the abandoned cart `{token}`
passed in.
**Usage Notes**:
* `{token}` is the token in the query string of the abandoned cart link
found in abandoned cart email notifications to shoppers
operationId: getAbandonedCarts
tags:
- Abandoned Carts
parameters:
- name: token
in: path
required: true
description: |-
Unique cart `UUID`.
Unique cart `UUID` token that is generated for abandoned cart emails.
schema:
type: string
- $ref: '#/components/parameters/Accept'
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
responses:
502_GatewayError:
description: >-
If something happens during the request that causes it to fail, a 502
response will be returned. A new request should be made; however, it
could fail.
content:
application/json:
schema:
$ref: '#/components/schemas/error_Full'
examples:
response:
value:
status: 502
title: >-
A login URL could not be generated. Please try another
request.
type: /api-docs/getting-started/api-status-codes
504_GatewayTimeout:
description: >-
If this occurs, you should retry the request. Typically retrying the
request several times will result in a successful request; However, if
you are unable to successfully make a request, please check the
BigCommerce system status [here](https://status.bigcommerce.com/). A
service is likely down and the request will need to be made again when
it is back up (in several hours usually)
content:
application/json:
schema:
$ref: '#/components/schemas/errorDetailed_Full'
examples:
response:
value:
status: 504
title: Gateway Timeout
type: /api-docs/getting-started/api-status-codes
errors: {}
403_Unauthorized:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/error_Full'
examples:
response:
value:
status: 403
title: >-
Unauthorized Access. You do not have permission to make this
request.
type: /api-docs/getting-started/api-status-codes
400_BadRequest:
description: |-
Malformed request syntax. Typically need to fix the JSON
Body to resend successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/error_Full'
examples:
response:
value:
status: 400
title: Input is invalid.
type: /api-docs/getting-started/api-status-codes
404_NotFound:
description: >-
If the requested account resource is not found for the franchise, return
a 404 Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/error_Full'
examples:
response:
value:
status: 404
title: Account with {id} not found
type: /api-docs/getting-started/api-status-codes
422_UnprocessableEntity:
description: >-
This occurs when missing or unacceptable data is passed for one or more
fields. Please correct the values for the fields listed in the errors
object.
content:
application/json:
schema:
$ref: '#/components/schemas/errorDetailed_Full'
examples:
response:
value:
status: 422
title: JSON data is missing or invalid
type: /api-docs/getting-started/api-status-codes
errors:
name: error.expected.jsstring
primary_contact.district: error.expected.jsstring.
503_ServiceUnavailable:
description: >-
If this occurs, you should retry the request. If you are unable to
successfully make a request, please check the BigCommerce system status
[here](https://status.bigcommerce.com/). A service is likely down and
the request will need to be made again when it is back up (in several
hours usually)
content:
application/json:
schema:
$ref: '#/components/schemas/error_Full'
examples:
response:
value:
status: 503
title: Service Unavailable
type: /api-docs/getting-started/api-status-codes
abandonedCart_Resp:
description: Returned on `GET` requests to `/abandoned_carts`.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/abandonedCartInfo_Full'
meta:
$ref: '#/components/schemas/metaEmpty_Full'
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
schemas:
metaEmpty_Full:
title: Response meta
type: object
properties: {}
additionalProperties: true
description: Response metadata.
error_Full:
type: object
title: error_Full
properties:
status:
description: |
The HTTP status code.
type: integer
title:
description: |
The error title describing the particular error.
type: string
type:
type: string
x-internal: false
errorDetailed_Full:
type: object
properties:
errors:
type: object
additionalProperties:
type: string
title: DetailedErrors
title: errorDetailed_Full
x-internal: false
abandonedCartInfo_Full:
type: object
title: abandonedCartInfo_Full
properties:
cart_id:
type: string
description: >-
The `cart_id` of the abandoned cart. Can be used to display the
abandoned cart to the customer using storefront cart or
server-to-server cart APIs.
x-internal: false
AbandonedCartSettings:
description: >-
Represents all settings related to the abandoned cart functionality of a
store
type: object
x-tags:
- Models
properties:
enable_notification:
description: Indicates whether or not abandoned cart notification is on
type: boolean
email_customer_until_cart_is_recovered:
description: >-
Indicates whether or not a customer should continue to receive
abandoned cart emails until their cart is recovered
type: boolean
marketing_emails_require_customer_consent:
description: >-
Indicates whether or not a customer should receive abandoned cart
emails based on their consent. By default customers will not receive
emails.
type: boolean
email_merchant_when_cart_is_converted:
description: >-
Indicates whether or not a merchant should receive a notification
email when a cart is converted into an order
type: boolean
email_merchant_when_cart_is_abandoned:
description: >-
Indicates whether or not a merchant should receive a notification
email when a cart is abandoned
type: boolean
merchant_email_address:
description: The email address for receiving merchant notifications
type: string
format: email
merchant_abandoned_cart_email_frequency_type:
description: >-
Indicates whether to send an email for every abandoned cart, or to
send a digest email after X number of abandoned carts
type: string
enum:
- digest
- individual
merchant_abandoned_cart_digest_email_frequency:
description: >-
The number of abandoned carts to accumulate before a digest email is
sent to a merchant
type: integer
minimum: 2
maximum: 1000
ChannelAbandonedCartSettings:
description: >-
Represents all settings overrides related to the abandoned cart
functionality of a store for a channel
type: object
x-tags:
- Models
properties:
enable_notification:
description: >-
Indicates whether or not abandoned cart notification is on. If it is
null, it means there is no override for the specified channel.
type: boolean
nullable: true
email_customer_until_cart_is_recovered:
description: >-
Indicates whether or not a customer should continue to receive
abandoned cart emails until their cart is recovered. If it is null,
it means there is no override for the specified channel.
type: boolean
nullable: true
marketing_emails_require_customer_consent:
description: >-
Indicates whether or not a customer should receive abandoned cart
emails based on their consent. If it is null, it means there is no
override for the specified channel. By default customers will not
receive emails.
type: boolean
nullable: true
email_merchant_when_cart_is_converted:
description: >-
Indicates whether or not a merchant should receive a notification
email when a cart is converted into an order. If it is null, it
means there is no override for the specified channel.
type: boolean
nullable: true
email_merchant_when_cart_is_abandoned:
description: >-
Indicates whether or not a merchant should receive a notification
email when a cart is abandoned. If it is null, it means there is no
override for the specified channel.
type: boolean
nullable: true
merchant_email_address:
description: >-
The email address for receiving merchant notifications. If it is
null, it means there is no override for the specified channel.
type: string
format: email
nullable: true
merchant_abandoned_cart_email_frequency_type:
description: >-
Indicates whether to send an email for every abandoned cart or to
send a digest email after X number of abandoned carts. If it is
null, it means there is no override for the specified channel.
type: string
enum:
- digest
- individual
nullable: true
merchant_abandoned_cart_digest_email_frequency:
description: >-
The number of abandoned carts to accumulate before a digest email is
sent to a merchant. If it is null, it means there is no override for
the specified channel.
type: integer
minimum: 2
maximum: 1000
nullable: true
ChannelAbandonedCartSettingsRequest:
allOf:
- $ref: '#/components/schemas/ChannelAbandonedCartSettings'
- description: >-
The request object for updating the abandoned cart settings
overrides of a store for a channel
x-tags:
- Models
ChannelAbandonedCartSettingsResponse:
description: The response object of abandoned cart settings overrides for a channel
type: object
properties:
data:
$ref: '#/components/schemas/ChannelAbandonedCartSettings'
meta:
$ref: '#/components/schemas/metaEmpty_Full'
x-tags:
- Models
GlobalAbandonedCartSettingsRequest:
allOf:
- $ref: '#/components/schemas/AbandonedCartSettings'
- description: >-
The request object for updating the abandoned cart settings of a
store at the global level
required:
- enabled
- email_customer_until_cart_is_recovered
- marketing_emails_require_customer_consent
- email_merchant_when_cart_is_converted
- email_merchant_when_cart_is_abandoned
- merchant_email_address
- merchant_abandoned_cart_email_frequency_type
- merchant_abandoned_cart_digest_email_frequency
x-tags:
- Models
GlobalAbandonedCartSettingsResponse:
description: The response object of abandoned cart settings at the global level
type: object
properties:
data:
$ref: '#/components/schemas/AbandonedCartSettings'
meta:
$ref: '#/components/schemas/metaEmpty_Full'
x-tags:
- Models
ErrorResponse:
description: The response object containing details of an error
type: object
properties:
status:
type: integer
title:
type: string
type:
type: string
instance:
type: string
errors:
type: object
x-tags:
- Models