Retrieve Orders


Considerations

  • 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).
  • Use $count=true within the URI to return the number of records within the response.

Property Information

  • Property Types

    • 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
    • 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
  • 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 Structure

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.
OrderItem Promotion Promotions

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

OrderItemBundleComponent

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.
Order Fulfillment Fulfillments

A default fulfillment is created when order is created (unless order is created by seller via API).
It includes buyer requested (or default) shipping carrier and shipping class for the order.
Requests can be made directly to a Fulfillment Endpoint to make adjustments.
/v1/Orders/Ship endpoint is also used to intelligently update content in the Fulfillment collection.

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.
n/a ShipOrderRequest n/a

This is not a collection, which is why the Property Name is n/a - but it is provided here for reference purposes.
Correlates with the Ship endpoint to efficiently mark orders as shipped.
Data at this entity level corresponds with Order-Level shipments.

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