openapi: 3.0.1
info:
title: Cart Actions Endpoints Catalog Connector Jobs API
description: fabric's **Cart API** lets you add, update, and remove items from your Storefront cart, either as a guest user or as a logged-in user. It also provides functionality to merge carts when you switch from guest user to logged-in user, and apply coupons and other attributes (for example, gift wrapping) to the line items. Additionally, the API supports more advanced tasks such as using multiple carts within a B2B organization, sharing carts, and supporting a unified cart experience for multi-region and multi-brand businesses.<p>The Cart API provides high performance, scalability, multi-tenancy, and configurability to the end-to-end order processing actions that start from the item being added to the cart; through the pre-checkout stage that includes billing, shipping, and payment details; to the checkout stage where the order is processed and confirmed by fabric's Order Management System (OMS)
contact:
name: Cart Support
email: support.cnc@fabric.inc
license:
name: fabric API License
url: https://fabric.inc/api-license
version: 3.0.0
servers:
- url: https://api.fabric.inc/v3
security:
- bearerAuth: []
tags:
- name: Catalog Connector Jobs
description: Export data from the Catalog Connector and retrieve the status of previously processed files.
paths:
/catalog-connector-jobs/actions/export:
post:
tags:
- Catalog Connector Jobs
summary: Export Products
description: "Use this endpoint to start an internal job to export products from Catalog Connector. \nSpecify the `formatType` query parameter to export data in either CSV or JSONL format. In the request body, provide the `ids` of all products to be exported, the product type, and the locale.\n"
operationId: exportProductsJob
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricRequestId'
requestBody:
$ref: '#/components/requestBodies/exportIDJobRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/jobIdResponse'
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestId'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/notAuthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internalServerError'
/catalog-connector-jobs:
get:
tags:
- Catalog Connector Jobs
summary: Retrieve Jobs
description: "Use this endpoint to retrieve a paginated list of import and export jobs related to Catalog Connector.\nThe following constraints apply when using the query parameters:\n - The query parameter job `ids` can't be combined with any other query parameters.\n - The query parameter `inputFileIds` can only be combined with the query parameter `lastJobOnly`. \n - Pagination isn't supported when `ids` or `inputFileIds` is specified.\n"
operationId: getJobs
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricRequestId'
- $ref: '#/components/parameters/ids'
- $ref: '#/components/parameters/productFileType'
- $ref: '#/components/parameters/inputFileIds'
- $ref: '#/components/parameters/lastJobOnly'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/limit'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/productJob'
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestId'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/notAuthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internalServerError'
/catalog-connector-jobs/search:
post:
tags:
- Catalog Connector Jobs
summary: Search Jobs
description: Get a paginated list of jobs related to products and collections by specifying the request body. You need to specify the criteria for the search such as job `id`, `type`, `status`, `collectionId`, or `inputFileId`.
operationId: getJobsBySearchCriteria
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricRequestId'
requestBody:
$ref: '#/components/requestBodies/jobSearchRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/productJob'
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestId'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/notAuthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internalServerError'
components:
schemas:
job:
type: object
description: The details of the import or export job.
properties:
id:
type: string
description: The 24-character system-generated file ID created using the [Create a File](/v3/api-reference/catalog-connector/files/create-file) endpoint.
example: 877f1f77bcf86cd799439087
inputFileId:
type: string
example: 327f1f77bcf86cd799439045
description: The IDs of the files to be processed as part of the job.
outputFiles:
type: array
description: The IDs of the processed files. The output files include success files, error files, and more.
items:
type: string
description: The IDs of the processed files. The output files include success files, error files, and more.
example: 507f1f77bcf86cd7994390163, 967f1f77bcf86cd799439058
errorFiles:
type: array
description: The IDs of the processed files. The output files include success files, error files, and more.
items:
type: string
description: A 24-character system-generated IDs of the error files. The error files list products that couldn't be processed through the job.
example: 887f1f77bcf86cd799439011, 997f1f77bcf86cd799439074
progressTracker:
type: object
properties:
updatedAt:
type: string
description: The time when the tracker was last updated, in UTC format.
example: '2023-02-14T22:10:30.618Z'
totalCount:
type: integer
format: int32
description: The total number of records to be processed through the job.
example: 100000
processedCount:
type: integer
format: int32
description: The total number of records processed.
example: 40000
errorCount:
type: integer
format: int32
description: Total number of records with error.
example: 10
status:
type: string
description: The job status.
enum:
- IN_PROGRESS
- COMPLETED
- FAILED
example: COMPLETED
statusMessage:
description: A brief message corresponding to the job `status`.
type: string
example: 100% completed
additionalDetails:
type: object
properties:
itemsCreated:
type: integer
format: int32
description: The number of items created during the import process. Only applicable when job `type` is `PRODUCT_IMPORT`.
example: 10
itemsUpdated:
type: integer
format: int32
description: The number of items updated during the import process. Only applicable when job `type` is `PRODUCT_IMPORT`.
example: 10
createdAt:
type: string
description: The time of job creation, in UTC format.
example: '2021-09-14T22:10:30.618Z'
completedAt:
type: string
description: The time of job completion, in UTC format.
example: '2021-09-14T22:10:30.618Z'
updatedBy:
type: string
description: The email of the user who last updated the job.
example: test@email.com
updatedAt:
type: string
description: The time when the job was last updated, in UTC format.
example: '2021-09-14T22:10:30.618Z'
productJob:
description: The details of the job.
type: object
properties:
data:
type: array
items:
allOf:
- $ref: '#/components/schemas/job'
type: object
properties:
type:
$ref: '#/components/schemas/productFileJobTypes'
offset:
description: 'The number of records to skip before returning records.
For example, when the offset is 20 and limit is 10, the system returns the records from 21 to 30.'
type: integer
format: int32
default: 0
example: 5
limit:
description: The maximum number of records per page.
type: integer
format: int32
default: 10
example: 10
count:
description: The total number of records.
type: integer
format: int32
example: 100
productFileJobTypes:
type: string
enum:
- CATALOG_CONN_ITEM_VARIANT_IMPORT
- CATALOG_CONN_ITEM_VARIANT_EXPORT
- CATALOG_CONN_BUNDLE_IMPORT
- CATALOG_CONN_BUNDLE_EXPORT
description: Specify the type of operation or job performed by uploading the file.
example: CATALOG_CONN_ITEM_VARIANT_IMPORT
productAsyncJobTypes:
type: string
enum:
- CATALOG_CONN_ITEM_VARIANT_EXPORT
- CATALOG_CONN_BUNDLE_EXPORT
description: The supported job types.
example: CATALOG_CONN_ITEM_VARIANT_EXPORT
containsStringSearchOperation:
type: object
description: An operation used to define string search.
required:
- op
- value
properties:
op:
type: string
description: Search operation that can be performed on a `string` type.
example: CONTAINS
enum:
- CONTAINS
value:
$ref: '#/components/schemas/stringSchema'
jobIdResponse:
type: object
description: The job ID.
properties:
jobId:
type: string
description: A 24-character system-generated job ID.
example: 877f1f77bcf86cd799439087
id:
type: string
example: 5f7329dfd5288b0011332366
description: A 24-character system-generated ID.
datetimeOperation:
type: object
description: The search criteria based on date-time.
properties:
op:
type: string
description: The type of search operation.
example: GTE
enum:
- EQUALS
- LTE
- GTE
- LT
- GT
value:
type: string
description: The timestamp to be searched, in UTC format.
example: '2021-09-14T22:10:30.618Z'
genericError:
type: object
description: The details of the error.
properties:
message:
type: string
description: A placeholder error message for all the 4xx, 5xx errors
example: Request is invalid
type:
type: string
description: A placeholder error type for all the 4xx, 5xx errors
example: Bad request
errors:
type: array
items:
type: object
properties:
type:
type: string
description: The error type.
example: CLIENT_ERROR
message:
type: string
description: The error message corresponding to the `type`.
example: Invalid request. Unable to find/create product
datetimeRangeOperation:
type: object
description: The search criteria based on date range.
properties:
op:
type: string
description: The type of search operation.
example: RANGE
enum:
- RANGE
fromValue:
type: string
description: The start date for searching, in UTC format.
example: '2022-09-14T22:10:30.618Z'
toValue:
type: string
description: The end date for searching, in UTC format.
example: '2023-04-14T22:10:30.618Z'
stringSchema:
type: string
nullable: true
description: Represents a string schema.
example: blue
stringSearchWithNullableOperation:
type: object
description: String search
anyOf:
- $ref: '#/components/schemas/simpleMultiStringWithNullableSearchOperation'
- $ref: '#/components/schemas/containsStringSearchOperation'
jobSearchRequestMatch:
minProperties: 1
additionalProperties: false
description: Search criteria to match jobs.
type: object
properties:
id:
description: job id search
$ref: '#/components/schemas/simpleMultiIdSearchOperation'
inputFileId:
description: Search based on input file ID
$ref: '#/components/schemas/simpleMultiIdSearchOperation'
name:
description: Search based on job name
$ref: '#/components/schemas/stringSearchWithNullableOperation'
keyword:
description: Search based on either job name or job ID
anyOf:
- $ref: '#/components/schemas/containsStringSearchOperation'
- $ref: '#/components/schemas/simpleMultiStringSearchOperation'
type:
description: Search based on job type
$ref: '#/components/schemas/multiJobType'
status:
description: Search based on job status
$ref: '#/components/schemas/multiJobStatuses'
createdAt:
description: Search based on job creation time
$ref: '#/components/schemas/datetimeSearchOperation'
completedAt:
description: Search based on job completion Time
$ref: '#/components/schemas/datetimeSearchOperation'
formatTypes:
type: string
enum:
- csv
- jsonl
description: Specify the file format used to upload to Catalog Connector.
example: jsonl
datetimeSearchOperation:
type: object
description: Date-time search
anyOf:
- $ref: '#/components/schemas/datetimeRangeOperation'
- $ref: '#/components/schemas/datetimeInOperation'
- $ref: '#/components/schemas/datetimeOperation'
multiJobStatuses:
type: object
required:
- op
- value
description: 'Search jobs using multiple job types.
For example, `COMPLETED'' or ''SCHEDULED`.'
properties:
op:
type: string
description: Operations that can be performed on a `string` type.
example: IN
enum:
- IN
value:
type: array
items:
$ref: '#/components/schemas/jobStatuses'
multiJobType:
type: object
description: 'Search jobs using multiple job types.
For example, `ITEM_VARIANT_IMPORT, BUNDLE_EXPORT`.'
required:
- op
- value
properties:
op:
type: string
description: Operations that can be performed on a `string` type.
example: IN
enum:
- IN
value:
type: array
items:
$ref: '#/components/schemas/productFileJobTypes'
locale:
type: string
description: 'The language code, which is a combination of language (ISO 639 format) and country (ISO 3166 format).
The default value is `en-US`.
'
example: en-US
jobStatuses:
type: string
enum:
- SCHEDULED
- COMPLETED_PARTIALLY
- IN_PROGRESS
- COMPLETED
- FAILED
- UPDATING_SEARCH_INDEX
- CANCELLATION_IN_PROGRESS
- CANCELLED
description: Job status
example: COMPLETED
simpleMultiIdSearchOperation:
type: object
description: A simple multi-string search operation.
required:
- op
- value
properties:
op:
type: string
description: Operations that can be performed on a `string` type.
example: IN
enum:
- IN
value:
type: array
items:
$ref: '#/components/schemas/id'
simpleMultiStringSearchOperation:
type: object
description: Simple multi-string search.
required:
- op
- value
properties:
op:
type: string
description: Operations that can be performed on a `string` type.
example: IN
enum:
- IN
value:
type: array
items:
$ref: '#/components/schemas/stringSchema'
datetimeInOperation:
type: object
description: The search criteria based on date-time using the IN condition.
properties:
op:
type: string
description: The type of search operation.
example: IN
enum:
- IN
value:
type: array
items:
type: string
example:
- 2023-01-14 22:10:30.618000+00:00
- 2023-05-14 22:10:30.618000+00:00
description: The timestamp to search.
simpleMultiStringWithNullableSearchOperation:
type: object
description: Simple multi-string search.
required:
- op
- value
properties:
op:
type: string
description: Operations that can be performed on a `string` type.
example: IN
enum:
- IN
value:
type: array
items:
$ref: '#/components/schemas/stringSchema'
responses:
internalServerError:
description: Internal server error
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/genericError'
example:
type: SERVER_ERROR
message: Internal Server Error
forbidden:
description: The user isn't allowed to perform this action.
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/genericError'
example:
type: REQUEST_DENIED
message: User does not have the required permission
badRequest:
description: Request is invalid or malformed
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/genericError'
notAuthorized:
description: The requester is unauthorized.
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/genericError'
example:
type: UNAUTHORIZED_ERROR
message: Requester is unauthorized
parameters:
lastJobOnly:
in: query
name: lastJobOnly
description: A flag indicating whether the response should be based only on the last job. Set it to `true` to show response based on the last job and `false` to include response based on all jobs that meet the criteria. This is only applicable with `type` and `inputFileIds`.
schema:
type: boolean
example: true
xFabricTenantId:
in: header
name: x-fabric-tenant-id
schema:
type: string
required: true
example: 5f328bf0b5f328bf0b5f328b
description: A header retrieved from your [Copilot Account Details](/v3/platform/settings/account-details/getting-the-account-id) that's used by the API to identify the tenant making the request. Tenant ID must be included in the authentication header for API requests to access any of fabric’s endpoints.
productFileType:
in: query
name: type
schema:
$ref: '#/components/schemas/productFileJobTypes'
description: Specify the type of operation or job performed when the file was uploaded.
inputFileIds:
in: query
name: inputFileIds
description: The file IDs specified in the request. You can specify up to 15 file IDs separated by commas. - This parameter can only be combined with the query parameter `lastJobOnly`. - Pagination isn't supported when this is specified.
schema:
type: string
example: 87328bf0b5f328bf0b5f328b, 9f328bf0b5f328bf0b5f3258
xFabricRequestId:
in: header
name: x-fabric-request-id
description: Unique request ID
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
required: false
ids:
in: query
name: ids
description: "The 24-character system-generated file ID created using the [Create a File](/v3/api-reference/catalog-connector/files/create-file) endpoint.\n\nDepending on the type of IDs, the array represents the file IDs or job IDs. Specify up to 15 IDs separated by commas. Note the following limitations of using this parameter:\n - This parameter can't be combined with any other parameters. \n - Pagination isn't supported when this parameter is specified.\n"
schema:
type: string
example: 5f328bf0b5f328bf0b5f328b, 1e328bf0b5f328bf0b5f3287
offset:
in: query
name: offset
description: The number of records to skip before returning records. For example, with an offset of 20 and limit of 10, the system returns records from 21 to 30.
schema:
type: integer
format: int32
default: 0
example: 2
required: false
limit:
in: query
name: limit
description: The maximum number of records per page.
schema:
type: integer
format: int32
default: 10
example: 20
requestBodies:
exportIDJobRequest:
content:
application/json:
schema:
type: object
additionalProperties: false
description: A sample request to export data.
required:
- ids
- locale
- type
properties:
ids:
type: array
minItems: 1
description: The product type IDs that must be exported.
items:
type: string
description: The product type IDs that must be exported.
example:
- 5f328bf0b5f328bf0b5f328b
- 22328bf0b5f328bf0b5f3287
formatType:
$ref: '#/components/schemas/formatTypes'
locale:
$ref: '#/components/schemas/locale'
type:
$ref: '#/components/schemas/productAsyncJobTypes'
jobSearchRequest:
content:
application/json:
schema:
type: object
required:
- match
description: Request for a job search.
properties:
sort:
type: string
description: Sorting criteria. Sorting is supported on `id`, `type`, `status`, `completedAt`, and `createdAt`. `-` refers to descending while `+` refers to ascending order.
example: +id,-type
match:
$ref: '#/components/schemas/jobSearchRequestMatch'
offset:
description: 'Number of records to skip before returning records.
For example, `offset=20, limit=10` returns records 21-30.'
type: integer
format: int32
default: 0
example: 2
limit:
description: Maximum number of records per page.
type: integer
format: int32
default: 10
example: 10
headers:
xFabricRequestId:
schema:
type: string
required: false
example: 263e731c-45c8-11ed-b878-0242ac120002
description: Unique request ID
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'This is the authorization token used to authenticate the request. You must pass the access token generated from the system app. For more information, see the [Making your first API request](/v3/api-reference/getting-started/getting-started-with-fabric-apis#procedure) section.
'