Some APIs support "batch import" which is a slightly different method for submitting and processing update requests. This allows you to send a large batch of updates before marking them as ready for processing, at which point Kibo will begin to perform all updates at either the system's own pace or a specific scheduled date.
Batch importing provides better fault tolerance, as Kibo is able to retry the action several times. Processing batch updates at Kibo's own pace also reduces load on the system, helping to avoid service disruption.
Batch Job Statuses
The below statuses indicate whether or not a job has been processed.
- Ready: Job is not yet processed but can begin immediately regardless of the date.
- Pending: Job is waiting for a scheduled date to be reached before it can be processed.
- Completed: Job has been fully processed.
- Canceled: Job has been canceled.
Individual items within a job also have their own Processing Status.
- Waiting: Item data is being updated.
- Running: An action has been performed for the item.
- ValidationFailed: Item could not be found.
- Failed: An error was experienced, such as missing data.
- Completed: Item data has been successfully added or updated.
- Canceled: Item's job has been canceled.
Available APIs
Batch imports can only be performed on specific APIs, and their jobs can be managed with dedicated Batch Job API endpoints to start, cancel, or reset imports as needed.
APIs with Batch Import Support
Only the Product, ProductProperties, and PriceLists endpoints of the Catalog Admin APIs support batch importing with their POST, PUT, and DELETE calls. Support for more APIs may be added later if there is client demand for it.
Manage Batch Import Jobs
The following Batch Job endpoints manage your batch import jobs.
- The Create Batch Job call initiates an unstarted batch job that your updates will be added to.
- The Perform Batch Action call starts, cancels, and resets jobs. Reset can only be called for jobs that are already completed or canceled, and will remove all items so that you can re-use the empty job.
- The Get Batch Job Items call queries for items of a specific processing status and/or resource by appending
?processingStatus={processingStatus}&resourceType={resourceType}to the endpoint.- Resource Type Options: Products, ProductProperty, Pricelistentries
- The Update Batch Job call currently only allows you to change the name of the batch job.
Batch Import Process
First make a Create Batch Job call. Only the code, name, and domain (which is "Catalog" for both prices and price lists) are required, as the status will default to Ready if not provided. Providing an optional scheduledDate field will determine when Kibo begins processing the import.
{
"code": "batch_job_1",
"jobName": "Example Job",
"scheduledDate": null,
"domain": "Catalog",
"status": "Ready"
}
Then make your update calls to the Product or Price Lists API and specify the batchJobCode as a parameter in the endpoint, as shown below (using the Add Products API as an example). This will add the updates to the job but not yet implement them.
.../commerce/catalog/admin/products/?batchJobCode={batch_job_1}
Once all of your updates are added to the job, call the Perform Batch Action API to indicate that it's ready to be processed with the start action. This is necessary even for jobs with a scheduled date, which will go into Pending status until that date is reached (at which point Kibo will automatically begin the update process). If a scheduled date was not provided, the job will be processed immediately.
.../platform/data/batchJob/actions/{batch_job_1}{
"action": "start"
}