Common Order Retrieval Methods


When to Use

  • Each additional parameter submitted in a request will add additional processing time.

  • Below are several commonly used requests that will generate results with the most important data.

  • We advise reviewing the business needs to ensure everything relevant is captured, and build out more processes to retrieve more specific information in a more efficient manner to meet those business needs.
  • To view the order data for one profile (assuming authorization provides approval to access order data across multiple profiles).

  • To show expanded order information: Item level basic detail, Bundle Components, requested Carrier/Class information.

  • To display only orders that have not already been marked as exported by the Developer Key and Application ID combination.

  • See more on all the options for filtering, querying, expanding data under the Getting and Filtering Data page.
  • For marketplace specific response data to use as reference, see the Marketplace-Specific Order Responses for more information when building out an integration.

Resource URL / Endpoint

GET https://api.channeladvisor.com/v1/Orders
GET https://api.channeladvisor.com/v1/Orders(OrderID)
GET https://api.channeladvisor.com/v1/Orders?$expand={{Insert Collection Names in Comma Separated List}}
GET https://api.channeladvisor.com/v1/Orders?exported={{true or false}}
GET https://api.channeladvisor.com/v1/Orders?$filter=ProfileID eq ProfileID
GET https://api.channeladvisor.com/v1/Orders?$expand={{Insert Collection Names in Comma Separated List}}&exported={{true or false}}&$filter=ProfileID eq ProfileID

Important and/or Required Parameters

Property Required Note
ProfileID Conditionally Include in URL. Required if need to only retrieve orders from a single profile when authorized for multiple profiles.
The ChannelAdvisor generated unique identifier for the Profile.
Replace value with numeric integer representing the ID.
OrderID Conditionally Include in URL. Required to retrieve a specific order. 
The ChannelAdvisor generated unique identifier for the Order.
When specifying the Order ID, the Profile ID is not needed since the Order ID will be unique across all profiles.
Other important/required parameters vary widely based on goals.
Use Order Entitites page to help guide what properties can and cannot be filtered.

Sample Formats

GET https://api.channeladvisor.com/v1/Orders?access_token=xxxxxxxxxx&$expand=Items,Fulfillments&exported=false&$filter=ProfileID eq 12345678

  • Retrieves all non-exported orders on a specific Profile ID, displaying item-level SKU information for the order, and requested Fulfillment information, but does not break out item-level distribution center information within the order.

GET https://api.channeladvisor.com/v1/Orders(108971)?access_token=xxxxxxxxxx&$expand=Items,Fulfillments&$filter=ProfileID eq 12345678

  • Retrieves ChannelAdvisor Order ID 108971, ensuring it comes from this specific Profile ID, and displays item and fulfillment information.
    Note: "exported=False" has been removed from the URL because we are only reaching out for a specific ChannelAdvisor Order ID.


Retrieve all Non-Imported Orders and Display Item Data, Promotion, and Fulfillment Collections

Business Goal: retrieve basic data for orders that have not previously been imported into the system - include marketplace order data, order-level pricing data, buyer shipping and billing addresses, item information, including item pricing, shipment data and taxes on the order, include buyer-requested shipping carrier and class; also include promotional information because we have promotions going on.

Example Request
GET https://api.channeladvisor.com/v1/Orders?access_token=xxxxxxxxxx&exported=false&$expand=Items($expand=Promotions),Fulfillments
Example Response (Success)
200 OK
{
  "@odata.context": "https://api.channeladvisor.com/v1/$metadata#Orders",
  "value": [
		{
		  "@odata.context": "https://api.channeladvisor.com/v1/$metadata#Orders/$entity",
		  "ID": 19993489,
		  "ProfileID": 12345678,
		  "SiteID": 587,
		  "SiteName": "Amazon Seller Central - US",
		  "SiteOrderID": "108-9989137-0000002",
		  "SecondarySiteOrderID": null,
		  "SellerOrderID": null,
		  "CheckoutSourceID": null,
		  "CreatedDateUtc": "2016-06-27T13:24:55.85Z",
		  "ImportDateUtc": "2016-06-27T13:24:56.56Z",
		  "PublicNotes": null,
		  "PrivateNotes": "",
		  "SpecialInstructions": "",
		  "TotalPrice": 17,
		  "TotalTaxPrice": 1,
		  "TotalShippingPrice": 6,
		  "TotalShippingTaxPrice": null,
		  "TotalInsurancePrice": 0,
		  "TotalGiftOptionPrice": 0,
		  "TotalGiftOptionTaxPrice": null,
		  "AdditionalCostOrDiscount": 0,
		  "EstimatedShipDateUtc": null,
		  "DeliverByDateUtc": null,
		  "ResellerID": null,
		  "FlagID": 0,
		  "FlagDescription": null,
		  "OrderTags": null,
		  "DistributionCenterTypeRollup": "SellerManaged",
		  "CheckoutStatus": "Completed",
		  "PaymentStatus": "Cleared",
		  "ShippingStatus": "Unshipped",
		  "CheckoutDateUtc": "2016-06-27T13:24:55.85Z",
		  "PaymentDateUtc": "2016-06-27T13:24:55.85Z",
		  "ShippingDateUtc": null,
		  "BuyerUserId": "amazon_random_email@marketplace.amazon.com",
		  "BuyerEmailAddress": "amazon_random_email@marketplace.amazon.com",
		  "BuyerEmailOptIn": false,
		  "OrderTaxType": "NoTax",
		  "ShippingTaxType": "NoTax",
		  "GiftOptionsTaxType": "NoTax",
		  "PaymentMethod": "Amazon",
		  "PaymentTransactionID": null,
		  "PaymentPaypalAccountID": null,
		  "PaymentCreditCardLast4": "",
		  "PaymentMerchantReferenceNumber": null,
		  "ShippingTitle": null,
		  "ShippingFirstName": "John",
		  "ShippingLastName": "Doe",
		  "ShippingSuffix": null,
		  "ShippingCompanyName": null,
		  "ShippingCompanyJobTitle": null,
		  "ShippingDaytimePhone": "1234567890",
		  "ShippingEveningPhone": null,
		  "ShippingAddressLine1": "1234 Main Street",
		  "ShippingAddressLine2": "",
		  "ShippingCity": "Anytown",
		  "ShippingStateOrProvince": "FL",
		  "ShippingPostalCode": "33813-4545",
		  "ShippingCountry": "US",
		  "BillingTitle": null,
		  "BillingFirstName": "John",
		  "BillingLastName": "Doe",
		  "BillingSuffix": "",
		  "BillingCompanyName": "",
		  "BillingCompanyJobTitle": null,
		  "BillingDaytimePhone": "1234567890",
		  "BillingEveningPhone": null,
		  "BillingAddressLine1": "1234 Main Street",
		  "BillingAddressLine2": "",
		  "BillingCity": "Anytown",
		  "BillingStateOrProvince": "FL",
		  "BillingPostalCode": "33813-4545",
		  "BillingCountry": "US",
		  "PromotionCode": null,
		  "PromotionAmount": 0,
		  "Items": [
			{
			  "ID": 22313195,
			  "ProfileID": 12345678,
			  "OrderID": 19993489,
			  "ProductID": 22120969,
			  "SiteOrderItemID": "",
			  "SiteListingID": "141964888",
			  "Sku": "CG0001",
			  "Title": "Colby Germond Create Test Product CG0001",
			  "Quantity": 2,
			  "UnitPrice": 10,
			  "TaxPrice": 1,
			  "ShippingPrice": 6,
			  "ShippingTaxPrice": 0,
			  "RecyclingFee": 0,
			  "GiftMessage": null,
			  "GiftNotes": null,
			  "GiftPrice": 0,
			  "GiftTaxPrice": 0,
			  "IsBundle": false,
			  "ItemURL": "",
			  "Promotions": [
				{
				  "ID": 2389,
				  "Code": "TestPromoCode",
				  "Amount": -10,
				  "ShippingAmount": 0
				}
			  ]
			}
		  ],
		  "Fulfillments": [
			{
			  "ID": 11356614,
			  "ProfileID": 12345678,
			  "OrderID": 19993489,
			  "CreatedDateUtc": "2016-06-27T13:24:55.85Z",
			  "UpdatedDateUtc": "2016-06-27T13:24:56.737Z",
			  "Type": "Ship",
			  "DeliveryStatus": "NoChange",
			  "TrackingNumber": null,
			  "ShippingCarrier": null,
			  "ShippingClass": null,
			  "DistributionCenterID": 149,
			  "ShippedDateUtc": null,
			  "SellerFulfillmentID": null
			}
		  ]
		},
		{
		// Next Product Data
		}
	  ],
  "@odata.nextLink": "https://api.channeladvisor.com/v1/Orders?access_token=xxxxxxxxxx&exported=false&$expand=Items%28%24expand%3DPromotions%29%2CFulfillments&$skip=20"
}


Retrieve Specific Order and Display Only Item and Promotion Data

Business Goal: retrieve a specific order and only display item information, show promotional data because we have promotions going on.

Example Request
GET https://api.channeladvisor.com/v1/OrderItems?access_token=xxxxxxxxxx&$expand=Promotions&$filter=Promotions/Any (c:c/ID ne null) and OrderID eq 19993487
Example Response (Success)
200 OK
{
  "@odata.context": "https://api.channeladvisor.com/v1/$metadata#OrderItems",
  "value": [
    {
      "ID": 22313193,
      "ProfileID": 12345678,
      "OrderID": 19993487,
      "ProductID": 22120969,
      "SiteOrderItemID": "",
      "SiteListingID": "141964875",
      "Sku": "CG0001",
      "Title": "Test Product CG0001",
      "Quantity": 2,
      "UnitPrice": 10,
      "TaxPrice": 1,
      "ShippingPrice": 6,
      "ShippingTaxPrice": 0,
      "RecyclingFee": 0,
      "GiftMessage": null,
      "GiftNotes": null,
      "GiftPrice": 0,
      "GiftTaxPrice": 0,
      "IsBundle": false,
      "ItemURL": "",
      "Promotions": [
        {
          "ID": 2389,
          "Code": "TestPromoCode",
          "Amount": 0,
          "ShippingAmount": -5
        }
      ]
    }
  ]
}


Retrieve Fulfillment Information On a Specific Order

Business Goal: retrieve a specific order's fulfillment information only, displaying item level data. Note: fulfillments do not display "Sku" - they only display 'OrderItemId' and the ChannelAdvisor 'ProductID'.

Example Request
GET https://api.channeladvisor.com/v1/Fulfillments?access_token=xxxxxxxxxx&$filter=OrderID eq 19993487&$expand=Items
Example Response (Success)
200 OK
{
  "@odata.context": "https://api.channeladvisor.com/v1/$metadata#Fulfillments",
  "value": [
    {
      "ID": 11356612,
      "ProfileID": 12345678,
      "OrderID": 19993487,
      "CreatedDateUtc": "2016-06-27T13:23:11.407Z",
      "UpdatedDateUtc": "2016-06-27T13:23:15.07Z",
      "Type": "Ship",
      "DeliveryStatus": "NoChange",
      "TrackingNumber": null,
      "ShippingCarrier": null,
      "ShippingClass": null,
      "DistributionCenterID": 149,
      "ShippedDateUtc": null,
      "SellerFulfillmentID": null,
      "Items": [
        {
          "ID": 7368136,
          "ProfileID": 12345678,
          "FulfillmentID": 11356612,
          "OrderID": 19993487,
          "OrderItemID": 22313193,
          "Quantity": 2,
          "ProductID": 22120969
        }
      ]
    }
  ]
}


Order Error Responses

Example Response (Failure)
GET https://api.channeladvisor.com/v1/Orders?access_token=xxxxxxxxxx&$expand=Item,Fulfillments
"Item" is not a valid property
 
400 Bad Request
{
  "error": {
    "code": "",
    "message": "The query specified in the URI is not valid. Could not find a property named 'Item' on type 'ChannelAdvisor.RestApi.V1.Models.Order'."
  }
}
Example Response (Failure)
GET https://api.channeladvisor.com/v1/Orders?access_token=xxxxxxxxxx&$expand=Items,Fulfillments&$filter=ProfileID eq 12345678
ProfileID is not in the approved profiles for this authorization.
 
400 Bad Request
{
  "error": {
    "code": "10169068",
    "message": "Attempted to perform an unauthorized operation."
  }
}