- Make sure to read through Getting and Filtering Data and all subsections on this page to understand what retrieval standards the REST API supports.
- All dates in the REST API are UTC, while the system User Interface dates are time-zone specific (to the profile time zone setting).
- Order data differs from one marketplace to the next - as a result, some properties may be populated, while others are null or blank.
- Response data is limited to a maximum of 20 orders at a time.
- To maintain efficient processing through multiple pages of orders, use the @odata.nextLink at the bottom of the response - do not hardcode $skip values. See more about Paging Through Results.
- Expanding collections in a general orders retrieval (GET /v1/Orders endpoint) will result in a maximum of 20 items per collection.
- For example, if there are more than 20 items in an order, only the first 20 will appear in the initial response data.
- Paging through the items is required using the @odata.nextLink links at the end of each Collection section.
- OR alternately choose to retrieve orders with more than 20 items directly by requesting the order directly (GET /v1/Orders(OrderID)) and expanding collections - all items will be displayed in that response.
- Important data may exist in the PublicNotes, PrivateNotes, and SpecialInstructions fields, but can be updated by the seller as needed.
- Recommend appending changes, rather than overwriting to these fields to ensure the original data in these fields is not lost.
- To build out an efficient and faster integration, we recommend using Export status as a way to mark orders already received/imported.
- Using $filter and any date fields as a way to limit what orders are imported is generally inefficient.
- ChannelAdvisor acknowledges the orders back to the marketplace on the seller's behalf within the allotted timeframe - no acknowledgement request is required by the seller.
- Do not code to specific HTTP response values - these may change. Code to the range if possible (e.g. 200 values are successful responses; 400 values are improperly formatted requests; 500 values are ChannelAdvisor side server errors).
- Add $count=true to the request URI to retrieve the total number of orders matching the query.
- Warning: requesting the count may increase response times by up to 100%, so when paging through results, it is highly recommended to only request the count with the first page, if at all.
Most property types (e.g. 'string' length, integer as 32 bit) are much longer than values we receive from any marketplaces. This is done to accommodate changes that the marketplaces may make.
We recommend development plans be similarly flexible because marketplaces can change the values/formats they use at any time without notice.
- PrivateNotes may contain data from different marketplaces - be sure to get this data before updating it. It may be relevant to business reporting.
- Shipping Carrier and Shipping Class values differ from one marketplace to the next. Find a list of values to expect from each marketplace - if a marketplace doesn't exist in this link, Contact ChannelAdvisor Support by creating a case on the ChannelAdvisor Community.
- The values returned to the marketplace can be customized based on system settings and needs.
- A seller will need to setup (or coordinate with contacts at ChannelAdvisor) to add carrier and class combinations in the ChannelAdvisor User Interface.
- Site Names (and Site IDs) will be static for each marketplace over time. Contact ChannelAdvisor Support by creating a case on the ChannelAdvisor Community if a marketplace doesn't exist in the list.
- OrderTags may be populated with referential data generated by ChannelAdvisor, but cannot be set via API requests with POST/PATCH/PUT.
- Not filterable.
- Distribution Center Type Rollup
- Provides a filterable value representing a summary of the distribution center types that are referenced in the Fulfillments collection in an order.
- Recommend use of these values to limit orders to Seller Managed or Externally Managed Distribution Centers.
- Distribution Center IDs
- Only exists under the Fulfillments collection.
- Only relevant if multiple distribution centers exist in a ChannelAdvisor integration.
- Quantity is set at the Fulfillment level, and the product's Distribution Center ID may be relevant. When retrieving orders, make sure $expand=Fulfillments is added to the URL see the DistributionCenterID value.
- Read more about Distribution Centers and accessing DistributionCenterIDs.
- External Fulfillment Center Codes
- Exists under the Fulfillments collection.
- Only relevant to Amazon FBA (Fulfillment by Amazon) orders
- Does not apply to Multi-Channel FBA orders
- Values are provided exactly as the marketplace defines them
General Expected Behavior
- Required Properties - many POST/PATCH endpoints only require the data point(s) intended to send, so there may be very few required fields in examples. See the Order Entity tables for POST and PATCH requirements.
- Order Item information that comes from the marketplace may not match what exists in our inventory - for example: "Title" will be the value presented by the marketplace to ChannelAdvisor at the time the order was received, and will not necessarily match any title field at ChannelAdvisor.
- Orders data and Product data are independent in our databases, and therefore no single request exists to retrieve Order data and Product-specific data points/attributes/etc.
- We are constantly reviewing and expanding our capabilities, so some Product data points may become available within Orders in the future.
- Order Frequency
- See Marketplace Communication Frequency to find out how often we'll import data from each marketplace, and send refunds/cancellations back to the marketplace.
- For most marketplaces - orders are ready to be retrieved from ChannelAdvisor when:
- PaymentStatus = "Cleared" AND CheckoutStatus = "Completed"
- These two statuses indicate the marketplace has successfully processed the order and completed fraud checks (when applicable)
- Pending Orders do not exist for most marketplaces - Amazon is one exception. Read through this linked page for more information about how to handle pending orders.
Retrieve Order Endpoints
|GET /v1/Orders||Query against all orders across accounts|
|GET /v1/Orders(id)||Retrieve a single order|
|GET /v1/Orders(id)/Items||Retrieve all items for a single order|
Order Components & Collections
|Parent Entity||Collection Name||Property Name||Description|
|Order||OrderItem||Items||Contains all item-level information about the order. |
Most orders with multiple quantity on an item will have the Item provided with total quantity on the item, while some marketplaces (e.g. Walmart - as of Sept 2016) split multiple quantity on same the same item into separate Items, each with single quantity.
Promotions is only populated when promotion data is sent from the marketplace.
|OrderItem||FulfillmentItem||FulfillmentItems||Default FufillmentItem exists under the Fulfillment, but also appears here with ProductID data specific to the items in the order.|
Not useful for most integrations.
|OrderItem||OrderItemAdjustment||Adjustments||Only populated after an item-level refund or cancellation has been applied. Multiple adjustments may exist if multiple refunds or cancellations are applied.|
|OrderItem||BundleComponents||Contains the bundle components of the order when the primary product in the OrderItem is a bundle.|
|OrderItemBundleComponents||FufillmentItem||FulfillmentItems||Default FufillmentItem exists under the Fulfillment, but also appears here with ProductID data specific to the items in the order.|
Not useful for most integrations.
A default fulfillment is created when order is created (unless order is created by seller via API).
|Fulfillment||FulfillmentItem||Items||FulfillmentItem is an collection within the Fulfillment that contains the ProductID and OrderItemId and is the same data found in the same collection in the OrderItem and OrderItemBundleComponents.|
|Order||OrderAdjustment||Adjustments||Only populated after an order-level refund or cancellation has been applied.|
Multiple adjustments may exist if multiple refunds or cancellations are applied.
|Order||CustomField||CustomFields||Only populated when data points are provided that could not be placed in standardized fields.|
This is not a collection, which is why the Property Name is n/a - but it is provided here for reference purposes.
|ShipOrderRequest||ShipOrderRequestItem||Items||A collection within the ShipOrderRequest entity to define specific items for shipment.|
Data at this entity level corresponds with Item-Level shipments.
Important and/or Required Parameters
See our Complete Order Entity Table to see all Order properties and collections expanded with notes on what to expect when retrieving an order.
Retrieve Order Request Examples
- Basic Order Retrieval Requests
- Common Order Retrieval Methods
- Display All Collection Data
- Filter by Multiple Order Level Properties
- Filter Orders by Specific Distribution Center
- Include Distribution Center Data (aka Expand Fulfillments)
- Include Distribution Center Data on FBA Order
- Order Retrieval with Emphasis on Site Account ID
- Orders with Gift Wrap Price & Message
- Retrieve Bundle Order with Components
- Retrieve FBA Orders Only
- Retrieve FBA Orders with Refunds
- Retrieve Non-Exported Orders Including Bundle Orders
- Retrieve Non-FBA Orders Only
- Retrieve Orders with > 20 Items
- Site Name and Order IDs Only for Non-Exported Orders
- Unshipped Orders from a Specific Profile