Using the batch Items API

This API requires Authentication.

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.

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.

Batches into non-active catalogs (FHR/XO)

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:

1. Add a createBatchImport=true query parameter to the catalog creation call.

2. When sending items:

   1. Change URL from https://items.attraqt.io/items to https://items.attraqt.io/batch-imports/items.

   2. Add a batch_id query parameter with a value set to the catalog version.

   3. Remove catalogVersion from request body attributes.

3. Once all items are sent, replace the catalog promotion call with a batch ingestion creation similar to the following:

curl --request POST
 --url 'https://items.attraqt.io/batch-imports/ingestions?tenant=$TENANT&environment=$ENVIRONMENT'
 --header 'Authorization: Bearer $ACCESS_TOKEN'
 --header 'Content-Type: application/json'
  --data '{
  "catalogVersion": $CATALOG_VERSION,
  "promoteCatalogOnCompletion": true
}'

Optionally specify minItemCount and minSuccessRatePercent.

Batches into active catalogs (XO only)

Clients integrated with XO only can use this method.

Implementation changes:

1. Create a batch before sending items, and keep its ID.

curl --request POST 
 --url 'https://items.attraqt.io/batch-imports?tenant=$TENANT&environment=$ENVIRONMENT' 
 --header 'Authorization: Bearer $ACCESS_TOKEN'

1. When sending items:

   1. Change URL from https://items.attraqt.io/items to https://items.attraqt.io/batch-imports/items.

   2. Add a batch_id query parameter with a value set to the batch ID created earlier.

   3. Remove catalogVersion from request body attributes.

2. Once all items are sent, launch a batch ingestion.

curl --request POST 
 --url 'https://items.attraqt.io/batch-imports/ingestions?tenant=$TENANT&environment=$ENVIRONMENT' 
 --header 'Authorization: Bearer $ACCESS_TOKEN' 
 --header 'Content-Type: application/json' 
  --data '{
  "batchImportId": $BATCH_ID,
  "catalogVersion": $CATALOG_VERSION,
}'

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	Your tenant ID
environment*	string	Your environment ID

Headers

Name	Description
Authorization*	Bearer token

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=true query 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	Your tenant ID
environment*	string	Your environment ID

Headers

Name	Description
Authorization*	Bearer token

Response body

The response body consists of an array of objects containing the following fields:

Name	Type	Description
id*	object	batch ID
createdAt*	RFC 3339 Internet date/time format	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	Your tenant ID
environment*	string	Your environment ID
batch_id*		batch ID returned by the batch creation call OR identical to catalog version for default catalog batches

Headers

Name	Description
Authorization*	Bearer token
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	Item schema name
context	string	Context (store ID, private sales...); can only include alphanumeric characters, underscores, and hyphens
timestamp	RFC 3339 Internet date/time format, e.g. 1985-04-12T23:20:50.52Z	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	c.f. item attributes

Sample request body:

[
   {
        "id": "id1",
        "type": "product",
        "timestamp": "2024-09-05T10:50:42Z",
        "attributes": {
            "title": "Item 1",
            "url": "https://example.com/item1"
        }
   },
   {
        "id": "id2",
        "type": "variant",
        "parentId": "id1",
        "attributes": {
            "size": 2
        }
    }
]

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	Your tenant ID
environment*	string	Your environment ID
batch_id*		batch ID returned by the batch creation call OR identical to catalog version for default catalog batches

Headers

Name	Description
Authorization*	Bearer token
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	Item schema name
context	string	Context (store ID, private sales...); can only include alphanumeric characters, underscores and hyphens
timestamp	RFC 3339 Internet date/time format, e.g. 1985-04-12T23:20:50.52Z	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:

Sample request body:

[{
        "id": "id1",
        "type": "product",
        "attributes": {
		    "url": "https://example.com/item1_patch"
        }
}]

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	Your tenant ID
environment*	string	Your environment ID
batch_id*		batch ID returned by the batch creation call OR identical to catalog version for default catalog batches

Headers

Name	Description
Authorization*	Bearer token
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	Item schema name
context	string	Context (store ID, private sales...); can only include alphanumeric characters, underscores and hyphens
timestamp	RFC 3339 Internet date/time format, e.g. 1985-04-12T23:20:50.52Z	Defaults to current time stamp; allows ordering insertion, modification, and deletion operations on the same item

Sample request body:

[{
  "id": "id1",
  "type": "product"
}]

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	Your tenant ID
environment*	string	Your environment ID

Headers

Name	Description
Authorization*	Bearer token
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	Your tenant ID
environment*	string	Your environment ID

Headers

Name	Description
Authorization*	Bearer token

Response body

Name	Type	Required	Description
id*	string	yes	Batch ingestion ID
status*	string	yes	Results in one of the following: RUNNING SUCCESS FAILURE (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*	RFC 3339 Internet date/time format	yes	Creation timestamp
updatedAt*	RFC 3339 Internet date/time format	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	Your tenant ID
environment	string	The environment for which you want to list ingestions. This parameter can be set multiple times, or none to fetch ingestions for all environments
lookback_duration	number	Time window in milliseconds, going back from now
status	string	Filters ingestions by their status. Possible values: RUNNING, SUCCESS, ERROR, FAILURE

Headers

Name	Description
Authorization*	Bearer token

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	Your tenant ID
environment*	string	Your environment ID

Headers

Name	Description
Authorization*	Bearer token