Skip to main content

Advance the batch status

POST /v2/fulfillment_sandbox/batches/{batch_id}/advance

Advances the status of a batch through the statuses for the selected fulfillment workflow. You specified the fulfillment workflow when you generated the batch with the batch_type attribute set to one of the workflows. The transitions occur in the order shown. Optionally, you can set the status in the request body.

Delivery

#StatusDescription
0brand_newThe default batch state when a delivery batch is generated.
1acknowledgedShopper is assigned to a batch that contains the order ID.
2pickingShopper has started shopping.
3verifying_replacementsShopper has requested approval for replacements and refunds.
4checkoutShopper has paid for the order.
5receipt_sanity_checkShopper has verified the receipt is accurate.
6deliveringShopper is in transit to the customer's address.
7completedShopper has delivered the order to the customer.

Pickup

#StatusDescription
0brand_newThe default batch state when a pickup batch is generated.
1acknowledgedShopper is assigned to a batch that contains the order ID.
2pickingShopper has started shopping.
3verifying_replacementsShopper has requested approval for replacements and refunds.
4checkoutShopper has paid for the order.
5receipt_sanity_checkShopper has verified the receipt is accurate.
6bags_checkShopper has verified the contents of the bags.
7stagedShopper has placed the bags in the staging area.

At this point, a runner_customer batch must be created for an employee to run the bags from the staging area to the customer. The Advance batch endpoint moves this batch through the following states:

#StatusDescription
0brand_newThe default batch state when a runner_customer batch is generated.
1at_storeCustomer has arrived at the store to pick up the order.
2bags_verifiedCustomer has verified the number of bags matches the order.
3completedCustomer has accepted the order.

Last mile delivery (delivery only)

#StatusDescription
0brand_newThe default batch state when a delivery_only batch is generated.
1acknowledged_for_deliveryShopper is assigned to a batch.
2at_storeShopper has arrived at the store to get the order.
3bags_verifiedShopper has verified the number of bags matches the order.
4deliveringShopper is in transit to the customer's address.
5completedShopper has delivered the order to the customer.

Security

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

Parameters

NameInTypeRequiredDescription
batch_idpathintegerThe ID of the batch.

Request

FieldTypeRequiredDescription
workflow_statestringThe target workflow state that the batch.

Request examples

curl --request POST \
--url 'https://connect.instacart.com/v2/fulfillment_sandbox/batches/{batch_id}/advance' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"workflow_state": "string"
}'

Response

FieldTypeRequiredDescription
idintegerThe ID of the batch.
workflow_statestringThe new 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
400Batch already completed"Batch already completed"3002{}
404Batch not found"Batch not found"4000{}