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 job statuses indicate whether or not the 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
While batch imports can be performed on certain APIs, the import jobs can also be managed with dedicated endpoints.
APIs with Batch Import Support
The Product, Product Property, and Price Lists APIs support batch importing with their Add, Update, and Delete calls. This includes the Bulk Price List Entries endpoints within the Price Lists API.
Support for more APIs may be added later if there is client demand for it.
Manage Batch Import Jobs
The Batch Job API endpoints within the Import-Export service allow you to manage your batch import jobs. Be aware of the following behaviors:
- The Perform Batch Action call allows you to perform start, cancel, and reset actions. 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 allows you to query 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
Before importing your updates, 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, provide that code as a parameter in the endpoint while updating your product or price list data. The below example shows a call to the Add Products API specifying the job:
.../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 the job is ready to be processed by providing 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 is not provided, the job can be processed immediately.
.../platform/data/batchJob/actions/{batch_job_1}{
"action": "start"
}