Order Data Integration with DemandStream
Getting Started Guide
Rev 2.1
Contents
1.
2.
Order Process Overview ....................................................................................................................... 2
1.1.
Order Report ................................................................................................................................. 2
1.2.
Acknowledgement Feed ............................................................................................................... 2
1.3.
Fulfillment Feed ............................................................................................................................ 3
1.4.
Adjustment Feed ........................................................................................................................... 4
Feed Development ................................................................................................................................ 4
2.1.
3.
Reference Documentation ............................................................................................................ 4
Sample Feeds using XML ....................................................................................................................... 5
3.1.
Order Report XML Sample ............................................................................................................ 5
3.2.
Order Acknowledgement XML Sample ......................................................................................... 6
3.3.
Order Fulfillment XML Sample ...................................................................................................... 7
3.4.
Order Adjustment XML Sample .................................................................................................... 7
3.4.1.
Adjust the Entire Order ............................................................................................................. 7
3.4.2.
Adjust by Line Item Components .............................................................................................. 8
3.4.3.
Adjust by Line Item Amounts .................................................................................................... 8
1
1. Order Process Overview
The following details describe the process of integrating fully with all marketplaces that DemandStream
supports. It requires the development of multiple feeds which will be sent or received on a regular
schedule.
When a customer places an order on the marketplace, DemandStream will make the order available in
either an XML or text file format. This order report will be placed on the CommerceHub FTP, into your
dedicated FTP ‘outgoing’ directory.
If your ftp server is sfeeds.mercent.com, your order report will be available at
{MerchantID}\Reports\PendingOrders\. Files you upload (Order Acknowledgement, Fulfillment, and
Adjustment) will need to be put in {MerchantID}\Feeds\. Your MerchantID and ftp credentials will be
provided to you by the CommerceHub Client Onboarding team.
You should create an automated task to check this location, at least hourly, to retrieve any new order
reports placed.
1.1.
Order Report
DemandStream returns all orders, regardless of marketplace, in a single feed, scheduled throughout the
day – typically hourly. An order file will be created on a pre-determined schedule for pick-up from your
FTP location at CommerceHub. The order report will contain all new orders that have been placed and
that have not yet been acknowledged by you via the order acknowledgement feed.
Key Notes:




1.2.
Because orders will be included in every file until they are acknowledged, there is the possibility
that an order may be imported into your system more than once. Your system should expect this
and neither error out nor create duplicate orders in your system. Orders are uniquely identified by
the ChannelOrderID and ChannelName.
The Order file will be updated the next scheduled period that there are new orders. The file will
remain the same if there are no new orders. You can optionally delete the Order file on the ftp
site after processing it.
Feed File Name – The order report will by default be named Order.[xml|txt]. If you would like a
different file name, or a new file to be generated each time where the file name has the date and
time included, notify your CommerceHub Client Onboarding team.
The order report can optionally be compressed using the Zip or Gzip file format with the
extension zip, xml.gz, or txt.gz. To request your order report be compressed, notify your
CommerceHub Client Onboarding team.
Acknowledgement Feed
The acknowledgement feed is generated by the merchant and sent to DemandStream through the
dedicated FTP site. The order acknowledgement feed lets the marketplace know you have received the
2
order and are in the process of fulfilling it. Additionally the order acknowledgement feed is used to
associate your order IDs and order item IDs with the marketplaces order IDs and order item IDs. Each
acknowledgement will contain a StatusCode element, the value being either ‘Success’ or ‘Failure’. Use
the ‘Success’ code to indicate you’ve received the order and can fulfill it. Use the ‘Failure’ code only
when you can’t fulfill the order and want it to be cancelled in the marketplace.
Key Notes:






1.3.
Use a Failure StatusCode with caution. It will result in the entire order being cancelled, even if a
prior Success StatusCode was provided.
Send Acknowledgements Batched – When you send the acknowledgements, they should be
batched together in a single file.
Acknowledgement Schedule – Acknowledgements should come between order reports, usually
hourly.
Provide an OrderAcknowledgement feed only when there are acknowledgements to process.
Feed File Name – The acknowledgement feed name should be
“OrderAcknowledgement_yyyyMMddHHmmss.[xml/txt]”.
The acknowledgement feed may optionally be compressed using the Zip or Gzip file format with
the extension zip, gz, xml.gz, or txt.gz.
Fulfillment Feed
The fulfillment feed is sent by the merchant once the order has been successfully shipped from their
warehouse or drop shipper. This is also the trigger to let the marketplace know to charge the customer for
the order as well as notifying the customer of the tracking identifier on the package.
Each shipment is identified by the combination of the ChannelOrderID and the
ShippingTrackingNumber. A shipment can be for the entire order or for part of the order (split
shipments). What is in each shipment is identified by SKU and Quantity. Therefore there will be one line
in the fulfillment file for each SKU in each shipment.
Key Notes:





Send fulfillments batched - When you send the fulfillments, batch multiple fulfillments together
in a single file.
Fulfillment Schedule – Fulfillments are typically sent hourly.
Provide an OrderFulfillment feed only when there are fulfillments to process.
Feed File Name – The fulfillment feed name should be
“OrderFulfillment_yyyyMMddHHmmss.[xml/txt]”
The fulfillment feed may optionally be compressed using the Zip or Gzip file format with the
extension zip, gz, xml.gz, or txt.gz.
3
1.4.
Adjustment Feed
The DemandStream order adjustment feed is used to return money back to the buyer when the customer
has initiated a product return. The adjustment amount and type is worked out between the buyer and the
merchant’s customer service representative. Once the adjustment is ready, the merchant sends the
adjustment feed to DemandStream for processing on the marketplace.
The following order adjustment refunds are supported by the DemandStream adjustment feed:



Complete order refund.
Complete refund at the order line item level.
Partial amount refunds on the line item.
The following adjustment amounts can be adjusted at the line item level:




Principal item amount
Shipping
Tax
Gifting
Additionally we can support restocking fees applied to the adjustment.
Key Notes:





Send adjustments batched - When you send the adjustments, batch multiple adjustments together
in a single file.
Adjustment Schedule – Adjustments are typically sent every 2-4 hours.
Provide an OrderAdjustment feed only when there are adjustments to process.
Feed File Name – The adjustment feed name should be
“OrderAdjustment_yyyyMMddHHmmss.[xml/txt]”
The adjustment feed may optionally be compressed using the Zip or Gzip file format with the
extension zip, gz, xml.gz, or txt.gz.
2. Feed Development
The DemandStream feeds can be developed using XML or flat file feeds. Each feed is independent of the
other, so a combination of XML and flat files is possible.
2.1.
Reference Documentation
The following reference documents are available for working with the DemandStream Order Process:
DemandStream_Standard_Order_Specification_Text.xlsx – Layout, definition and examples for each
field in the specification.
4
DemandStream_Standard_Order_Specification_XML.xslx – Definition and examples for each
attribute and element of the XML specification.
DemandStream_Standard_Order*.xsd – A collection of XSD’s for each XML feed.
3. Sample Feeds using XML
3.1.
Order Report XML Sample
<?xml version="1.0" encoding="utf-8"?>
<MercentFeed>
<Order ChannelOrderID="002-6489057-7780233" ChannelName="Amazon">
<OrderDate>2011-03-30T08:10:24-07:00</OrderDate>
<CurrencyCode>USD</CurrencyCode>
<PaymentTransactionID/>
<IsCBA>false</IsCBA>
<IsChannelFulfilled>false</IsChannelFulfilled>
<IsMerchantFulfilledPrime>false</IsMerchantFulfilledPrime>
<BillingData>
<Name>
<FullName>Jeff Larson</FullName>
<FirstName>Jeff</FirstName>
<MiddleName/>
<LastName>Larson</LastName>
</Name>
<PhoneNumber>2068323953</PhoneNumber>
<EmailAddress>zzrv6qmbtpfnww4@marketplace.amazon.com</EmailAddress>
</BillingData>
<FulfillmentData>
<Name>
<FullName>Jeff Larson</FullName>
<FirstName>Jeff</FirstName>
<MiddleName/>
<LastName>Larson</LastName>
</Name>
<PhoneNumber>2068323953</PhoneNumber>
<FulfillmentAddress>
<Address1>1633 Weslake Ave N</Address1>
<City>Seattle</City>
<StateOrRegion>WA</StateOrRegion>
<PostalCode>98109</PostalCode>
<CountryCode>US</CountryCode>
</FulfillmentAddress>
<FulfillmentMethod>Ship</FulfillmentMethod>
<FulfillmentLevel>Standard</FulfillmentLevel>
</FulfillmentData>
<ItemTotal>34.97</ItemTotal>
<ShippingTotal>0.00</ShippingTotal>
<OtherTotal>0.00</OtherTotal>
<ItemDiscountTotal>-1.00</ItemDiscountTotal>
<TaxTotal>0.00</TaxTotal>
<OrderTotal>33.97</OrderTotal>
<OrderItem ChannelOrderItemID="48821535204818">
<SKU>7907731013070</SKU>
<Title>Women's Wrapped Mary Jane, Mushroom/Espresso,7 M US</Title>
<Quantity>1</Quantity>
<ItemPrice>
<ItemAmount>34.97</ItemAmount>
<ItemTax>0.00</ItemTax>
<ShippingAmount>0.00</ShippingAmount>
<ShippingTax>0.00</ShippingTax>
5
</ItemPrice>
<ItemFee>
<ItemCommission>-5.25</ItemCommission>
</ItemFee>
<PromotionData>
<MerchantPromotionID>FreeShip25</MerchantPromotionID>
<PromotionClaimCode>_SITE_WIDE_</PromotionClaimCode>
<PrincipalDiscount>-1.00</PrincipalDiscount>
<ShippingDiscount>0.00</ShippingDiscount>
</PromotionData>
</OrderItem>
</Order>
<!-- ebay order -->
<Order ChannelOrderID="350450370146-286210401022" ChannelName="eBay">
<OrderDate>2011-03-30T06:17:16-07:00</OrderDate>
<CurrencyCode>USD</CurrencyCode>
<PaymentTransactionID>9HN99082XG718003G</PaymentTransactionID>
<IsChannelFulfilled>false</IsChannelFulfilled>
<IsMerchantFulfilledPrime>false</IsMerchantFulfilledPrime>
<BillingData>
<Name>
<FullName>Jeff Larson</FullName>
<FirstName>Jeff</FirstName>
<MiddleName/>
<LastName>Larson</LastName>
</Name>
<PhoneNumber>800 555 1234</PhoneNumber>
<EmailAddress>jeff.larson@mercent.com</EmailAddress>
</BillingData>
<FulfillmentData>
<Name>
<FullName>Mercent Corporation</FullName>
<FirstName>Mercent</FirstName>
<MiddleName/>
<LastName>Corporation</LastName>
</Name>
<PhoneNumber/>
<FulfillmentAddress>
<Address1>1633 Westlake Ave N</Address1>
<Address2>Suite 200</Address2>
<City>Seattle</City>
<StateOrRegion>WA</StateOrRegion>
<PostalCode>98109</PostalCode>
<CountryCode>US</CountryCode>
</FulfillmentAddress>
<FulfillmentLevel>Standard</FulfillmentLevel>
</FulfillmentData>
<ItemTotal>52.99</ItemTotal>
<ShippingTotal>6.99</ShippingTotal>
<OrderTotal>59.98</OrderTotal>
<OrderItem ChannelOrderItemID="350450370146-286210401022">
<SKU>0746131-10 M</SKU>
<Quantity>1</Quantity>
<ItemPrice>
<ItemAmount>52.99</ItemAmount>
<ItemTax>0.00</ItemTax>
<ShippingAmount>6.99</ShippingAmount>
</ItemPrice>
</OrderItem>
</Order>
</MercentFeed>
3.2.
Order Acknowledgement XML Sample
<?xml version="1.0" encoding="utf-8"?>
<MercentFeed>
6
<OrderAcknowledgement>
<ChannelOrderID>002-6489057-7780233</ChannelOrderID>
<ChannelName>Amazon</ChannelName>
<MerchantOrderID>M999</MerchantOrderID>
<StatusCode>Success</StatusCode>
<Item>
<ChannelOrderItemID>48821535204818</ChannelOrderItemID>
<MerchantOrderItemID>M999-1</MerchantOrderItemID>
</Item>
</OrderAcknowledgement>
<OrderAcknowledgement>
<ChannelOrderID>350450370146-286210401022</ChannelOrderID>
<ChannelName>eBay</ChannelName>
<StatusCode>Success</StatusCode>
</OrderAcknowledgement>
</MercentFeed>
3.3.
Order Fulfillment XML Sample
<?xml version="1.0" encoding="utf-8"?>
<MercentFeed>
<OrderFulfillment>
<ChannelOrderID>002-6489057-7780233</ChannelOrderID>
<ChannelName>Amazon</ChannelName>
<FulfillmentDate>2011-04-01T08:35:33-07:00</FulfillmentDate>
<FulfillmentData>
<Carrier>UPS</Carrier>
<ShippingTrackingNumber>1Z9216AX0316833873</ShippingTrackingNumber>
<ShippingMethod>Standard</ShippingMethod>
</FulfillmentData>
<Item>
<SKU>7907731013070</SKU>
<Quantity>1</Quantity>
</Item>
</OrderFulfillment>
<OrderFulfillment>
<ChannelOrderID>350450370146-286210401022</ChannelOrderID>
<ChannelName>eBay</ChannelName>
<FulfillmentDate>2011-04-01T08:37:33</FulfillmentDate>
<FulfillmentData>
<Carrier>UPS Ground</Carrier>
</FulfillmentData>
</OrderFulfillment>
</MercentFeed>
3.4.
Order Adjustment XML Sample
3.4.1. Adjust the Entire Order
The following will refund everything paid by the buyer.
<?xml version="1.0" encoding="UTF-8"?>
<MercentFeed>
<OrderAdjustment>
<ChannelOrderID>999-9999999-9999999</ChannelOrderID>
<ChannelName>Amazon</ChannelName>
<RefundFull>true</RefundFull>
<FullAdjustmentReason>ItemBackOrdered</FullAdjustmentReason>
</OrderAdjustment>
</MercentFeed>
7
3.4.2. Adjust by Line Item Components
The following adjustment type is useful when the backend system doesn’t maintain the amounts paid by
the customer at the order item level. DemandStream will return the amounts based on previous
adjustments to the order and the quantity designated in the adjustment.
<?xml version="1.0" encoding="utf-8"?>
<MercentFeed>
<OrderAdjustment>
<ChannelOrderID>999-9999999-9999999</ChannelOrderID>
<ChannelName>Amazon</ChannelName>
<OrderItemAdjustment>
<ChannelOrderItemID>9999999999999</ChannelOrderItemID>
<AdjustmentReason>CustomerReturn</AdjustmentReason>
<Quantity>1</Quantity>
<ItemPriceAdjustments>
<RefundItemPrincipal>true</RefundItemPrincipal>
<RefundItemTax>true</RefundItemTax>
<RefundShippingPrincipal>true</RefundShippingPrincipal>
<RefundShippingTax>true</RefundShippingTax>
</ItemPriceAdjustments>
</OrderItemAdjustment>
</OrderAdjustment>
</MercentFeed>
3.4.3. Adjust by Line Item Amounts
The following adjustment type allows the most customization by the merchant, however, you must be
able to maintain the balances remaining on an order at the item level so as to not create adjustment errors
to the channels. The adjustment allows for a full dollar amount adjustment on each line item.
<MercentFeed>
<OrderAdjustment>
<ChannelOrderID>999-9999999-9999999</ChannelOrderID>
<ChannelName>Amazon</ChannelName>
<OrderItemAdjustment>
<ChannelOrderItemID>9999999999999</ChannelOrderItemID>
<AdjustmentReason>CustomerReturn</AdjustmentReason>
<Quantity>1</Quantity>
<ItemPriceAdjustments>
<ItemPrincipalAmount>9.99</ItemPrincipalAmount>
<ItemTaxAmount>0.99</ItemTaxAmount>
<ShippingPrincipalAmount>4.99</ShippingPrincipalAmount>
<ShippingTaxAmount>0.49</ShippingTaxAmount>
</ItemPriceAdjustments>
</OrderItemAdjustment>
</OrderAdjustment>
</MercentFeed>
8