Developer API – Orders
GetOrders
Returns order data from your ChannelUnity account based on the given channel and filters.
Input
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | <ChannelUnity> <MerchantName>merch</MerchantName> <Authorization>TWF0dFR...==</Authorization> <ApiKey>123123123</ApiKey> <RequestType>GetOrders</RequestType> <SourceURL><![CDATA[http://]]></SourceURL> <Payload> <SubscriptionID>304778</SubscriptionID> <FilterStatus>Cancelled</FilterStatus> <FilterFlags>AMAZON_FBA</FilterFlags> <DateFrom>2018-04-10</DateFrom> <DateTo>2018-04-11</DateTo> <UpdateDateFrom>2018-04-10 17:00:00</UpdateDateFrom> <Offset>0</Offset> <Count>10</Count> </Payload> </ChannelUnity> |
Important: The SubscriptionID refers to the channel you want to get the orders for. It is actually referred to as the SettingsLinkId field when you run a ValidateUser call. The SubscriptionID in the ValidateUser call should be ignored.
Set the FilterStatus to one of the ChannelUnity order statuses to retrieve orders of that status.
To get orders which are fulfilled by Amazon, use AMAZON_FBA for the FilterFlags. Otherwise leave this blank.
Set the offset to zero to retrieve the 1st, 2nd, 3rd orders and so on.
Set the offset to 10 to retrieve the 11th, 12th, 13th order and so on.
Set the count to the number of orders you want to retrieve. This number must be between 1 and 1000.
If you want to filter by purchase date, use the <DateFrom> tag. You must use the format yyyy-mm-dd, for example 2018-04-10 is the 10th of April 2018. This will return orders placed on the marketplace on or after this date.
If also using <DateTo> tag, the same format applies.
It is also possible to filter the orders by the last time the order was updated in ChannelUnity. The field to filter by is called UpdateDateFrom. The format should be yyyy-mm-dd hh:mm:ss
This can be used in conjunction with the other filters. So you can request orders from 2019-02-01, but which have been updated after 2019-02-05 12:00:00.
Output
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 | <ChannelUnity> <Order> <OrderId>106</OrderId> <RemoteOrderId><![CDATA[122-11124242-133]]></RemoteOrderId> <ServiceSku><![CDATA[CU_AMZ_COM]]></ServiceSku> <PurchaseDate><![CDATA[2016-02-20T06:11:57+00:00]]></PurchaseDate> <Currency><![CDATA[USD]]></Currency> <ShipRecipientName><![CDATA[Fred Johnson]]></ShipRecipientName> <ShipEmail></ShipEmail> <ShipAddress1><![CDATA[1145 Sunset Blvd]]></ShipAddress1> <ShipAddress2></ShipAddress2> <ShipAddress3></ShipAddress3> <ShipCity><![CDATA[West Hollywood]]></ShipCity> <ShipState><![CDATA[CA]]></ShipState> <ShipPostalcode><![CDATA[90068-1348]]></ShipPostalcode> <ShipCountry><![CDATA[US]]></ShipCountry> <ShipPhoneNumber>5550001555</ShipPhoneNumber> <ShipPrice>0.00</ShipPrice> <ShipTax>0.00</ShipTax> <ShipService><![CDATA[Econ Cont US]]></ShipService> <ShipDeliveryInstructions></ShipDeliveryInstructions> <OrderStatus><![CDATA[Complete]]></OrderStatus> <OrderFlags></OrderFlags> <PayPalTransactionID>BIXCWOQ9100910059862</PayPalTransactionID> <EbayRecordNumber>1001</EbayRecordNumber> <PaymentMethod>PayPal</PaymentMethod> <GiftWrapPrice>0.00</GiftWrapPrice> <GiftWrapTax>0.00</GiftWrapTax> <GiftWrapType></GiftWrapType> <GiftMessage></GiftMessage> <BuyerName><![CDATA[Bob J]]></BuyerName> <BuyerEmail><![CDATA[bob.j@channelunity.com]]></BuyerEmail> <BuyerPhoneNumber></BuyerPhoneNumber> <GrandTotal>24.99</GrandTotal> <OrderTax>0.00</OrderTax> <OrderItems> <Item> <SKU><![CDATA[BWODF10181]]></SKU> <Name><![CDATA[Quality T-Shirt]]></Name> <Qty>1.000</Qty> <Price>24.99</Price> <Tax>0.00</Tax> </Item> </OrderItems> </Order> <!-- Order element repeated for each order --> <Status>OK</Status> </ChannelUnity> |
Each Order returned contains the following elements.
Element name | Description |
---|---|
OrderId | The ChannelUnity internal order number for the current ChannelUnity merchant account. You may use this if you want to store a simple integer order number for ChannelUnity orders, otherwise you may safely ignore this value. |
RemoteOrderId | The order number as provided by the marketplace. The format of this value varies based on the marketplace. |
ServiceSku | This indicates the marketplace from which the order originated. Please see Appendix: Channel types for all the possible values. |
PurchaseDate | The date the customer placed this order on the marketplace. |
Currency | The currency of all the price and tax amounts in the current order. This is the standard 3-letter currency code as defined by ISO 4217. |
ShipRecipientName | The name on the shipping address. |
ShipEmail | The email address associated with the shipping details. |
ShipAddress1 | Shipping address line 1. |
ShipAddress2 | Shipping address line 2 (may not be populated). |
ShipAddress3 | Shipping address line 3 (may not be populated). |
ShipCity | Shipping address city. |
ShipState | Shipping address state/county. |
ShipPostalcode | Shipping postal code. |
ShipCountry | Shipping address country (as a 2 letter country code). |
ShipPhoneNumber | Phone number associated with the shipping address. |
ShipPrice | Cost of shipping. |
ShipTax | Tax associated with the shipping cost. |
ShipService | The shipping service passed from the marketplace. ChannelUnity passes through this information from the marketplace verbatim. |
ShipDeliveryInstructions or BuyerCheckoutMessage | Optional delivery instructions that the customer specified, such as “If out leave with the neighbour”. |
OrderStatus | This indicates the current status of the order. Valid order statuses are in the appendix. |
OrderFlags | Contains information which is marketplace-specific such as whether the order has been fulfilled by Amazon. In this case the value of OrderFlags is AMAZON_FBA. |
PayPalTransactionID | If the customer paid via PayPal, this is the PayPal transaction ID (eBay only). |
EbayRecordNumber | The order record number for the eBay order (if applicable). |
PaymentMethod | The method by which the customer paid for the order. Options include PayPal, CreditCard (currently eBay only). |
GiftWrapPrice | Price of the gift wrapping if any. |
GiftWrapTax | Tax associated with the gift wrap cost if any. |
GiftWrapType | The type of the gift wrap if applicable. |
GiftMessage | The gift message if applicable. |
BuyerName | The name of the person on the billing address. |
BuyerEmail | The email address associated with the billing address. |
BuyerPhoneNumber | The phone number associated with the billing address. |
GrandTotal | The grand total of the order including shipping, but not including tax. |
OrderTax | The amount of the order total which is tax. |
OrderItems | This is a collection of Items, one for each unique SKU. SKU: SKU of the product ordered. Name: Product name at the time of the order. Qty: Qty ordered. Price: The Price is the per item price for each single unit. Tax: The Tax element is only populated when there is a country or state-specific sales tax (e.g. in the United States). European style VAT is included in the Price element. |
OrderStatusUpdate
Allows an order’s status to be updated. Either the order can be shipped (with or without tracking details), or the order can be cancelled. The corresponding marketplace channel is updated accordingly. To mark an order as shipped use OrderStatus “Complete”. To cancel an order use OrderStatus “Cancelled”.
The SubscriptionID refers to the marketplace channel the order belongs to.
The OrderID is the order ID given to the order by the marketplace (matches the OrderID element from OrderNotification, and RemoteOrderID from GetOrders).
To provide tracking information you may provide the following optional fields.
Field | Description |
---|---|
CarrierName | The name of the shipping carrier. This may be plain text. |
ShipmentDate | Date and time (in GMT timezone) of the time the shipment occurred. |
ShipmentMethod | Shipping method used to deliver the item. For example “First Class” or “Second Day”. |
TrackingNumber | The carrier specific tracking number for the shipment. |
Please note although tracking is optional, all 3 of CarrierName, ShipmentMethod and TrackingNumber must be supplied for tracking to be sent successfully.
Input
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | <ChannelUnity> <MerchantName>merch</MerchantName> <Authorization>TWF0dFR...==</Authorization> <ApiKey>123123123</ApiKey> <RequestType>OrderStatusUpdate</RequestType> <Payload> <SubscriptionID>12</SubscriptionID> <OrderID>1122512-5522114-655625</OrderID> <OrderStatus>Complete</OrderStatus> [ Start of optional shipment data ] <ShipmentDate>2013-01-02T16:11:33+00:00</ShipmentDate> <CarrierName>Royal Mail</CarrierName> <ShipmentMethod>First Class</ShipmentMethod> <TrackingNumber>GB0000456465</TrackingNumber> [ End of optional shipment data ] </Payload> </ChannelUnity> |
Output
1 2 3 | <ChannelUnity> <Status>OK</Status> </ChannelUnity> |
DoPartialAction
Performs a partial refund of an order, or a partial shipment of an order. The example below illustrates one partial refund and one partial shipment in a single message. i.e. Each DoPartialAction message can contain more than one PartialActionItem.
The SubscriptionID refers to the marketplace channel the order belongs to.
The OrderID is the order ID given to the order by the marketplace (matches the OrderID element from GetOrders).
The PartialActionDate is the date and time (in GMT timezone) of the time the shipment or cancellation occurred.
Each PartialActionItem may contain the following data.
Field | Description |
---|---|
Action | Valid values are “Ship” and “Refund”. |
SKU | The SKU affected by this action. Must match the SKU exactly from the given order data. |
QtyAffected | Numerical integer value describing the number of qty of this SKU that is affected. |
Amount | For a refund, the amount on this order that should be refunded. The amount is always in the currency as the original order. |
ShipCarrier | The name of the shipping carrier. This is a plain text field. |
ShipTracking | The carrier-specific tracking number. |
Input
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | <ChannelUnity> <MerchantName>merch</MerchantName> <Authorization>TWF0dFR...==</Authorization> <ApiKey>123123123</ApiKey> <RequestType>DoPartialAction</RequestType> <Payload> <SubscriptionID>12</SubscriptionID> <OrderID>1122512-5522114-655625</OrderID> <PartialActionDate>2013-01-02 16:11:33</PartialActionDate> <PartialActionItem> <Action>Ship</Action> <SKU>AI022</SKU> <QtyAffected>1</QtyAffected> [ Start of optional shipment data ] <ShipCarrier>DHL</ShipCarrier> <ShipTracking>YU7822341</ShipTracking> [ End of optional shipment data ] </PartialActionItem> <PartialActionItem> <Action>Refund</Action> <Amount>1.92</Amount> <SKU>AI082</SKU> <QtyAffected>1</QtyAffected> </PartialActionItem> [ <PartialActionItem> element repeated as required ] </Payload> </ChannelUnity> |
Output
1 2 3 | <ChannelUnity> <Status>OK</Status> </ChannelUnity> |