This feature is in early access, which means that we are working to improve it. If you want to use this feature, please contact our Support Center.

The Batch operations endpoints of the Logistics API let you update large volumes of inventory data asynchronously by uploading a single CSV file to Amazon S3 and tracking its processing through the API. This flow is designed for scenarios such as full inventory refreshes and bulk synchronizations, where the existing per-SKU endpoints would require too many requests.

This guide walks you through the end-to-end flow: creating a batch job, uploading the CSV file, committing the batch for processing, polling the processing status, and downloading the error report if there are failed rows.

The integration involves four API endpoints and one direct upload to the pre-signed S3 URL returned by VTEX:

1. Create batch: Call the Create batch inventory job endpoint to register a new batch. The response includes a batchId and a pre-signed S3 URL for the CSV upload.
2. Upload CSV: Upload the CSV file directly to S3 using the pre-signed URL. This step does not go through the VTEX API.
3. Commit batch: Call the Commit batch inventory endpoint to confirm the upload and queue the batch for processing.
4. Monitor processing: Poll the Get batch inventory status endpoint until the batch reaches a terminal status.
5. Download error report (optional): If the status response indicates errorCount > 0, call the Get batch inventory errors endpoint to retrieve a pre-signed URL for the error CSV.

Use the Create batch inventory job endpoint to register a new batch. The response returns the batchId you will use throughout the flow and the pre-signed upload object you will use to send the CSV to S3.

Response example:

The batch starts in AWAITING_UPLOAD status and remains in this state until the CSV is uploaded and committed.

The pre-signed URL returned in url is valid for 30 minutes (see expiresAt). If the URL expires before you upload the file, create a new batch.

Upload the CSV file directly to S3 using the url returned by the Create batch inventory job endpoint. This request does not go through the VTEX API.

Keep the following requirements in mind:

• Submit every field following the order defined in the CSV file.
• The CSV file name must match the batchId returned in the Create batch inventory job response (for example, 550e8400-e29b-41d4-a716-446655440000.csv).
• Use the HTTP method (PUT) and headers (Content-Type: text/csv) returned in the upload object.

Example request:

Replace {presignedUrl} with the value returned in url. A successful upload returns an HTTP 200 OK response from S3.

After uploading the CSV to S3, call the Commit batch inventory endpoint, passing the batchId as a path parameter. This request confirms that the upload is complete and triggers the asynchronous processing of the batch.

A successful commit returns an HTTP 202 Accepted response, and the batch transitions to the QUEUED status. From this point on, processing is handled asynchronously by VTEX, and you can use the status endpoint to track progress.

If you call this endpoint twice in parallel for the same batchId, the second request will receive a 423 Locked response. Wait for the first commit to complete before retrying.

Use the Get batch inventory status endpoint to track the processing progress of the batch. The response returns row counts, error counts, percentage completed, processing stages, and a final summary once the batch is processed.

Response example:

The status field can return the following values:

Status	Description
AWAITING_UPLOAD	Batch created, waiting for CSV upload.
QUEUED	Upload committed, waiting to begin processing.
PROCESSING	Batch is currently being processed.
COMPLETED	All rows processed successfully.
COMPLETED_WITH_ERRORS	Processing finished with some row errors.
FAILED	Processing failed due to validation or system errors.
EXPIRED	Batch metadata has expired.

COMPLETED, COMPLETED_WITH_ERRORS, FAILED, and EXPIRED are terminal statuses. Once any of these is returned, no further updates will be made to the batch and you can stop polling.

If the batch status response indicates errorCount > 0, use the Get batch inventory errors endpoint to retrieve a pre-signed URL for downloading a CSV report with all rows that failed processing.

Response example:

The downloadUrl is a pre-signed S3 URL valid for 60 minutes. The error report itself remains available until the batch metadata expires, which is 7 days after batch completion.

The endpoint returns a 204 No Content response if errorCount is 0 or the batch is not in a status that produces an error report (PROCESSING, COMPLETED, COMPLETED_WITH_ERRORS, or FAILED).

The error CSV contains the following fields:

Field	Type	Description
line_number	integer	Original line number in the uploaded CSV.
item_id	string	SKU identifier from the failed row.
container_id	string	Warehouse ID from the failed row.
error_code	string	Machine-readable error code.
error_message	string	Human-readable error description.

Example:

The error report distinguishes between two categories of errors:

• Deterministic errors: Caused by invalid or incomplete data in the submitted file, such as missing required fields or invalid values. They are detected during file ingestion from S3 and fail the affected records immediately. The system does not retry these operations automatically. To resolve them, fix the data in the CSV file and submit a new batch.
• Non-deterministic errors: Caused by infrastructure or system issues. The system automatically retries the operation up to three times. If it still fails, the message is sent to a Dead Letter Queue (DLQ) for further investigation. These errors appear as UPDATE_FAILED in the error CSV.

Error code	Description
INVALID_QUANTITY	Quantity value is invalid (negative or non-numeric).
MISSING_REQUIRED_FIELD	A required field is empty or missing.
INVALID_DATE_FORMAT	A date or time field has an invalid format.
UPDATE_FAILED	Database update failed after retries (non-deterministic error).
INSERT_CONFLICT	Insert conflicted with a concurrent operation.
INVALID_FORMAT	Row format is invalid (for example, wrong number of columns).
CONFLICT	Compare-And-Set conflict or per-item routing conflict.
UNKNOWN	Unclassified error.

• Reuse the same batchId: Always use the batchId returned by the Create batch inventory job endpoint when uploading the CSV, committing the batch, polling its status, and retrieving errors.
• Respect the upload window: The pre-signed upload URL expires 30 minutes after creation. If it expires before the upload is complete, create a new batch.
• Avoid concurrent commits: Do not commit the same batch in parallel. A second commit while one is in progress returns a 423 Locked response.
• Use a reasonable polling interval: When monitoring large batches, poll the status endpoint at intervals proportional to the batch size to avoid unnecessary requests.
• Fix deterministic errors at the source: If the error report shows deterministic errors, correct them in your source data and submit a new batch instead of retrying the same file.