Skip to main content

Generate a batch

POST /v2/fulfillment_sandbox/batches

Generates a batch that contains an order ID and a shopper ID. To create an order ID, use the appropriate Create order endpoint in the Fulfillment API.

When generating the initial batch, set the batch_type to match the type of order you created. For the pickup workflow, use this endpoint a second time to generate a batch for an employee to run the order to the customer in the pickup area.

The following table describes the valid values for the batch_type attribute.

Batch typeDescription
deliveryUse the delivery workflow statuses with this batch.
pickupUse the pickup workflow statuses with this batch.
delivery_onlyUse the last mile delivery workflow statuses with this batch.
runner_customerUse the runner statuses with this batch, where a runner is an employee assigned to bring a staged pickup order to the customer.

Security

NameInDescription
AuthorizationheaderThe Authorization header with the bearer token acquired during authentication.

Parameters

NameInTypeRequiredDescription
X-Treat-Ids-As-Internalheaderboolean

Request

FieldTypeRequiredDescription
shopper_idintegerThe ID of the shopper.
batch_typestringThe batch type.
workflow_statestringThe initial workflow state of the batch.
ordersArray(Orders)The orders to batch.

Orders Object

FieldTypeRequiredDescription
idstringThe ID of the order.

Request examples

curl --request POST \
--url https://connect.instacart.com/v2/fulfillment_sandbox/batches \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Treat-Ids-As-Internal: true' \
--data '{
"shopper_id": 1,
"batch_type": "delivery",
"workflow_state": "string",
"orders": [
{
"id": "string"
}
]
}'

Response

FieldTypeRequiredDescription
idintegerThe ID of the batch.
workflow_statestringThe current workflow state of the batch.

Response examples

200 Success

{
"id": 1,
"workflow_state": "acknowledged"
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400Shopper not found"Shopper not found"1001{"key":"shopper_id"}
400Order not found"Order not found"1001{"key":"orders[1]"}
400Orders unbatchable"Orders unbatchable"3001{}