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>

<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

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