Intro to SOAP Integrations
This page is a high level introduction to a typical system integration. The name System2 is used as the non-ChannelAdvisor system. This integration involves sending ChannelAdvisor inventory items, and then pulling 'Ready To Ship' orders. Finally, System2 sends ChannelAdvisor a shipping confirmation.
Pulling Orders From ChannelAdvisor Into System2
Typically sellers want to retrieve orders that are ready to ship (payment Cleared and Unshipped). They want to retrieve the order only once so they don't duplicate their downloads. This entails calling Order Service.GetOrderList to get the orders and then calling Order Service.SetOrdersExportStatus to mark the order as having been previously downloaded. GetOrderList does allow for querying for orders that are in other states, but we will use Ready To Ship in the example as it is the most common use case.
A working sample and detailed explanation is here: Application Example - GetOrderList by ExportState. The end result of the sample code is one XML file for each order that is "Ready To Ship". The integrator would then need to load the XML into the system with which they are integrating.
Updating Shipping Status From System2 to ChannelAdvisor
Once the order ships from their system, the seller can send us the shipping details by using Shipping Service.SubmitOrderShipmentList. The shipping carrier-class that is sent to ChannelAdvisor must be a valid ChannelAdvisor shipping code. That list is available through GetShippingCarrierList.
Refunding Customer Orders
Many customers have a defined refund process in their back-end system and would like to eliminate any manual processes throughout the order lifecycle. We provide a method to do so. This API method allows a developer to tie their existing system flow into ChannelAdvisor in an automated fashion.
When Using System2 as the Master Inventory
For inventory updates, we recommend this pattern to almost all developers:
- Full sync of all fields for an item: Only when necessary, such as adding a new item.
- Price and quantity updates: Only for changed items, and generally every 15 minutes at most often and 1 day at least often for a changed item.
- Update of inventory fields other than price and quantity: once or twice a day, only for changed items.
- Wherever possible, track changes on System2, and only sync changed items with ChannelAdvisor. This greatly limits the number of calls that have to be processed as well as the payload size of each API call. Across all customers, we find this eliminates well over 90% of traffic between ChannelAdvisor and external systems, leading to greatly improved application performance.
These aren't hard and fast rules, but they work for most scenarios we see.
Inventory Service.SynchInventoryItemList can be used to update or add new inventory. The ChannelAdvisor Inventory item is fairly complex as it has many fields specific to CA. Since many integrations do not use all the fields, most of them can be left out. It's important to note that leaving a field out (or passing a null) will cause it not to be modified, but passing an empty value for a field will cause the value to be cleared.
In almost all applications, quantity and price change much more frequently than any other inventory field. To help facilitate these changes we've created a special method to accommodate changes to these field only, and we recommend its use to all developers:
This method allows you to send only price and quantity changes for a batch of items and has been optimized to process more quickly than a similar SynchInventoryItemList call for this scenario.
Finally, a note on large SKU counts: any HTTP-based web service will have reasonable performance below about twenty thousand SKUs in an hour or so period. Much of the latency in any Internet-based system like an API often takes place during network traversal. Above twenty thousand SKUs, we recommend you forgo using the API in favor of sending your inventory to ChannelAdvisor via FTP to avoid excessive latencies. You can contact Support to get set up for FTP if you choose to take advantage of this alternative.