openapi: 3.0.0
info:
title: BigCommerce Abandoned Cart Emails Import-Export 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: Import-Export
paths:
/storefront/redirects/imex/jobs:
parameters:
- $ref: '#/components/parameters/Accept'
get:
tags:
- Import-Export
summary: BigCommerce Get Redirect Import-Export Jobs
description: Returns a collection of the storeʼs 301 redirects across all sites.
operationId: getRedirectImportExportJobs
parameters:
- name: id
in: query
description: Filters results by Redirect Import-Export job ID.
style: form
explode: false
schema:
type: string
- name: type
in: query
description: Filters results by the type of the Redirect Import-Export job.
style: form
explode: false
schema:
$ref: '#/components/schemas/ImportExportJobType'
- name: status
in: query
description: Filters results by the status of the Redirect Import-Export job.
style: form
explode: false
schema:
$ref: '#/components/schemas/ImportExportJobStatus'
- name: limit
in: query
description: Determines the number of items returned per page. The default is 10 items per page.
schema:
type: integer
default: 10
- name: page
in: query
description: Specifies the page number to return when the number of items returned exceeds the page limit. Used to paginate large collections.
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/301RedirectImportExportJobRead'
meta:
$ref: '#/components/schemas/MetaPaginationObject'
/storefront/redirects/imex/export:
parameters:
- $ref: '#/components/parameters/Accept'
post:
tags:
- Import-Export
summary: BigCommerce Create Redirects Export Job
description: Creates a new 301 Redirects export job.
operationId: createRedirectExportJob
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
type: object
properties:
site_id:
type: integer
nullable: true
default: null
description: The site ID for which you wish to export redirects. If no site ID is provided, the request exports all redirects for all sites.
redirect_ids:
type: array
items:
type: integer
default: []
description: A list of the redirect IDs you wish to export. If no redirect IDs are provided, the request exports all redirects for the given site selection.
include_dynamic_target_urls:
type: boolean
default: false
description: If true, the exported CSV will contain an additional read-only column containing the target URL for dynamic redirects.
description: Data necessary to create a new 301 Redirects export job.
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: ab1c2de3-f4gh-5678-i90j-klm12n345o67
'409':
description: No Redirects in your store meet the criteria in your request.
'429':
description: Your store already has an active Redirects import or export job running.
/storefront/redirects/imex/import:
parameters:
- $ref: '#/components/parameters/Accept'
post:
tags:
- Import-Export
summary: BigCommerce Create Redirects Import Job
description: Creates a new 301 Redirects import job.
operationId: createRedirectImportJob
parameters:
- $ref: '#/components/parameters/ContentTypeFormData'
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
import_file:
description: 'A CSV file containing a list of Redirects to be imported.
The headers must be defined as follows:
`Domain,Old Path,Manual URL/Path,Dynamic Target Type,Dynamic Target ID`
Not every line will have a value for every column.'
type: string
format: binary
example: "Domain,Old Path,Manual URL/Path,Dynamic Target Type,Dynamic Target ID \nstore.example.com,/old-path,/new-manual-path,, \nstore.example.com,/old-product,,Product,12 \nstore.example.com,/old-brand,,Brand,34 \nstore.example.com,/old-category,,Category,56 \nstore.example.com,/old-page,,Page,78 \nstore.example.com,/old-post,,Post,90"
required:
- import_file
description: Data necessary to create a new 301 Redirects import job.
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: ab1c2de3-f4gh-5678-i90j-klm12n345o67
'400':
description: The provided form data was invalid or the file is not a CSV.
'413':
description: The provided file is too large. The maximum file size is 20MB.
'429':
description: Your store already has an active Redirects import or export job running.
/storefront/redirects/imex/export/{uuid}/events:
parameters:
- $ref: '#/components/parameters/AcceptEventStream'
- $ref: '#/components/parameters/ImportExportIdParam'
get:
tags:
- Import-Export
summary: BigCommerce Open Redirect Export Event Stream
description: Opens an event stream to receive live updates from an export job.
operationId: getRedirectExportEvents
responses:
'200':
description: Stream of export events. The `data` attribute is stringified JSON.
content:
text/event-stream:
schema:
type: string
example: 'event: message\ndata: {"job_id":"cfccdd6e-956e-4484-8cc2-a610db26bad9","status":"complete","completed_items":100,"total_items":100}\n\n'
'404':
description: The provided export job ID does not exist.
/storefront/redirects/imex/import/{uuid}/events:
parameters:
- $ref: '#/components/parameters/AcceptEventStream'
- $ref: '#/components/parameters/ImportExportIdParam'
get:
tags:
- Import-Export
summary: BigCommerce Open Redirect Import Event Stream
description: Opens an event stream to receive live updates from an import job.
operationId: getRedirectImportEvents
responses:
'200':
description: Stream of import events. The `data` attribute is stringified JSON.
content:
text/event-stream:
schema:
type: string
example: 'event: message\ndata: {{"job_id":"a4abaf59-9c25-4f37-a09d-66e6054229a1","status":"complete","completed_items":100,"failed_items":100,"total_items":93,"errors":[]}\n\n'
'404':
description: The provided import job ID does not exist.
/storefront/redirects/imex/export/{uuid}/download:
parameters:
- $ref: '#/components/parameters/ContentTypeCsv'
- $ref: '#/components/parameters/ImportExportIdParam'
get:
tags:
- Import-Export
summary: BigCommerce Download Redirect Export
description: Downloads the CSV file containing the results of an export job.
operationId: getRedirectExportDownload
responses:
'200':
description: The exported Redirects in CSV format
content:
text/csv:
schema:
type: string
format: binary
example: 'Domain,Old Path,Manual URL/Path,Dynamic Target Type,Dynamic Target ID
store.example.com,/old-path,/redirect-target,,
'
'404':
description: The requested export download does not exist.
components:
parameters:
ContentTypeCsv:
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: text/csv
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
AcceptEventStream:
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: text/event-stream
ImportExportIdParam:
name: uuid
description: The import-export job identifier.
in: path
required: true
schema:
type: string
format: uuid
ContentTypeFormData:
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: multipart/form-data
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:
301RedirectImportExportJobRead:
type: object
description: Full detail of a Redirect Import-Export job.
properties:
id:
type: string
format: uuid
description: The Import-Export job ID.
type:
$ref: '#/components/schemas/ImportExportJobType'
status:
$ref: '#/components/schemas/ImportExportJobStatus'
completed_items:
type: integer
description: The number of items that were successfully imported or exported.
failed_items:
type: integer
description: The number of items that were not successfully imported or exported.
total_items:
type: integer
description: The number of items in the import or export job.
errors:
$ref: '#/components/schemas/ImportErrors'
created_at:
type: string
format: date-time
description: The date-time that the import-export job was created, formatted as an [RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.
example: '2022-01-04T04:15:50.000Z'
completed_at:
type: string
format: date-time
description: The date-time that the import-export job was completed, formatted as an [RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.
example: '2022-01-04T04:15:50.000Z'
ImportExportJobStatus:
type: string
enum:
- new
- working
- complete
- aborted
- failed
ImportExportJobType:
type: string
enum:
- import
- export
MetaPaginationObject:
type: object
properties:
pagination:
type: object
properties:
total:
minimum: 0
type: integer
example: 246
count:
minimum: 0
type: integer
example: 5
per_page:
minimum: 0
type: integer
example: 5
current_page:
minimum: 1
type: integer
example: 1
total_pages:
minimum: 0
type: integer
example: 50
links:
type: object
properties:
next:
type: string
example: ?limit=5&page=2
current:
type: string
example: ?limit=5&page=1
ImportErrors:
type: array
items:
type: object
description: Detail of an error that occurred during an import job.
properties:
row:
type: integer
description: The row in the import CSV where the error occurred.
message:
type: string
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