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 type	Description
delivery	Use the delivery workflow statuses with this batch.
pickup	Use the pickup workflow statuses with this batch.
delivery_only	Use the last mile delivery workflow statuses with this batch.
runner_customer	Use the runner statuses with this batch, where a runner is an employee assigned to bring a staged pickup order to the customer.

Security

Name	In	Description
Authorization	header	The Authorization header with the bearer token acquired during authentication.

Parameters

Name	In	Type	Required	Description
X-Treat-Ids-As-Internal	header	boolean

Request

Field	Type	Required	Description
shopper_id	integer		The ID of the shopper.
batch_type	string		The batch type.
workflow_state	string		The initial workflow state of the batch.
orders	Array(Order)		The orders to batch.

Order Object

Field	Type	Required	Description
id	string		The ID of the order.

Request examples

cURL

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"
    }
  ]
}'

Java

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/fulfillment_sandbox/batches")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .header("X-Treat-Ids-As-Internal", "true")
  .body("{\n  \"shopper_id\": 1,\n  \"batch_type\": \"delivery\",\n  \"workflow_state\": \"string\",\n  \"orders\": [\n    {\n      \"id\": \"string\"\n    }\n  ]\n}")
  .asString();

Python

import http.client

conn = http.client.HTTPSConnection("connect.instacart.com")

payload = "{\n  \"shopper_id\": 1,\n  \"batch_type\": \"delivery\",\n  \"workflow_state\": \"string\",\n  \"orders\": [\n    {\n      \"id\": \"string\"\n    }\n  ]\n}"

headers = {
    'Accept': "application/json",
    'Content-Type': "application/json",
    'Authorization': "Bearer <token>",
    'X-Treat-Ids-As-Internal': "true"
    }

conn.request("POST", "/v2/fulfillment_sandbox/batches", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Go

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://connect.instacart.com/v2/fulfillment_sandbox/batches"

	payload := strings.NewReader("{\n  \"shopper_id\": 1,\n  \"batch_type\": \"delivery\",\n  \"workflow_state\": \"string\",\n  \"orders\": [\n    {\n      \"id\": \"string\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "application/json")
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Treat-Ids-As-Internal", "true")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Response

Field	Type	Required	Description
id	integer		The ID of the batch.
workflow_state	string		The current workflow state of the batch.

Response examples

200 Success

200 Batch generated

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

200 Pickup batch generated

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

200 Runner-customer batch generated

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

200 Delivery only batch generated

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

200 Delivery only batch generated with target workflow state

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

200 Delivery batch generated with target workflow state

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

4XX Errors

Error responses return either a single error or multiple errors.

HTTP Code	Cause	Error Message	Error Code	Error Meta
400	Shopper not found	"Shopper not found"	1001	{"key":"shopper_id"}
400	Order not found	"Order not found"	1001	{"key":"orders[1]"}
400	Orders unbatchable	"Orders unbatchable"	3001	Not applicable