Batch Requests


Background

  • To understand Batch Processing under OData standards, please read: http://www.odata.org/documentation/odata-version-3-0/batch-processing/
  • It is recommended batching no more than 100 requests at a time regardless of what action is being performed (GET, PUT, POST, etc)
  • If requests timeout, scale back the number of requests being batched together.
  • The batch as well as the requests within the body of the batch all count toward request limits, therefore batches are actually more expensive than individual requests with regard to request limits.
  • The /v1/Orders(ID)/Export endpoint is not compatible with batch requests.
  • Take note of line breaks within the examples - they are critical for batch requests to execute properly.

Alternate Methods Required

We have a few aliased endpoints that will not work in $batch requests, so the real URI must be used instead. These, along with complete requirements around the endpoint are referenced on the individual example pages for Attributes, Images, Labels, Bundles, and Quantity:

Endpoint Not Supported in $batchReal URI Supported in $batch
PATCH or PUT /v1/Products(ID)/Attributes('AttributeName')

POST /v1/AttributeValues to update a single attribute
OR
POST /v1/Products(ID)/UpdateAttributes to update a single or multiple attributes
OR
PATCH or PUT /v1/AttributeValues(ProductID=ID, Name='Attribute Name') to update a single attribute

DELETE
/v1/Products(ID)/Attributes('AttributeName')
DELETE
/v1/AttributeValues(ProductID=ID, Name='Attribute Name')
PATCH, PUT, or DELETE
/v1/Products(ID)/Images('PlacementName')

PATCH, PUT, or DELETE
/v1/Images(ProductID=ID, PlacementName='Placement Name')

PATCH, PUT, or DELETE
/v1/Products(ID)/Labels('LabelName')
PATCH, PUT, or DELETE
/v1/ProductLabels(ProductID=ID, Name='Label Name')
PATCH, PUT, or DELETE
/v1/Products(ID)/BundleComponents(ComponentID)
PATCH, PUT, or DELETE
/v1/ProductBundleComponents(ProductID=ID, ComponentID=Component ID)
PATCH, PUT, or DELETE
/v1/Products(ID)/DCQuantities(DC Id)
PATCH, PUT, or DELETE
/v1/DCQuantities(ProductID=ID, DistributionCenterID=DC Id)

Resource URL / Endpoint

POST https://api.channeladvisor.com/v1/$batch

Important and/or Required Headers

HeaderValueRequiredDescription
Content-Type multipart/mixed; boundary=changesetRequired

Defines the MIME content to be delivered. Since the content will vary by the requests included, this allows for multiple parts to be defined within the body.
The value "changeset" is used as the batch delimiter within the body (see examples). This can be changed to any consistent value (without special characters or spaces) as long as the batch delimiter in the body are changed to match.

Important and/or Required Parameters in the Body

*not a literal value - see Description for more detail

ValueRequiredDescription
--batchRequired

Defines the beginning of the batch.

Content-Type: multipart/mixed; boundary=changesetRequiredDefines the batching MIME content.
--changeset
Required

Defines the first request within the batch. Repeat this between each request. 
If the Header of the request defines something other than boundary=changeset, this value must be identical for the request to execute. 

Content-Type: application/httpRequiredDefines the batching MIME content for processing the request within the batch.
This same format will be used for every changeset in the batch request.
Content-Transfer-Encoding: binaryRequiredDefines the transfer encoding to ensure it is processed accurately.
Content-ID*RequiredNumeric value representing the request being made. Simple integer in increasing value, not duplicated within the batch request.
For example: Content-ID: 1 is the first changeset; Content-ID: 2 is the second changeset, and so on.
Insert NewlineRequiredInsert a newline here to ensure accurate processing.
Method and URL/Endpoint with Required IDs*RequiredThe full URL of the request as provided in an individual request format.
Do not forget to include any IDs or string values formatted properly.
For example: PUT https://api.channeladvisor.com/v1/Fulfillments(11353895) HTTP/1.1
Content-Type: application/jsonConditionalRequired if the request is a POST/PUT/PATCH and contains a body.
Format/required properties and values will vary by the request being made.
This will be required for the individual changeset request to work.
Insert NewlineRequiredInsert a newline here to ensure accurate processing.
Body Content in JSON format*ConditionalRequired if the request is a POST/PUT/PATCH and contains a body.
Format/required properties and values will vary widely by the request being made.
This will be required for the individual changeset request to work.
Insert NewlineRequiredInsert a newline here to ensure accurate processing.
--changeset--RequiredDefines the end of the changeset.
--batch--RequiredDefines the end of the batch.

Batch Request Examples