Working with Orders

Endpoint Description
https://api.channeladvisor.com/v1/orders Provides access to the account's orders, including order details, shipments/fulfillments, cancellations, and refunds.

Parts of an Order

An order in the ChannelAdvisor system has the following parts:

Part Description
Order The details of an order.
OrderItem The purchased items belonging to an Order.
BundleComponent When a purchased item is a bundle, the bundle component data exists as a property within the OrderItem and includes basic SKU and quantity information of the products that comprise the bundle.
Fulfillment At least one fulfillment is created with every Order and includes the requested shipping carrier/class. This can be updated when marking the order shipped or modifying the fulfillment directly. New fulfillments can be created as needed.
FulfillmentItem The items to be fulfilled that belong to a Fulfillment. Multiple FulfillmentItems may exist if multiple items are part of an order.

Actions

Using the Orders and other related endpoints, perform the following operations and more:

Flow of Order Processing

The Order and Fulfillment retrieval and update process usually flows something like this with the REST API:

  1. Order is placed on a marketplace
  2. Order is retrieved from the marketplace by ChannelAdvisor
    1. ChannelAdvisor will acknowledge and confirm receipt of the order as necessary within the time frame required by the marketplaces
    2. Generally speaking, orders are retrieved from marketplaces every 15 minutes
  3. Client will retrieve a group of orders that haven't already been imported into their system
    1. See Common Order Retrieval Methods for some of the more common order retreivals and filters.
    2. For different marketplace-specific examples: Marketplace-Specific Order Responses
  4. Once those orders have been imported into their system successfully, client should mark them as Exported in the API (each order must be marked as exported individually)
    1. See Exported & Non-Exported Orders
  5. Orders may be completed in three ways:

    SHIP
    the Order
    1. Prepare the item for shipment
    2. Mark items/fulfillments as shipped and send shipping/tracking information
      1. See options to execute this at Shipments & Fulfillments sections and review options based on needs.
      2. The API can intelligently handle partial shipments as separate requests with item-level detail, and create new fulfillments based on requests defined in the Shipments section.
    CANCEL the Order
    1. If a check against internal stock is necessary, run this check first
      1. If the item is out of stock, send an adjustment back on the Item that was out of stock.
      2. If the item is in-stock but the order needs to be canceled for some other reason, make the same request as above, but utilize a different reason for the adjustment.
        • Note: Neither of these are desired outcomes - any seller-side cancellation will result in negative seller feedback.
    2. The API knows the status of the order - if the item has not been marked as shipped, it will be handled as a cancellation.
    3. Important Note: not all marketplaces allow cancellations, or may only allow certain types of cancellations (e.g. partial order cancellations may not be allowed). See Cancellations & Refunds for a more complete view of options

    REFUND the Order

    1. Once a seller receives an order, they may want to return the item for a refund.
    2. If the buyer requests a refund, internal steps may be necessary first, but ultimately the API process is nearly identical to the cancellation process outlined above.
    3. Two primary differences are the 'Reason' sent in the body of the request AND in the fact that the item has already been marked as shipped. The API will analyze these pieces of data and deliver the appropriate data back to the marketplace.
    4. Important Notes
      1. Not all marketplaces allow all different kinds of refunds (e.g. partial quantity item refunds may not be allowed). See Cancellations & Refunds for a more complete view of options.
      2. The concept of exchanges does not currently exist in any marketplace and is not supported in the ChannelAdvisor system. If the buyer wishes to exchange a product for a different size/color/etc, communication may happen between the seller and the buyer without order adjustment information being passed to ChannelAdvisor or the marketplace.