Batch API requests

Multiple OData API requests may be submitted within a single batch request. We currently support a maximum of 100 requests within a single batch.

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:

PropertyDescription
idAn identifier for the request. Each request within the batch request must have a unique id value.
methodThe method type for the request; e.g., GET, POST, PATCH, DELETE.
headersThis should always include a Content-Type header that is set to application-json. See the example below for exact formatting.
urlThe 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).
bodyThe body of the request. Only applicable to POST and PATCH requests.
{
  "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": "POST",
      "headers": {
        "Content-Type": "application/json"
      },
      "url": "/odata/v1/Customer",
      "body": {
        "Email": "[email protected]",
        "Name": "Marietta Nichols",
        "CurrencyCode": "USD"
      }
    },
    {
      "id": "3",
      "method": "GET",
      "headers": {
        "Content-Type": "application/json"
      },
      "url": "/odata/v1/Customer"
    }
  ]
}

The above example batch request would execute three OData API requests in sequence:

  1. A POST request to add a customer named Trenton Hudson
  2. A POST request to add a customer named Marietta Nichols
  3. A GET request to retrieve all customers

🚧

Query options are not supported in batch requests.

At this time, query options (such as $filter and $expand) are not supported for requests within a batch. Any query options that are specified in a request's url property will be ignored.

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": "https://odata.liftoff.shop/odata/v1/Customer(431529)",
        "content-type": "application/json; odata.metadata=minimal; odata.streaming=true",
        "odata-version": "4.0"
      },
      "body": {
        "@odata.context": "https://odata.liftoff.shop/odata/v1/$metadata#Customer/$entity",
        "Id": 431529,
        "AccountId": 3098,
        "Email": "[email protected]",
        "Password": "",
        "Name": "Trenton Hudson",
        "CreateDate": "2022-12-04T16:44:40.6909701Z",
        "LastModifiedDate": "2022-12-04T16:44:40.6909701Z",
        "LastLoginDate": null,
        "IsActive": true,
        "IsGuest": false,
        "CurrencyCode": "USD",
        "CustomerId": "","TaxExempt": false,
        "OpenAccount": true,
        "EnableCreditCards": true,
        "EnableBudgets": true,
        "EnableDiscounts": true,
        "AllowBillingAddressManagement": false,
        "AllowShippingAddressManagement": false,
        "ForcePasswordReset": true
      }
    },
    {
      "id": "2",
      "status": 201,
      "headers": {
        "location": "https://odata.liftoff.shop/odata/v1/Customer(431530)",
        "content-type": "application/json; odata.metadata=minimal; odata.streaming=true",
        "odata-version": "4.0"
      },
      "body": {
        "@odata.context": "https://odata.liftoff.shop/odata/v1/$metadata#Customer/$entity",
        "Id": 431530,
        "AccountId": 3098,
        "Email": "[email protected]",
        "Password": "",
        "Name": "Marietta Nichols",
        "CreateDate": "2022-12-04T16:44:41.7380893Z",
        "LastModifiedDate": "2022-12-04T16:44:41.7380893Z",
        "LastLoginDate": null,
        "IsActive": true,
        "IsGuest": false,
        "CurrencyCode": "USD",
        "CustomerId": "",
        "TaxExempt": false,
        "OpenAccount": true,
        "EnableCreditCards": true,
        "EnableBudgets": true,
        "EnableDiscounts": true,
        "AllowBillingAddressManagement": false,
        "AllowShippingAddressManagement": false,
        "ForcePasswordReset": true
      }
    },
    {
      "id": "3",
      "status": 200,
      "headers": {
        "content-type": "application/json; odata.metadata=minimal; odata.streaming=true",
        "odata-version": "4.0"
      },
      "body": {
        "@odata.context": "https://odata.liftoff.shop/odata/v1/$metadata#Customer",
        "value": [
          {
            "Id": 431529,
            "AccountId": 3098,
            "Email": "[email protected]",
            "Password": "",
            "Name": "Trenton Hudson",
            "CreateDate": "2022-12-04T16:44:40.6909701Z",
            "LastModifiedDate": "2022-12-04T16:44:40.6909701Z",
            "LastLoginDate": null,
            "IsActive": true,
            "IsGuest": false,
            "CurrencyCode": "USD",
            "CustomerId": "",
            "TaxExempt": false,
            "OpenAccount": true,
            "EnableCreditCards": true,
            "EnableBudgets": true,
            "EnableDiscounts": true,
            "AllowBillingAddressManagement": false,
            "AllowShippingAddressManagement": false,
            "ForcePasswordReset": true
          },
          {
            "Id": 431530,
            "AccountId": 3098,
            "Email": "[email protected]",
            "Password": "",
            "Name": "Marietta Nichols",
            "CreateDate": "2022-12-04T16:44:41.7380893Z",
            "LastModifiedDate": "2022-12-04T16:44:41.7380893Z",
            "LastLoginDate": null,
            "IsActive": true,
            "IsGuest": false,
            "CurrencyCode": "USD",
            "CustomerId": "",
            "TaxExempt": false,
            "OpenAccount": true,
            "EnableCreditCards": true,
            "EnableBudgets": true,
            "EnableDiscounts": true,
            "AllowBillingAddressManagement": false,
            "AllowShippingAddressManagement": false,
            "ForcePasswordReset": true
          }
        ]
      }
    }
  ]
}

📘

Batch requests may contain any combination of API requests.

The example above contains only requests for Customer entities, but a batch request may contain any combination of requests for any combination of entities.