Batches

You can access this API endpoint upon request only. If you need access to it, reach out to your Client Success Manager.

This information about the batches response does not include everything. We recommend that you take a look at the Open API Spec as well.

Once you send product data to the API, it responds with a status and a batch identifier or Batch ID. Use the Batch ID to check the processing status of a specific payload.

Example using a chunked stream:

curl --location --request GET 'https://stream-api.productsup.com/streams/124773/batches/b15e8bb1-bd53-470a-9597-785003536978' \
--header 'Accept: application/vnd.api+json'

We keep track of 3 overall statuses of a batch:

uploaded - when products were fully or partially uploaded to a stream

processed - when products were fully or partially processed and imported to a site

failed - when all products from a batch were invalid either during upload or processing stage.

Each batch transits through 2 stages: upload and processing and each stage can be found with one of 3 statuses:

success - no invalid products were encountered

warning - at least 1 invalid product was encountered

failure - all products were invalid

Partial uploads

When you upload a batch which contains some invalid products, a chunked stream accepts it as a partial upload and responds with a 202 Accepted HTTP status code. The property data.attributes.stages.upload of the batch object then includes the status of the upload stage, a number of successfully uploaded products, details of how many invalid products were encountered, and a list of unique error messages captured with example raw product data.

A referenced stream does not validate products on upload and will always indicate that an upload was either a success or failure.

Processing

When you run an import process, the property data.attributes.stages.processing of the batch object gets updated with the status of the processing stage, which also includes a number of successfully imported products, a number of errors encountered, and a list of unique error messages captured with example raw product data.

Invalid batch

Chunked type

Error	Response Code	Description
Empty Product Attributes	422	When sending a product where all attributes are empty
Empty Payload line	422	When sending an empty line
Missing "id" attribute	422	When the id attribute is not found in the product details
Product payload is too large	422	When the payload size is too big, max line length is 2097152 bytes
Control character error, possibly incorrectly encoded	422	When there is an error in data coding like missing an open quote
Syntax error	422	When missing a comma between attributes for example
Empty Payload	422	When the payload is empty

Empty Product Attributes of Chunked type:

curl --location --request POST 'https://stream-api.productsup.com/streams/streamId/products' \
--header 'Content-Type: application/x-ndjson' \
--header 'Authorization: Bearer token' \
--data-raw '{}'

Empty Payload line of Chunked type:

curl --location --request POST 'https://stream-api.productsup.com/streams/streamId/products' \
--header 'Content-Type: application/x-ndjson' \
--header 'Authorization: Bearer token' \
--data-raw '  '

Empty Payload of Chunked type:

curl --location --request POST 'https://stream-api.productsup.com/streams/streamId/products' \
--header 'Content-Type: application/x-ndjson' \
--header 'Authorization: Bearer token' \
--data-raw ''

Referenced type

Error	Response Code	Description
Empty Payload	422	When the payload is empty

Empty Payload of Referenced type (example 1):

curl --location --request POST 'https://stream-api.productsup.com/streams/streamId/products' \
--header 'Content-Type: application/json' \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer token' \
--data-raw '[{ }]'

Empty Payload of Referenced type (example 2):

curl --location --request POST 'https://stream-api.productsup.com/streams/streamId/products' \
--header 'Content-Type: application/json' \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer token' \
--data-raw '[]'

Empty Payload of Referenced type (example 3):

curl --location --request POST 'https://stream-api.productsup.com/streams/streamId/products' \
--header 'Content-Type: application/json' \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer token' \
--data-raw '[  ]'

Empty Payload of Referenced type (example 4):

curl --location --request POST 'https://stream-api.productsup.com/streams/streamId/products' \
--header 'Content-Type: application/json' \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer token' \
--data-raw ''