Using the batch Items API
Required fields are marked with a red asterisk (*) in the Name column.
Use the batch Items API to replace a whole or parts of a catalog.
Create a batch
POST https://items.attraqt.io/batch-imports
This endpoint allows you to import a batch.
Query Parameters
Name
Type
Description
tenant*
string
environment*
string
Headers
Name
Description
Authorization*
Response Body
Name
Type
Description
id
string
batch ID
Batches automatically expire after 7 days and can therefore not be ingested after this period.
Create a default catalog batch
You can also create batches automatically along with catalogs:
Add a
createBatchImport=truequery parameter to the catalog creation call. -> The ID of this default catalog batch is identical to the catalog version.
List batches
GET https://items.attraqt.io/batch-imports
This allows you to retrieve a list of batches.
Query Parameters
Name
Type
Description
tenant*
string
environment*
string
Headers
Name
Description
Authorization*
Response body
The response body consists of an array of objects containing the following fields:
Name
Type
Description
id*
object
batch ID
createdAt*
batch creation date
Add items to batch
POST https://items.attraqt.io/batch-imports/items
This allows you to add items to an existing batch.
Query Parameters
Name
Type
Description
tenant*
string
environment*
string
batch_id*
batch ID
Headers
Name
Description
Authorization*
Content-Type*
application/json
Request body
The request body consists of an array of JSON items with the following fields:
Name
Type
Description
id*
string
Item ID; can not be empty and can only include alphanumeric characters, underscores, and hyphens
type*
string
context
string
Context (store ID, private sales...); can only include alphanumeric characters, underscores, and hyphens
timestamp
defaults to current time stamp; allows for ordering insertion, modification, and deletion operations on the same item
parentId
string
Parent item, if item is a variant
attributes*
object
Response body
Results are returned in the form of an array. Each array element corresponds to an item in the request body. The results have the following fields:
Name
Type
Description
id*
object
ID, type, and context of the item
code*
integer
0 means success, any other value is an internal error code
message
string
Error message if code is different from 0
A success code (0) means that the item has been added into the batch, but not necessarily that the item is valid.
Items can only be validated against a specific schema during batch ingestions once the target catalog is defined.
Modify items in batch
PATCH https://items.attraqt.io/batch-imports/items
This allows you to modify the items included in an existing batch.
Query Parameters
Name
Type
Description
tenant*
string
environment*
string
batch_id*
batch ID
Headers
Name
Description
Authorization*
Content-Type*
application/json
Request body
The request body consists of an array of JSON items with the following fields:
Name
Type
Description
id*
string
Item ID; can not be empty and can only include alphanumeric characters, underscores and hyphens
type*
string
context
string
Context (store ID, private sales...); can only include alphanumeric characters, underscores and hyphens
timestamp
Defaults to current time stamp; allows ordering insertion, modification, and deletion operations on the same item
parentId
string
Parent item, if item is a variant
attributes
object
Item attributes that need to be modified; unchanged attributes don’t have to be included
sample request body:
Response body
The structure of the response body when modifying items is identical to the structure of the response body when adding items.
Delete items from batch
POST https://items.attraqt.io/batch-imports/items/delete
This allows you to delete items from an existing batch.
Query Parameters
Name
Type
Description
tenant*
string
environment*
string
batch_id*
batch ID
Headers
Name
Description
Authorization*
Content-Type*
application/json
Request body
The request body consists of an array of JSON items with the following fields:
Name
Type
Description
id*
string
Item ID; can not be empty and can only include alphanumeric characters, underscores and hyphens
type*
string
context
string
Context (store ID, private sales...); can only include alphanumeric characters, underscores and hyphens
timestamp
Defaults to current time stamp; allows ordering insertion, modification, and deletion operations on the same item
Batch ingestion
Ingesting a batch in a catalog will:
Validate all items in the batch against catalog item schema
Check that the absolute and relative number of items that pass validation is above the optionally provided threshold
Insert all items that passed validation in the provided catalog
Optionally promote the catalog
POST https://items.attraqt.io/batch-imports/ingestions
This allows you to ingest a batch.
Query Parameters
Name
Type
Description
tenant*
string
environment*
string
Headers
Name
Description
Authorization*
Content-Type*
application/json
Request body
Name
Type
Default value
Description
batchImportId
string
default catalog batch
batch ID returned by the batch creation call; leave empty when ingesting the default catalog batch
catalogVersion*
string
version of the catalog in which the batch must be ingested
minItemCount
number
0
Minimum number of items in the batch that should pass schema validation; ingestion will fail if this threshold is not reached
minSuccessRatePercent
number
0
Minimum percentage of items in the batch that should pass schema validation; ingestion will fail if this threshold is not reached
source
string
empty string
Source of items in the batch, can be any string; this field is only meaningful when used in conjunction with deleteMissingItems
deleteMissingItems
boolean
false
whether items with same source present in the catalog but not present in the batch must be deleted
promoteCatalogOnCompletion
boolean
false
whether the catalog must be promoted after having been loaded
Response body
Name
Type
Description
id
string
batch ingestion ID; can be used to query batch ingestion status
Get batch import ingestion
GET https://items.attraqt.io/batch-imports/ingestions/{id}
This allows you to retrieve the status of a batch ingestion.
Path Parameters
Name
Type
Description
id*
string
ID of batch import ingestion to get
Query Parameters
Name
Type
Description
tenant*
string
environment*
string
Headers
Name
Description
Authorization*
Response body
Name
Type
Required
Description
id*
string
yes
Batch ingestion ID
status*
string
yes
Results in one of the following:
RUNNINGSUCCESSFAILURE(invalid batch, e.g. quality threshold was not met)ERROR(unexpected error)
statusReason
string
if status is FAILURE or ERROR
Reason why the ingestion failed or errored
itemErrorCount
number
if status is SUCCESS or FAILURE
Number of items that didn’t pass validation
itemErrorsSummary
object
if status is SUCCESS or FAILURE
Number of errors by error type, with some Sample error IDs
upsertedItemCount
number
if status is SUCCESS
Number of items that were either inserted or updated in the catalog
deletedItemCount
number
if status is SUCCESS and batch ingestion was launched with deleteMissingItems set to true
Number of items that were deleted from the catalog
duration
string
if status is SUCCESS or FAILURE
Duration of batch ingestion in seconds
createdAt*
yes
Creation timestamp
updatedAt*
yes
Last time batch ingestion status was updated
configuration*
object
yes
Batch ingestion configuration; format is the same as batch ingestion creation request body
Fredhopper currently does not support loading batches into active catalogs. If you try to ingest a batch into the active catalog of a Fredhopper client, it will result in an HTTP 400 error.
You can only ingest one batch into a given catalog at any given time. If you try to load a batch into a catalog which already has a running batch ingestion, it will result in an HTTP 409 error. Once the first ingestion is complete, you can launch another into the same catalog.
Catalogs cannot be promoted during an active batch ingestion. If you try to do so, it will result in an HTTP 409 error.
List batch import ingestions
GET https://items.attraqt.io/batch-imports/ingestions
This allows you to get the status for all ingestions.
Query Parameters
Name
Type
Description
tenant*
string
environment*
string
Headers
Name
Description
Authorization*
Response body
The response body lists all batch ingestions for the active tenant and environment and has the same format as the Get batch import ingestion response body.
Delete a batch ingestion
Batches will be automatically deleted seven days after their creation date, but they can be deleted earlier if they are not longer needed.
DELETE https://items.attraqt.io/batch-imports/ingestions/{id}
This allows you to delete a certain batch.
Path Parameters
Name
Type
Description
id*
string
ID of batch import ingestion to delete
Query Parameters
Name
Type
Description
tenant*
string
environment*
string
Headers
Name
Description
Authorization*
Migrating from streaming Items API to batch Items API
If you have been using the streaming Items API to send your entire catalog, we recommend migrating to the batch Items API, which has been designed for this purpose specifically.
Fredhopper currently does not support loading batches into active catalogs. Clients integrated with Fredhopper must use this method.
Before you enforce the following changes reach out to Crownpeak to enable the feature.
Implementation changes:
Add a
createBatchImport=truequery parameter to the catalog creation call.When sending items:
Change URL from
https://items.attraqt.io/itemstohttps://items.attraqt.io/batch-imports/items.Add a
batch_idquery parameter with a value set to the catalog version.Remove
catalogVersionfrom request body attributes.
Once all items are sent, replace the catalog promotion call with a batch ingestion creation similar to the following:
Optionally specify minItemCount and minSuccessRatePercent.
Last updated