Developer API – Callbacks

This section contains all the available callbacks that the ChannelUnity Connector Kit implementation can expect to receive.

The type of notification is always indicated in an element named “Type” which is a child of the “Notification” element.

CartDataRequest

This notification is sent to the cart connector when the ChannelUnity account is ready to receive the list of stores, categories and attributes. The implementation should be to simply invoke each of the StoreData, CategoryData and ProductAttributes calls and return the statuses for each.

Input

1
2
3
4
5
6
7
8
<ChannelUnity>
   <Notification>
       <Type>CartDataRequest</Type>
       <ID>507257</ID>
       <URL>http://94.193.1.2/channelunity/api/index</URL>
       <Timestamp>2013-01-21 09:45:14</Timestamp>  
   </Notification>
</ChannelUnity>

Output

1
2
3
4
5
<ChannelUnity>
   <StoreStatus><Status>OK</Status></StoreStatus>
   <CategoryStatus>OK</CategoryStatus>
   <ProductAttributeStatus>OK</ProductAttributeStatus>
</ChannelUnity>

GetAllSKUs

When the connector kit receives this notification it should respond with a list of all SKUs currently available in the product catalog. When ChannelUnity receives a non-empty SKU list, any SKUs in the ChannelUnity account that are not in the full SKU list will be removed from the ChannelUnity account.

Input

1
2
3
4
5
6
7
8
<ChannelUnity>
   <Notification>
       <ID>50f9de15b9363</ID>
       <Timestamp>18-01-2013 23:43:17</Timestamp>
       <Type>GetAllSKUs</Type>
       <Payload></Payload>
   </Notification>
</ChannelUnity>

Output

1
2
3
4
5
6
7
8
9
10
11
<ChannelUnity>
   <RequestType>GetAllSKUs</RequestType>
   <Payload>
   <SKU>D2484</SKU>
   <SKU>T22584</SKU>
   <SKU>D2411</SKU>
   <SKU>P2004</SKU>
<!--  SKU element repeated for each SKU  -->
 
   </Payload>
</ChannelUnity>

OrderNotification

This notification is sent to the cart when an order is placed on one of the marketplace channels connected to the CU account. This is also sent when the status of an order changes. Valid order statuses are in the appendix.

Input

1
2
3
4
5
6
7
8
<ChannelUnity>
    <Notification>
        <ID>50fdd17aeefdf</ID>
        <Timestamp>21-01-2013</Timestamp>
        <Type>OrderNotification</Type>
        <Payload>P+V...abg==</Payload>
    </Notification>
</ChannelUnity>

Input payload example

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
49
50
51
52
53
54
55
56
57
58
59
<MerchantName>matttest123</MerchantName>
<SourceId></SourceId>
<FriendlyName>My Store</FriendlyName>
<URL>http://94.193.82.158</URL>
<MainCountry></MainCountry>
<FrameworkType>Custom</FrameworkType>
<WebsiteId>1</WebsiteId>
<StoreId>1</StoreId>
<StoreviewId>1</StoreviewId>
<SubscriptionId>13</SubscriptionId>
<SkuAttribute>sku</SkuAttribute>
<Orders>
   <Order>
       <ServiceSku>CU_AMZ_UK</ServiceSku>
       <OrderId>112211-08888-9913813</OrderId>
       <PurchaseDate>2012-11-01 12:12:13</PurchaseDate>
       <Currency>GBP</Currency>
       <OrderFlags></OrderFlags>
       <OrderStatus>Processing</OrderStatus>
       <ShippingInfo>
           <RecipientName><![CDATA[Mr Test]]></RecipientName>
           <Email><![CDATA[m2048@amazon.co.uk]]></Email>
           <Address1><![CDATA[1 High St]]></Address1>
           <Address2><![CDATA[]]></Address2>
           <Address3><![CDATA[]]></Address3>
           <City><![CDATA[Manchester]]></City>
           <State><![CDATA[Manchester]]></State>
           <PostalCode><![CDATA[M1 1AA]]></PostalCode>
           <Country><![CDATA[GB]]></Country>
           <PhoneNumber><![CDATA[01612202222]]></PhoneNumber>
           <ShippingPrice>1.99</ShippingPrice>
           <ShippingTax>0.00</ShippingTax>
           <Service><![CDATA[]]></Service>
           <DeliveryInstructions><![CDATA[]]></DeliveryInstructions>
           <GiftWrapPrice>0.00</GiftWrapPrice>
           <GiftWrapTax>0.00</GiftWrapTax>
           <GiftWrapType></GiftWrapType>
           <GiftMessage><![CDATA[]]></GiftMessage>
       </ShippingInfo>
       <BillingInfo>
           <Name><![CDATA[Mr Buyer]]></Name>
           <Email><![CDATA[unknown@channelunity.com]]></Email>
           <PhoneNumber><![CDATA[]]></PhoneNumber>
       </BillingInfo>
       <OrderItems>
           <Item>
               <SKU><![CDATA[D532]]></SKU>
               <Name><![CDATA[My widget]]></Name>
               <Quantity>1.000</Quantity>
               <Price>10.00</Price>
               <Tax>0.00</Tax>
           </Item>
<!--  Item element repeated for each unique SKU in the order  -->
 
       </OrderItems>
   </Order>
<!--  Order element repeated for each order  -->
 
</Orders>

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.

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 this is included in the Price element. The Price is the per item price for each single unit.

Other XML elements passed through are as follows:

TotalInvoiceAmountThe total amount charged to the customer, i.e. the grand total of the order including shipping.
StockReservedCartA value of either 0 or 1 indicating whether ChannelUnity has deducted the stock for the products on this order from the connected shopping cart.
This is done only if the OrderNotification callback is implemented, and the order is currently in an OnHold state.
Stock is then reserved until the order moves into Processing status.
Implementation of stock reservation is not required. 
BuyerCheckoutMessageOptional delivery instructions that the customer specified, such as “If out leave with the neighbour”.

Output

Return an Imported element for each order which is successfully received, and an Exception and NotImported element for each order not successfully received. The value in the element is the remote order ID which identifies the order. If the order is not imported, CU will attempt to send the order again in the next 2 minutes.

1
2
3
4
5
6
<ChannelUnity>
 <Imported>11100011-662200-22111</Imported>
 <Imported>11100011-662200-22510</Imported>
 <Exception>Order not stored successfully.</Exception>
 <NotImported>11100011-662200-22510</NotImported>
</ChannelUnity>

Ping

This request is sent from ChannelUnity to the cart to ensure the credentials provided within the cart installation are adequate to make API calls.

When receiving a Ping, the cart should attempt a ValidateUser request and return whether or not this call was successful.

Input

1
2
3
4
5
6
7
8
<ChannelUnity>
   <Notification>
       <ID>50f9de15b9363</ID>
       <Timestamp>18-01-2013 23:43:17</Timestamp>
       <Type>Ping</Type>
       <Payload></Payload>
   </Notification>
</ChannelUnity>

Output

1
2
3
<ChannelUnity>
   <Status>OK</Status>
</ChannelUnity>

ProductData (callback)

This notification is sent when ChannelUnity requires to obtain product data for the account. Use the VerifyNotification call to decrypt the payload.

Input

1
2
3
4
5
6
7
8
<ChannelUnity>
   <Notification>
       <ID>50f9de15f1e84</ID>
       <Timestamp>18-01-2013 23:43:17</Timestamp>
       <Type>ProductData</Type>
       <Payload>P+V....HbM=</Payload>
   </Notification>
</ChannelUnity>

Input payload example

1
2
3
4
5
6
7
8
9
10
<MerchantName>matttest123</MerchantName>
<RangeFrom>750</RangeFrom>
<SourceId>1</SourceId>
<FriendlyName>My Store</FriendlyName>
<URL>http://94.1.1.158</URL>
<MainCountry></MainCountry>
<FrameworkType>Custom</FrameworkType>
<WebsiteId>1</WebsiteId>
<StoreId>1</StoreId>
<StoreviewId>1</StoreviewId>

Output

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<ChannelUnity>
   <RequestType>ProductData</RequestType>
   <Payload>
   <Products>
   <Product>
       <RemoteId>751</RemoteId>
       <SourceURL>http://94.193.82.158:80/</SourceURL>
       <StoreViewId>0</StoreViewId>
       <ProductType>Default</ProductType>
       <Title>My widget</Title>
       <Description>This does bla bla</Description>
       <SKU>D123</SKU>
       <Price>11.99</Price>
       <Quantity>10</Quantity>
       <Category>2</Category>
       <CategoryName>Cat123</CategoryName>
       <Image>http://www.aaa/12/badge-industry-bronze.jpg</Image>
   </Product>
   <RangeNext>0</RangeNext>
   <TotalProducts>1</TotalProducts>
   </Products>
   </Payload>
</ChannelUnity>

The returned product data should include the total number of products available. The RangeNext should contain an ID which is passed back to the connector kit from ChannelUnity when the next range of products is needed. This allows the connector kit to provide products to ChannelUnity in batches for when there is a large amount of products.

If you want to sell on marketplaces but don't yet have an online store, Synchromatic is the solution for you.
More Details