Batch request overview and limits
Multiple OData API requests may be combined into a single batch request.
We currently support a maximum of 100 requests within a single batch.
The maximum size of a batch request body is 300k.
Batch request procedures
To make a batch OData API request, submit a POST request to https://odata.liftoff.shop/odata/v1/$batch. As with all OData API requests, be sure to include an authorization header.
The body of this $batch request must be a JSON-formatted array of objects. This array must be named requests. Each request object in this array should include the following properties:
| Property | Description |
|---|---|
id | An identifier for the request. Each request within the batch request must have a unique id value. |
method | The method type for the request; e.g., GET, POST, PATCH, DELETE. |
headers | This should always include a Content-Type header that is set to application-json. See the example below for exact formatting. |
url | The URL for the request. This value may be an absolute URL (e.g., https://odata.liftoff.shop/odata/v1/Customer) or a relative URL (e.g., /odata/v1/Customer). The request URL may also include query options such as $expand, $filter, $select, and $top.URL path parameters and query strings may include tokens that reference earlier responses in the batch. See Tokens in batch requests below for details. |
body | The body of the request. Only applicable to POST and PATCH requests.Request bodies may include tokens that reference earlier responses in the batch. See Tokens in batch requests below for details. |
Example batch request
{
"requests": [
{
"id": "1",
"method": "POST",
"headers": {
"Content-Type": "application/json"
},
"url": "/odata/v1/Customer",
"body": {
"Email": "[email protected]",
"Name": "Trenton Hudson",
"CurrencyCode": "USD"
}
},
{
"id": "2",
"method": "PATCH",
"headers": {
"Content-Type": "application/json"
},
"url": "/odata/v1/CustomerField(CustomerId=$[1].body.Id,AccountCustomerFieldId=41267)",
"body": {
"Value": "purple"
}
},
{
"id": "3",
"method": "POST",
"headers": {
"Content-Type": "application/json"
},
"url": "/odata/v1/CustomerRoleMember",
"body": {
"CustomerRoleId": 2017,
"CustomerId": "$[1].body.Id"
}
}
]
}The above example batch request executes three OData API requests in sequence:
- A
POSTrequest to add a customer named Trenton Hudson - A
PATCHrequest to assign a value of purple to a customer field for the newly created customer - A
POSTrequest to add the newly created customer to a customer role
Batch request responses
When a batch OData API request is made, the response body will contain a JSON-formatted array of objects. This array will be named responses. Each response object in this array corresponds to a request within the batch.
The response body for the above example batch request would look like the following:
{
"responses": [
{
"id": "1",
"status": 201,
"headers": {
"location": "http://odata.liftoff.shop/odata/v1/Customer(1063490)",
"content-type": "application/json; odata.metadata=minimal; odata.streaming=true; charset=utf-8",
"odata-version": "4.0"
},
"body": {
"@odata.context": "http://odata.liftoff.shop/odata/v1/$metadata#Customer/$entity",
"Id": 1063490,
"AccountId": 3098,
"Email": "[email protected]",
"Password": "",
"Name": "Trenton Hudson",
"CreateDate": "2026-07-20T21:53:29.5283787Z",
"LastModifiedDate": "2026-07-20T21:53:29.5283787Z",
"LastLoginDate": null,
"IsActive": true,
"IsGuest": false,
"CurrencyCode": "USD",
"CustomerId": "",
"TaxExempt": false,
"OpenAccount": true,
"EnableCreditCards": true,
"EnableBudgets": true,
"EnableDiscounts": true,
"AllowBillingAddressManagement": false,
"AllowShippingAddressManagement": true,
"AllowShippingAttentionManagement": false,
"ForcePasswordReset": true
}
},
{
"id": "2",
"status": 200,
"headers": {
"content-type": "application/json; odata.metadata=minimal; odata.streaming=true; charset=utf-8",
"odata-version": "4.0"
},
"body": {
"@odata.context": "http://odata.liftoff.shop/odata/v1/$metadata#CustomerField/$entity",
"CustomerId": 1063490,
"AccountCustomerFieldId": 41267,
"Name": "Favorite Color",
"Value": "purple"
}
},
{
"id": "3",
"status": 201,
"headers": {
"location": "http://odata.liftoff.shop/odata/v1/CustomerRoleMember(22158871)",
"content-type": "application/json; odata.metadata=minimal; odata.streaming=true; charset=utf-8",
"odata-version": "4.0"
},
"body": {
"@odata.context": "http://odata.liftoff.shop/odata/v1/$metadata#CustomerRoleMember/$entity",
"Id": 22158871,
"CustomerRoleId": 2017,
"CustomerId": 1063490
}
}
]
}Tokens in batch requests
Often, you will need to reference values that are returned by an earlier request in the batch. For example, consider the use case for the example batch request above:
- You need to create a new customer.
- You need to assign a value to a customer field for that customer. To do so, you need the
Customer.Idfor that new customer. - You need to add the new customer to a customer role. To do so, you need the
Customer.Idfor the new customer.
With tokens, you can complete all three steps within a single batch, without having to implement application logic to parse response values from one request to use in subsequent, separately issued requests.
In the batch request example above, note the url value for request ID 2:
"url": "/odata/v1/CustomerField(CustomerId=$[1].body.Id,AccountCustomerFieldId=41267)"
In particular, note that the value of the CustomerId path parameter is set to $[1].body.Id.
$[1].body.Id is a token that references the body.Id value in the response for request ID 1 ($[1]). If we check the body of this request ID 1, we will see that body.Id (using JSON path syntax) property is the ID of the newly created customer, or 1063490:
"id": "1",
"status": 201,
"headers": {
"location": "http://odata.liftoff.shop/odata/v1/Customer(1063490)",
"content-type": "application/json; odata.metadata=minimal; odata.streaming=true; charset=utf-8",
"odata-version": "4.0"
},
"body": {
"@odata.context": "http://odata.liftoff.shop/odata/v1/$metadata#Customer/$entity",
"Id": 1063490,
"AccountId": 3098,
"Email": "[email protected]",
...
}This token will automatically be interpolated as 1063490 at runtime, resulting in a url value of:
/odata/v1/CustomerField(CustomerId=1063490,AccountCustomerFieldId=41267)
Tokens may also be referenced in the body of a request. In the batch request example above, note the body value for request ID 3:
"body": {
"CustomerRoleId": 2017,
"CustomerId": "$[1].body.Id"
}As before, the token $[1].body.Id will be replaced with the newly created customer's ID at runtime, resulting in a body value of:
"body": {
"CustomerRoleId": 2017,
"CustomerId": "1063490"
}Tokens may be specified within request URL path parameters, request URL query strings, or request bodies. Tokens can reference any body property value from the response of any earlier request in the batch.