openapi: 3.0.0
x-mint:
mcp:
enabled: true
info:
description: >-
fabric's **Files** and **Jobs** APIs support bulk import and export of
items, attributes, and bundles. To begin with importing, download the
appropriate template for the specific `type` of import. A standardized
template ensures consistency in data structure and formatting. It also helps
enforce data validation rules to ensure imported data meets the specified
criteria and reduces the chance of incorrect and inaccurate information.
Once you have completed filling out the import details in the template, add
the file name and `type` in the request body of the `POST /files/product`
endpoint. The response will provide you with the URL where you can upload
the file for importing. After successfully importing the file, you can use
the job exports endpoints to export the imported products and attributes
based on specified criteria.
title: Products - Files and Jobs
version: 3.0.0
x-audience: external-public
contact:
email: support@fabric.inc
name: Product team
license:
name: fabric API License
url: https://fabric.inc/api-license
termsOfService: https://fabric.inc/terms-of-use
externalDocs:
description: Find out more about Products (previously called PIM)
url: https://developer.fabric.inc/docs/products-overview
servers:
- url: https://api.fabric.inc/v3
description: Production URL
tags:
- name: Files
description: >-
Files endpoints interact with the file object, which is associated with
(and points to) a job.
- name: Jobs
description: >-
Bulk import of attributes must be in a standardized format. This endpoint
gets the template required to bulk import attributes.
paths:
/product-templates/actions/generate:
post:
tags:
- Files
summary: Generate Import Template
description: >-
Bulk import must be in a standardized format. Using this endpoint, you
can generate the template required to bulk import attribute, category,
collection, item, and/or bundle.
operationId: generateProductTemplate
parameters:
- $ref: '#/components/parameters/x-fabric-tenant-id'
- $ref: '#/components/parameters/x-fabric-request-id'
requestBody:
$ref: '#/components/requestBodies/generateTemplateRequest'
responses:
'200':
description: OK
content:
text/csv: {}
headers:
x-fabric-request-id:
$ref: '#/components/headers/x-fabric-request-id-header'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/notAuthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFoundError'
'500':
$ref: '#/components/responses/internalServerError'
/product-files:
post:
tags:
- Files
summary: Create File Object and Get File Upload Location
description: >-
This endpoint creates a file object by specifying the import file's
`type`, `name`, and `locale` in the request body. The response will
include the URL location to upload the file.
operationId: createFile
parameters:
- $ref: '#/components/parameters/x-fabric-tenant-id'
- $ref: '#/components/parameters/x-fabric-request-id'
requestBody:
$ref: '#/components/requestBodies/createFileRequest'
responses:
'200':
description: Create file success response
content:
application/json:
schema:
$ref: '#/components/schemas/file'
headers:
x-fabric-request-id:
$ref: '#/components/headers/x-fabric-request-id-header'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/notAuthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internalServerError'
get:
tags:
- Files
summary: Get Available Files
description: >-
Get files available for a merchant. This endpoint can be used to search
for files using file names or file IDs. **Note**: Query parameter `ids`
can't be combined with any other query parameters and pagination isn't
supported when `ids` query is used.
operationId: getFiles
parameters:
- $ref: '#/components/parameters/x-fabric-tenant-id'
- $ref: '#/components/parameters/x-fabric-request-id'
- $ref: '#/components/parameters/ids'
- $ref: '#/components/parameters/fileName'
- $ref: '#/components/parameters/fileType'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/sortBy'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/getFilesResponse'
headers:
x-fabric-request-id:
$ref: '#/components/headers/x-fabric-request-id-header'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/notAuthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internalServerError'
/product-files/actions/download:
get:
tags:
- Files
summary: Download a File by ID
description: >-
Use this endpoint to get a download link for imported file, which you
can use to review or update the file . **Note**: The link is valid only
for five minutes.
operationId: downloadFile
parameters:
- $ref: '#/components/parameters/x-fabric-tenant-id'
- $ref: '#/components/parameters/x-fabric-request-id'
- $ref: '#/components/parameters/fileId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/fileDownloadResponse'
headers:
x-fabric-request-id:
$ref: '#/components/headers/x-fabric-request-id-header'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/notAuthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFoundError'
'500':
$ref: '#/components/responses/internalServerError'
/product-jobs/actions/export:
post:
tags:
- Jobs
summary: Initiate Job to Export Items and Variants
description: Use this endpoint to trigger a job to export items and variants, by ids.
operationId: exportProductsJob
parameters:
- $ref: '#/components/parameters/x-fabric-tenant-id'
- $ref: '#/components/parameters/x-fabric-request-id'
requestBody:
$ref: '#/components/requestBodies/exportBasedOnIDJobRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/jobIdResponse'
headers:
x-fabric-request-id:
$ref: '#/components/headers/x-fabric-request-id-header'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/notAuthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internalServerError'
/product-jobs/actions/filter-export:
post:
tags:
- Jobs
summary: Initiate Job to Export Items and Variants
description: >-
Use this endpoint to trigger a job to export items and variants based on
the specified filter conditions.
operationId: exportProductsJobFilter
parameters:
- $ref: '#/components/parameters/x-fabric-tenant-id'
- $ref: '#/components/parameters/x-fabric-request-id'
requestBody:
$ref: '#/components/requestBodies/exportJobRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/jobIdResponse'
headers:
x-fabric-request-id:
$ref: '#/components/headers/x-fabric-request-id-header'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/notAuthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internalServerError'
/product-jobs:
get:
tags:
- Jobs
summary: Get Jobs Related to Products
description: >-
Get a paginated list of jobs related to products by specifying the query
parameters such as job `ids`, `type`. You can refine the results by
specifying `offset` and `limit`. **Note**:
1. Query parameter
`ids` can't be combined with the rest of the query parameters and when
it's specified, pagination isn't supported.
2. Query parameter
`inputFileIds` supports up to 15 comma-separated file IDs and it can be
combined only with the query parameter `lastJobOnly`. Pagination isn't
supported when this parameter is used.
operationId: getJobs
parameters:
- $ref: '#/components/parameters/x-fabric-tenant-id'
- $ref: '#/components/parameters/x-fabric-request-id'
- $ref: '#/components/parameters/ids'
- $ref: '#/components/parameters/type'
- $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/jobs'
headers:
x-fabric-request-id:
$ref: '#/components/headers/x-fabric-request-id-header'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/notAuthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internalServerError'
/product-jobs/search:
post:
tags:
- 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`,
`inputFileId`.
operationId: getJobsBySearchCriteria
parameters:
- $ref: '#/components/parameters/x-fabric-tenant-id'
- $ref: '#/components/parameters/x-fabric-request-id'
requestBody:
$ref: '#/components/requestBodies/jobSearchRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/jobs'
headers:
x-fabric-request-id:
$ref: '#/components/headers/x-fabric-request-id-header'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/notAuthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internalServerError'
/product-jobs/{id}/actions/cancel:
post:
tags:
- Jobs
summary: Cancel Background Jobs Using Job IDs
description: >-
Cancel any in progress or scheduled background job by providing the job
ID. Currently only supports item and variant import jobs.
operationId: cancelJobById
parameters:
- $ref: '#/components/parameters/x-fabric-tenant-id'
- $ref: '#/components/parameters/x-fabric-request-id'
- $ref: '#/components/parameters/jobIdPathParameter'
responses:
'200':
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/headers/x-fabric-request-id-header'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/notAuthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFoundError'
'500':
$ref: '#/components/responses/internalServerError'
components:
parameters:
localeParameter:
name: locale
in: query
example: en_US
description: Locale name
schema:
type: string
required: false
ids:
in: query
name: ids
description: >-
Supports up to 15 comma-separated job IDs. **Note**:
1. This
parameter can't be combined with any other query parameter.
2.
Pagination isn't supported when this parameter is used.
schema:
type: string
example: 5f328bf0b5f328bf0b5f328b, 1e328bf0b5f328bf0b5f3287
jobIdPathParameter:
in: path
name: id
schema:
type: string
required: true
example: 64184766610c0e32a86d8758
description: 24-character system-generated job ID
fileId:
in: query
name: fileId
description: 24-character system-generated file ID
schema:
type: string
example: 5f328bf0b5f328bf0b5f328b
required: true
fileType:
in: query
name: type
schema:
$ref: '#/components/schemas/fileJobTypes'
description: File types
type:
in: query
name: type
schema:
$ref: '#/components/schemas/jobTypes'
description: Job types
fileName:
in: query
name: fileName
schema:
type: string
description: File name
example: bulk_import_123345677788999.csv
inputFileIds:
in: query
name: inputFileIds
allowReserved: true
description: >-
Supports up to 15 comma-separated file IDs. **Note**:
1. This can
only be combined with the query parameter `lastJobOnly`.
2.
Pagination isn't supported when this parameter is used.
schema:
type: string
example: 87328bf0b5f328bf0b5f328b, 9f328bf0b5f328bf0b5f3258
lastJobOnly:
in: query
name: lastJobOnly
description: >-
true: The last job that meets the query parameters
false: Not
necessarily the last job **Note**: Only applicable with `type` and
`inputFileIds`.
schema:
type: boolean
example: true
limit:
in: query
name: limit
description: Maximum number of records per page
schema:
type: integer
format: int32
default: 10
example: 20
offset:
in: query
name: offset
description: >-
Number of records to skip before returning records. For example,
`offset=20, limit=10` returns records 21-30.
schema:
type: integer
format: int32
default: 0
example: 2
required: false
sortBy:
in: query
name: sort
description: >-
Sorting criteria. Supported values are `updatedAt` and `name`. **Note**:
`-` refers to descending and `+` refers to ascending order
schema:
type: string
example: +name,-updatedAt
required: false
x-fabric-tenant-id:
name: x-fabric-tenant-id
in: header
description: >-
A header used by fabric to identify the tenant making the request. You
must include tenant id in the authentication header for an API request
to access any of fabric’s endpoints. You can retrieve the tenant id ,
which is also called account id, from
[Copilot](/v3/platform/settings/account-details/getting-the-account-id).
This header is required.
schema:
type: string
example: 517fa9dfd42d8b00g1o3k312
x-fabric-request-id:
name: x-fabric-request-id
in: header
description: Unique request ID
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
required: false
securitySchemes:
authorization:
type: http
scheme: bearer
bearerFormat: JWT
description: S2S access token (JWT) from fabric Identity service (during login)
requestBodies:
exportBasedOnIDJobRequest:
content:
application/json:
schema:
type: object
description: Export based on ID
anyOf:
- $ref: '#/components/schemas/exportIDJobRequest'
- $ref: '#/components/schemas/productExportJobRequest'
examples:
AttributeExport:
value:
type: ATTRIBUTE
ids:
- 5f328bf0b5f328bf0b5f328b
locale: en-US
ProductExport:
value:
type: ITEM_VARIANT
ids:
- 22328bf0b5f328bf0b5f3287
statuses: LIVE,DRAFT
locale: en-US
exportJobRequest:
content:
application/json:
schema:
description: >-
Export job request based on the filter conditions applied for
attributes, category, collections, items or bundles.
anyOf:
- $ref: '#/components/schemas/exportAttributesByFiltersRequest'
- $ref: '#/components/schemas/exportFilteredProductsJobRequest'
- $ref: '#/components/schemas/exportSearchCollectionRequest'
- $ref: '#/components/schemas/exportSearchCategoryRequest'
examples:
AttributeFilter:
value:
type: ATTRIBUTE
match:
name:
locale:
- en-US
op: CONTAINS
value: size
target:
op: EQUALS
value: CATEGORY
isMandatory:
op: EQUALS
value: true
CategoryFilter:
value:
type: CATEGORY
match:
name:
locale:
- en-US
op: CONTAINS
value: shoes
attribute:
- id: 5f328bf0b5f328bf0b5f328b
value:
- op: EQUALS
value: thirty
isLeaf:
op: EQUALS
value: true
CollectionsFilter:
value:
type: COLLECTION
match:
name:
locale:
- en-US
op: CONTAINS
value: Flash Sale
categoryIdsIncluded:
op: EQUALS
value: 5f328bf0b5f328bf0b5f328b
ProductsFilter:
value:
type: PRODUCT
match:
sku:
op: EQUALS
value: FCP_SAMPLE_SKU
status:
op: EQUALS
value: LIVE
generateTemplateRequest:
content:
application/json:
schema:
description: Template request
anyOf:
- $ref: '#/components/schemas/itemFileTemplateRequest'
- $ref: '#/components/schemas/fileTemplateRequest'
examples:
AttributeTemplate:
value:
type: ATTRIBUTE
ItemTemplate:
value:
type: ITEM
categoryId: 648014741adc8a9de14e1a68
locale: en-US
createFileRequest:
content:
application/json:
schema:
type: object
additionalProperties: false
description: Request for file creation
required:
- type
- name
properties:
type:
$ref: '#/components/schemas/fileJobTypes'
name:
type: string
description: File name
example: bulk_import_123345677788999.csv
locale:
$ref: '#/components/schemas/locale'
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
responses:
notAuthorized:
description: Requester is unauthorized
headers:
x-fabric-request-id:
$ref: '#/components/headers/x-fabric-request-id-header'
content:
application/json:
schema:
$ref: '#/components/schemas/genericError'
example:
type: UNAUTHORIZED_ERROR
message: Requester is unauthorized
forbidden:
description: User isn't allowed to perform the action
headers:
x-fabric-request-id:
$ref: '#/components/headers/x-fabric-request-id-header'
content:
application/json:
schema:
$ref: '#/components/schemas/genericError'
example:
type: REQUEST_DENIED
message: User doesn't have the required permission
notFoundError:
description: Requested entity isn't found
headers:
x-fabric-request-id:
$ref: '#/components/headers/x-fabric-request-id-header'
content:
application/json:
schema:
$ref: '#/components/schemas/genericError'
example:
type: NOT_FOUND
message: Resource not found
badRequest:
description: Request is invalid or malformed
headers:
x-fabric-request-id:
$ref: '#/components/headers/x-fabric-request-id-header'
content:
application/json:
schema:
$ref: '#/components/schemas/genericError'
internalServerError:
description: Internal server error
headers:
x-fabric-request-id:
$ref: '#/components/headers/x-fabric-request-id-header'
content:
application/json:
schema:
$ref: '#/components/schemas/genericError'
example:
type: SERVER_ERROR
message: Internal Server Error
headers:
x-fabric-request-id-header:
description: Unique request ID
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
schemas:
singleProductType:
type: object
description: Search products using single product type - variant, item, or bundle
required:
- op
- value
properties:
op:
type: string
description: Operations that can be performed on a `string` type.
example: EQUALS
enum:
- EQUALS
value:
$ref: '#/components/schemas/productType'
multiProductType:
type: object
description: Search products using multiple product types - variant, item, and bundle
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/productType'
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/jobTypes'
multiJobStatuses:
type: object
required:
- op
- value
description: >-
Search jobs using multiple job types. For example, `COMPLETED,
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'
fileDownloadResponse:
type: object
description: File download response
properties:
location:
type: string
description: File download URL
format: uri
example: >-
https://pim-v3-dev02-us-east-1-files.s3.us-east-1.amazonaws.com/local/ITEM_VARIANT_EXPORT/abc.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIARD6W3CJ53CEYXKIJ%252F20230317%252Fus-east-1%252Fs3%252Faws4_request&X-Amz-Date=20230317T171516Z&X-Amz-Expires=300&X-Amz-Signature=f7069f25d72ac10f2163a134550cd68658de7a23d9960dc61ebaa67c8f54eb77&X-Amz-SignedHeaders=host&x-id=GetObject
productAttributeValueInfo:
anyOf:
- $ref: '#/components/schemas/localizedStringSearchOperation'
- $ref: '#/components/schemas/booleanSearchOperation'
- $ref: '#/components/schemas/numberSearchOperation'
productAttributeValueSearch:
type: object
description: Search criteria - attribute
properties:
attributeId:
type: string
description: 24-character system-generated attribute ID
example: 507f1f77bcf86cd799439011
attributeValue:
type: array
items:
$ref: '#/components/schemas/productAttributeValueInfo'
productType:
type: string
enum:
- ITEM
- VARIANT
- BUNDLE
example: ITEM
description: Supported product types
file:
type: object
properties:
id:
type: string
description: 24-character system-generated file ID
example: 337f1f77bcf86cd799439011
type:
$ref: '#/components/schemas/fileJobTypes'
name:
type: string
description: File name to be uploaded to the generated URL
example: bulk_import_123345677788999.csv
locale:
$ref: '#/components/schemas/locale'
location:
type: string
description: S3 file location of the uploaded file.
example: >-
https://s3.console.aws.amazon.com/s3/buckets/greatwall-stg01-bulk-import-pim/bulk_import_123345677788999.csv
createdAt:
type: string
description: File creation time (UTC)
example: '2021-09-14T22:10:30.618Z'
updatedBy:
type: string
description: Email of user who last updated the file
example: test@email.com
updatedAt:
type: string
description: Time of last update to file (UTC)
example: '2021-09-14T22:10:30.618Z'
fileInGetFilesResponse:
type: object
description: File details
properties:
id:
type: string
description: 24-character system-generated file ID
example: 857f1f77bcf86cd799439054
type:
$ref: '#/components/schemas/fileJobTypes'
name:
type: string
description: File name to be uploaded to the generated URL
example: bulk_import_123345677788999.csv
locale:
$ref: '#/components/schemas/locale'
createdAt:
type: string
description: File creation time (UTC)
example: '2021-09-14T22:10:30.618Z'
updatedBy:
type: string
description: Email of user who last updated the file
example: test@email.com
updatedAt:
type: string
description: Time of last update to file (UTC)
example: '2021-09-14T22:10:30.618Z'
getFilesResponse:
type: object
description: File info with pagination metadata
properties:
data:
type: array
items:
$ref: '#/components/schemas/fileInGetFilesResponse'
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: 5
limit:
description: Maximum number of records per page
type: integer
format: int32
default: 10
example: 10
count:
description: Total number of records
type: integer
format: int32
example: 100
jobStatuses:
type: string
enum:
- SCHEDULED
- COMPLETED_PARTIALLY
- IN_PROGRESS
- COMPLETED
- FAILED
- UPDATING_SEARCH_INDEX
- CANCELLATION_IN_PROGRESS
- CANCELLED
description: Job status
example: COMPLETED
jobTypes:
oneOf:
- $ref: '#/components/schemas/pimJobTypes'
- $ref: '#/components/schemas/catalogConnectorJobTypes'
pimJobTypes:
type: string
enum:
- ITEM_VARIANT_EXPORT
- ITEM_VARIANT_IMPORT
- BUNDLE_EXPORT
- BUNDLE_IMPORT
- ATTRIBUTE_IMPORT
- ATTRIBUTE_EXPORT
- CATEGORY_IMPORT
- CATEGORY_EXPORT
- COLLECTION_IMPORT
- COLLECTION_EXPORT
- ATTRIBUTE_JOB
- PRODUCT_JOB
- CATEGORY_JOB
- COLLECTION_JOB
- PRODUCT_BULK_CATEGORY_UPDATE
- PRODUCT_DENORM_JOB
description: Supported job types
example: ITEM_VARIANT_EXPORT
fileJobTypes:
type: string
enum:
- ITEM_VARIANT_EXPORT
- ITEM_VARIANT_IMPORT
- BUNDLE_EXPORT
- BUNDLE_IMPORT
- ATTRIBUTE_IMPORT
- ATTRIBUTE_EXPORT
- CATEGORY_IMPORT
- CATEGORY_EXPORT
- COLLECTION_IMPORT
- COLLECTION_EXPORT
description: Supported job types
example: ITEM_VARIANT_EXPORT
catalogConnectorJobTypes:
type: string
enum:
- CATALOG_CONN_ITEM_VARIANT_IMPORT
- CATALOG_CONN_BUNDLE_IMPORT
- CATALOG_CONN_ITEM_VARIANT_EXPORT
- CATALOG_CONN_BUNDLE_EXPORT
description: Catalog Connector job types
example: CATALOG_CONN_ITEM_VARIANT_IMPORT
jobIdResponse:
type: object
description: Job ID for the exported job
properties:
jobId:
type: string
description: 24-character system-generated job ID
example: 877f1f77bcf86cd799439087
job:
type: object
description: Job details
properties:
id:
type: string
description: 24-character system-generated job ID
example: 877f1f77bcf86cd799439087
type:
$ref: '#/components/schemas/jobTypes'
inputFileId:
type: string
example: 327f1f77bcf86cd799439045
description: File ID that needs to be processed through the job
outputFiles:
type: array
items:
type: string
description: >-
Output file IDs. For import and export jobs, the output files show
the exported products (items, variant and/or bundle) based on the
job type.
example: 507f1f77bcf86cd7994390163, 967f1f77bcf86cd799439058
errorFiles:
type: array
items:
type: string
description: >-
File IDs that show error details of the products that couldn't be
imported or exported.
example: 887f1f77bcf86cd799439011, 997f1f77bcf86cd799439074
progressTracker:
type: object
properties:
updatedAt:
type: string
description: Time of last update to tracker (UTC)
example: '2023-02-14T22:10:30.618Z'
totalCount:
type: integer
format: int32
description: Total number of records to be processed through the job
example: 100000
processedCount:
type: integer
format: int32
description: Total number of records to be processed
example: 40000
errorCount:
type: integer
format: int32
description: Total number of errors
example: 10
status:
$ref: '#/components/schemas/jobStatuses'
statusMessage:
description: User-friendly message corresponding to the current job status
type: string
example: 100% completed
additionalDetails:
type: object
properties:
itemsCreated:
type: integer
format: int32
description: >-
Number of items created. Only applicable when the job `type` is
`ITEM_VARIANT_IMPORT`.
example: 10
itemsUpdated:
type: integer
format: int32
description: >-
Number of items updated. Only applicable when the job `type` is
`ITEM_VARIANT_IMPORT`.
example: 10
variantsCreated:
type: integer
format: int32
description: >-
Number of variants created. Only applicable when the job `type`
is `ITEM_VARIANT_IMPORT`.
example: 10
variantsUpdated:
type: integer
format: int32
description: >-
Number of variants updated. Only applicable when the job `type`
is `ITEM_VARIANT_IMPORT`.
example: 10
bundlesCreated:
type: integer
format: int32
description: >-
Number of bundles created. Only applicable when the job `type`
is `BUNDLE_IMPORT`.
example: 10
bundlesUpdated:
type: integer
format: int32
description: >-
Number of bundles updated. Only applicable when the job `type`
is `BUNDLE_IMPORT`.
example: 10
attributeCreated:
type: integer
format: int32
description: >-
Number of attributes created. Only applicable when the job
`type` is `ATTRIBUTE_IMPORT`.
example: 10
attributeUpdated:
type: integer
format: int32
description: >-
Number of attributes updated. Only applicable when the job
`type` is `ATTRIBUTE_IMPORT`.
example: 10
categoriesCreated:
type: integer
format: int32
description: >-
Number of categories created. Only applicable when the job
`type` - `CATEGORY_IMPORT`.
example: 10
categoriesUpdated:
type: integer
format: int32
description: >-
Number of categories updated. Only applicable when the job
`type` is `CATEGORY_IMPORT`.
example: 10
collectionCreated:
type: integer
format: int32
example: 5
description: >-
Number of collections created. Only applicable when the job
`type` is `COLLECTION_IMPORT`.
collectionUpdated:
type: integer
format: int32
description: >-
Number of collections updated. Only applicable when the job
`type` is `COLLECTION_IMPORT`.
example: 10
createdAt:
type: string
description: Time of job creation (UTC)
example: '2021-09-14T22:10:30.618Z'
completedAt:
type: string
description: Time of job completion (UTC)
example: '2021-09-14T22:10:30.618Z'
updatedBy:
type: string
description: Email of the user who last updated the job
example: test@email.com
updatedAt:
type: string
description: Time of last update to job (UTC)
example: '2021-09-14T22:10:30.618Z'
jobs:
description: Details of jobs
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/job'
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: 5
limit:
description: Maximum number of records per page
type: integer
format: int32
default: 10
example: 10
count:
description: Total number of records
type: integer
format: int32
example: 100
booleanSchema:
type: boolean
description: Sample boolean schema
example: true
stringSchema:
type: string
description: Sample string schema
example: blue
idSchema:
type: string
description: The schema id.
example: 5fc100f1dd0c5900750c04b1
doubleSchema:
type: number
format: double
description: Sample double schema
example: 1
genericError:
type: object
description: Error details
properties:
message:
type: string
description: Placeholder error message for all the 4xx, 5xx errors
example: Request is invalid
type:
type: string
description: Placeholder error type for all the 4xx, 5xx errors
example: Bad request
errors:
type: array
items:
type: object
properties:
type:
type: string
description: Error type
example: CLIENT_ERROR
message:
type: string
description: Error message
example: Invalid request. Unable to find/create product
datetimeSearchOperation:
type: object
description: Date-time search
anyOf:
- $ref: '#/components/schemas/datetimeRangeOperation'
- $ref: '#/components/schemas/datetimeInOperation'
- $ref: '#/components/schemas/datetimeOperation'
datetimeInOperation:
type: object
description: IN operation on date-time
required:
- op
- value
properties:
op:
type: string
description: >-
Operations that can be performed on a `number` type such as equals,
less than (LT), Greater than (GT), Less than or equal to (LTE),
Greater than or equal to (GTE), etc.
example: IN
enum:
- IN
value:
type: array
items:
type: string
description: Timestamp to be searched (UTC)
example: '2023-04-20T10:24:36.162Z'
datetimeOperation:
type: object
description: Date-time search
required:
- op
- value
properties:
op:
type: string
description: >-
Operations that can be performed on a `number` type such as equals,
less than (LT), Greater than (GT), Less than or equal to (LTE),
Greater than or equal to (GTE).
example: GTE
enum:
- EQUALS
- LTE
- GTE
- LT
- GT
value:
type: string
description: Timestamp to be searched (UTC)
example: '2023-04-20T10:24:36.162Z'
datetimeRangeOperation:
type: object
description: Date range search
required:
- op
- fromValue
- toValue
properties:
op:
type: string
description: Search operation performed on a date range
example: RANGE
enum:
- RANGE
fromValue:
type: string
description: Starting range (UTC)
example: '2022-04-20T10:24:36.162Z'
toValue:
type: string
description: Ending range (UTC)
example: '2023-04-20T10:24:36.162Z'
advancedStringSearchOperation:
type: object
description: Advanced string search
anyOf:
- $ref: '#/components/schemas/advancedMultiStringSearchOperation'
- $ref: '#/components/schemas/advancedSingleStringSearchOperation'
advancedSingleStringSearchOperation:
type: object
description: Advanced single-string search
required:
- op
- value
properties:
op:
type: string
description: Search operations that can be performed on a `string` type
example: EQUALS
enum:
- EQUALS
- CONTAINS
- NOT_EQUALS
value:
$ref: '#/components/schemas/stringSchema'
advancedMultiStringSearchOperation:
type: object
description: Advanced multi-string search
required:
- op
- value
properties:
op:
type: string
description: Search operations that can be performed on a `string` type
example: IN
enum:
- IN
- NOT_IN
value:
type: array
items:
$ref: '#/components/schemas/stringSchema'
numberSearchOperation:
type: object
description: Number search
anyOf:
- $ref: '#/components/schemas/singleNumberSearchOperation'
- $ref: '#/components/schemas/multiNumberSearchOperation'
singleNumberSearchOperation:
type: object
description: Single number search
required:
- op
- value
properties:
op:
type: string
description: >-
Search operations that can be performed on a `number` type such as
equals to, less than (LT), Greater than (GT), Less than or equal to
(LTE), Greater than or equal to (GTE), etc.
example: GTE
enum:
- EQUALS
- LTE
- GTE
- LT
- GT
value:
$ref: '#/components/schemas/doubleSchema'
multiNumberSearchOperation:
type: object
description: Multiple numbers search
required:
- op
- value
properties:
op:
type: string
description: In operation on a `number`
example: IN
enum:
- IN
value:
type: array
items:
$ref: '#/components/schemas/doubleSchema'
simpleStringSearchOperation:
type: object
description: Simple string search
anyOf:
- $ref: '#/components/schemas/simpleMultiStringSearchOperation'
- $ref: '#/components/schemas/simpleSingleStringSearchOperation'
simpleSingleStringSearchOperation:
type: object
description: Simple single string search
required:
- op
- value
properties:
op:
type: string
description: Search operations that can be performed on a `string` type
example: EQUALS
enum:
- EQUALS
value:
$ref: '#/components/schemas/stringSchema'
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'
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'
stringSearchWithNullableOperation:
type: object
description: String search
anyOf:
- $ref: '#/components/schemas/simpleMultiStringWithNullableSearchOperation'
- $ref: '#/components/schemas/containsStringSearchOperation'
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/idSchema'
stringSearchOperation:
type: object
description: String search
anyOf:
- $ref: '#/components/schemas/simpleMultiStringSearchOperation'
- $ref: '#/components/schemas/singleStringSearchOperation'
singleStringSearchOperation:
type: object
description: Single string search
required:
- op
- value
properties:
op:
type: string
description: Search operations that can be performed on a `string` type
example: EQUALS
enum:
- EQUALS
- CONTAINS
value:
$ref: '#/components/schemas/stringSchema'
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'
booleanSearchOperation:
type: object
description: Boolean search
required:
- op
- value
properties:
op:
type: string
description: Operations that can be performed on a `boolean` type
example: EQUALS
enum:
- EQUALS
value:
$ref: '#/components/schemas/booleanSchema'
singleSubType:
description: Searches for attribute of the specified `subType`
type: object
required:
- op
- value
properties:
op:
type: string
description: Operations that can be performed on a `string` type
example: EQUALS
enum:
- EQUALS
value:
$ref: '#/components/schemas/subTypeValue'
subTypeValue:
type: string
description: >-
A string in case of a `EQUALS` operation and a comma-separated string in
case of an `IN` operation
example: SINGLE
enum:
- SINGLE
- MULTIPLE
- SMALL_TEXT
- TEXT_AREA
- HTML
multiSubType:
description: Searches for attributes of the specified `subType`
type: object
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/subTypeValue'
singleType:
description: Export criteria - single type
type: object
required:
- op
- value
properties:
op:
type: string
description: Operations supported on a `string` type
example: EQUALS
enum:
- EQUALS
value:
$ref: '#/components/schemas/typeValue'
typeValue:
type: string
description: >-
A string in case of `EQUALS` operation and a comma- separated string in
case of an `IN` operation
example: TEXT
enum:
- TEXT
- NUMBER
- DATETIME
- BOOLEAN
- OPTIONS
- SERIAL
multiType:
description: Export criteria - multi-type
type: object
required:
- op
- value
properties:
op:
type: string
description: Operations supported on a `string` type
example: IN
enum:
- IN
value:
type: array
items:
$ref: '#/components/schemas/typeValue'
singleTarget:
type: object
description: Export criteria - single target
required:
- op
- value
properties:
op:
type: string
description: Operations supported on a `string` type.
example: EQUALS
enum:
- EQUALS
value:
$ref: '#/components/schemas/targetValue'
singleStatusSearchSchema:
type: object
description: List of attributes that match the search based on single status
required:
- op
- value
properties:
op:
type: string
description: Operations that can be performed on a single status type
example: EQUALS
enum:
- EQUALS
value:
$ref: '#/components/schemas/status'
targetValue:
type: string
description: >-
A string in case of `EQUALS` operation and a comma-separated string in
case of an `IN` operation
example: PRODUCT
enum:
- PRODUCT
- CATEGORY
multiTarget:
type: object
description: Export criteria - multiple targets
required:
- op
- value
properties:
op:
type: string
description: Operations performed on a `string` type
example: IN
enum:
- IN
value:
type: array
items:
$ref: '#/components/schemas/targetValue'
localizedStringSearchOperation:
allOf:
- $ref: '#/components/schemas/advancedStringSearchOperation'
type: object
properties:
locale:
$ref: '#/components/schemas/locale'
locale:
type: string
description: >-
If `isLocalizable` is true, the search is based on the localized name in
specified locales. If `isLocalizable` is false, the search is only based
on the non-localized names.
example: en-US
status:
type: string
description: Represents the current status of product
enum:
- DRAFT
- LIVE
example: LIVE
fileTemplateRequest:
type: object
additionalProperties: false
description: Template file for item or variant
required:
- type
properties:
type:
type: string
description: >-
Specify the type (category or collection or attribute) for which
template needs to be downloaded
enum:
- CATEGORY
- COLLECTION
- ATTRIBUTE
example: ATTRIBUTE
locale:
$ref: '#/components/schemas/locale'
itemFileTemplateRequest:
type: object
additionalProperties: false
description: Template file for item or variant
required:
- type
- categoryId
properties:
type:
type: string
description: >-
Specify the type, such as item or bundle, for which a template file
needs to be downloaded
enum:
- ITEM
- BUNDLE
example: ITEM
categoryId:
type: string
description: ID of leaf category where items must be imported
example: 507f1f77bcf86cd799439011
locale:
$ref: '#/components/schemas/locale'
attributeSearchOperation:
type: object
description: >-
Search for multiple attributes using a combination of `id` and `value`
pairs.
properties:
id:
type: string
description: 24-character system-generated attribute ID
example: 63a123070cf218e178efda30
value:
type: array
description: Attribute value
items:
$ref: '#/components/schemas/attributeValueObject'
attributeValueObject:
anyOf:
- $ref: '#/components/schemas/localizedStringSearchOperation'
- $ref: '#/components/schemas/booleanSearchOperation'
- $ref: '#/components/schemas/numberSearchOperation'
exportFilteredProductsJobRequest:
type: object
additionalProperties: false
description: Export based on applied filter conditions
required:
- match
- type
properties:
type:
type: string
enum:
- PRODUCT
description: >-
Type of entity to be exported, such as products. Products include
items, variants, and bundles.
example: PRODUCT
match:
description: Filter conditions based on which products will be exported
type: object
minProperties: 1
properties:
id:
$ref: '#/components/schemas/simpleStringSearchOperation'
sku:
$ref: '#/components/schemas/stringSearchOperation'
type:
anyOf:
- $ref: '#/components/schemas/singleProductType'
- $ref: '#/components/schemas/multiProductType'
categoryId:
type: array
description: 24-character system-generated category ID
items:
$ref: '#/components/schemas/simpleStringSearchOperation'
hasDraft:
$ref: '#/components/schemas/booleanSearchOperation'
hasLive:
$ref: '#/components/schemas/booleanSearchOperation'
status:
oneOf:
- $ref: '#/components/schemas/singleStatusSearchSchema'
properties:
description: >-
Searches based on multiple values. The values must be a
combination of `id` and boolean `value`.
type: array
items:
$ref: '#/components/schemas/productAttributeValueSearch'
variantIds:
$ref: '#/components/schemas/simpleStringSearchOperation'
bundleProductIds:
$ref: '#/components/schemas/simpleStringSearchOperation'
createdAt:
$ref: '#/components/schemas/datetimeSearchOperation'
updatedAt:
$ref: '#/components/schemas/datetimeSearchOperation'
createdBy:
$ref: '#/components/schemas/simpleStringSearchOperation'
exportAttributesByFiltersRequest:
type: object
additionalProperties: false
required:
- match
- type
properties:
type:
type: string
enum:
- ATTRIBUTE
description: Type of entity to be exported.
example: ATTRIBUTE
match:
description: Filter conditions to export attributes
type: object
minProperties: 1
properties:
id:
$ref: '#/components/schemas/simpleStringSearchOperation'
name:
allOf:
- $ref: '#/components/schemas/stringSearchOperation'
type: object
description: >-
Search criteria to find attributes. Append locale and name with
a `#` as a value.
properties:
locale:
type: array
description: >-
If `isLocalizable` is true, the search is based on the
localized name in the specified locales. If `isLocalizable`
is false, the search is only based on the non-localized
names.
items:
type: string
description: Locale
example: en_US
description:
$ref: '#/components/schemas/stringSearchOperation'
isLocalizable:
$ref: '#/components/schemas/booleanSearchOperation'
isMandatory:
$ref: '#/components/schemas/booleanSearchOperation'
isManualOverwrite:
$ref: '#/components/schemas/booleanSearchOperation'
isFormulaSet:
$ref: '#/components/schemas/booleanSearchOperation'
isCustomFormulaSet:
$ref: '#/components/schemas/booleanSearchOperation'
target:
anyOf:
- $ref: '#/components/schemas/singleTarget'
- $ref: '#/components/schemas/multiTarget'
type:
anyOf:
- $ref: '#/components/schemas/singleType'
- $ref: '#/components/schemas/multiType'
subType:
anyOf:
- $ref: '#/components/schemas/singleSubType'
- $ref: '#/components/schemas/multiSubType'
createdAt:
$ref: '#/components/schemas/datetimeSearchOperation'
updatedAt:
$ref: '#/components/schemas/datetimeSearchOperation'
exportSearchCollectionRequest:
type: object
example:
type: COLLECTION
match:
name:
locale:
- en-US
op: CONTAINS
value: Flash Sale
categoryIdsIncluded:
op: EQUALS
value: 5f328bf0b5f328bf0b5f328b
additionalProperties: false
required:
- match
- type
properties:
type:
type: string
enum:
- COLLECTION
description: Entity type for export
example: COLLECTION
match:
description: Filter conditions to narrow down collections
type: object
minProperties: 1
properties:
id:
$ref: '#/components/schemas/simpleStringSearchOperation'
name:
allOf:
- $ref: '#/components/schemas/stringSearchOperation'
type: object
description: >-
Searches for attributes based on the applied filter conditions.
Append locale and name with a `#` as a value
properties:
locale:
type: array
description: >-
If `isLocalizable` is true, searches for the localized name
in the specified locales. If `isLocalizable` is false, the
search is only based on the non-localized names.
items:
type: string
description: Locale
example: en_US
isLocalizable:
$ref: '#/components/schemas/booleanSearchOperation'
isRoot:
$ref: '#/components/schemas/booleanSearchOperation'
isLeaf:
$ref: '#/components/schemas/booleanSearchOperation'
attribute:
type: array
items:
$ref: '#/components/schemas/attributeSearchOperation'
categoryIdsIncluded:
$ref: '#/components/schemas/simpleStringSearchOperation'
categoryIdsExcluded:
$ref: '#/components/schemas/simpleStringSearchOperation'
productAttributeIdsFilter:
$ref: '#/components/schemas/simpleStringSearchOperation'
updatedBy:
$ref: '#/components/schemas/simpleStringSearchOperation'
createdAt:
$ref: '#/components/schemas/datetimeSearchOperation'
updatedAt:
$ref: '#/components/schemas/datetimeSearchOperation'
exportSearchCategoryRequest:
type: object
example:
type: CATEGORY
match:
name:
locale:
- en-US
op: CONTAINS
value: shoes
attribute:
- id: 5f328bf0b5f328bf0b5f328b
value:
- op: EQUALS
value: thirty
isLeaf:
op: EQUALS
value: true
required:
- match
- type
additionalProperties: false
properties:
type:
type: string
enum:
- CATEGORY
description: Type of entity to be exported
example: CATEGORY
match:
description: Filter criteria to export categories
type: object
minProperties: 1
properties:
id:
$ref: '#/components/schemas/simpleStringSearchOperation'
name:
allOf:
- $ref: '#/components/schemas/stringSearchOperation'
type: object
description: >-
Search criteria to find attributes. Append locale and name with
a `#` as a value.
properties:
locale:
type: array
description: >-
If `isLocalizable` is true, the search is based on the
localized name in specified locales. If `isLocalizable` is
false, the search is only based on the non-localized names.
items:
type: string
description: Locale
example: en_US
isLocalizable:
$ref: '#/components/schemas/booleanSearchOperation'
isRoot:
$ref: '#/components/schemas/booleanSearchOperation'
isLeaf:
$ref: '#/components/schemas/booleanSearchOperation'
attribute:
type: array
items:
$ref: '#/components/schemas/attributeSearchOperation'
productIds:
$ref: '#/components/schemas/simpleStringSearchOperation'
productAttributeIds:
$ref: '#/components/schemas/simpleStringSearchOperation'
hasProductAttributeMandatory:
$ref: '#/components/schemas/booleanSearchOperation'
updatedBy:
$ref: '#/components/schemas/simpleStringSearchOperation'
createdAt:
$ref: '#/components/schemas/datetimeSearchOperation'
updatedAt:
$ref: '#/components/schemas/datetimeSearchOperation'
exportIDJobRequest:
type: object
additionalProperties: false
description: Export job based on ID
required:
- ids
- type
properties:
type:
type: string
description: >-
Type of entity to be exported, such as attributes, categories, or
collections
enum:
- ATTRIBUTE
- CATEGORY
- COLLECTION
example: ATTRIBUTE
ids:
type: array
minItems: 1
items:
type: string
description: >-
IDs of categories, collections or attributes that needs to be
exported
example:
- 5f328bf0b5f328bf0b5f328b
- 22328bf0b5f328bf0b5f3287
locale:
$ref: '#/components/schemas/locale'
productExportJobRequest:
type: object
additionalProperties: false
description: Export based on IDs and type
required:
- ids
- type
properties:
type:
type: string
description: >-
Type of entity to be exported, such as item, item variants, or
bundle
enum:
- ITEM_VARIANT
- BUNDLE
example: ITEM_VARIANT
ids:
type: array
minItems: 1
items:
type: string
description: IDs for items, variants, or bundles that needs to be exported
example:
- 5f328bf0b5f328bf0b5f328b 22328bf0b5f328bf0b5f3287
statuses:
type: string
description: >-
Specify the product status either individually or as comma-separated
values. Comma-separated values are used to indicate the preferred
order of operation
1. When the status is DRAFT, the operation
applies to Draft version, if it's available.
2. When the
status is LIVE, the operation applies to Live version, if it's
available.
3. For LIVE, DRAFT status, the priority is given to
Live version, if it's available; otherwise, Draft version is
considered.
4. When the status is DRAFT, LIVE, the priority is
given to Draft version if it's available; otherwise, Live version is
considered.
example: LIVE, DRAFT
default: LIVE, DRAFT
locale:
$ref: '#/components/schemas/locale'
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'
security:
- authorization: []