This API has been replaced with our newer REST APIs. Please visit https://www.ultracart.com/api/ for more information. Our newer REST APIs provide language specific SDKs and far more functionality. |
Distribution Center Transport SOAP Service for 3rd party fulfillment integration
The purpose of this document is to introduce the web services that can be used to interface a 3rd party logistics company or internal fulfillment operation with UltraCart. Most fulfillment integrations rely upon UltraCart implementing the production of files and transmitting them to fulfillment companies in the format that they already support. With this method the fulfillment company can now write code in any programming language to communicate with UltraCart to retrieve orders, acknowledge receipt of the order and post back shipping information. This document is intended for software developers. It is not meant to either explain programming or the usage of web services for a specific language.
The web service transport is like any other transport in the fact that it must be configured for a particular distribution center. This configuration is performed:
Main Menu → Configuration → (middle menu) Checkout → Shipping → Distribution Center (tab) → [Edit] → Transmission Mechanism (section) → Web Service (SOAP) |
You must set the transport to “Web Service” and configure the three required options: key, bidirectional, send credit card information.
You do not need to setup a API user to use this API. The required credentials are listed below:
Credential | Purpose | ||
---|---|---|---|
Access Key | The key is the password that is used by the program to access your order information.
| ||
Bidirectional | Set the bidirectional to "yes" if the fulfillment house can return tracking information to UltraCart. | ||
Send Payment Information | If the fulfillment house is also going to be processing the credit cards then also set the send credit card information to "yes".
|
The WSDL (web service description language) file is located at the following URL:
https://secure.ultracart.com/axis/services/DctServiceV4?wsdl
MAKE SURE YOU ACCESS THE WEB SERVICE OVER HTTPS! |
Order getOrder(Credentials credentials, String orderId)
This method retrieves a single order using the known order ID. This method is suitable for warehouse management system which may be scanning a pick list barcode of the order id.
Order[ ] getOrders(Credentials credentials)
This function obtains all the orders that have not been exported. This will include all orders that are new from the previous retrieval and acknowledgment. It is important that you make an acknowledge call for each order that you process after retrieving them.
Order[ ] getOrdersForDateRange(Credentials credentials, dateTime from, dateTime to)
This function obtains all orders that are either in the shipping department or in the completed stage between the specified from
and to
times. This method can be used to historically fetch order information in case of a processing problem after an order has been acknowledged.
Order[] getOrdersWithThumbnails(Credentials credentials, int thumbnailWidth, int thumbnailHeight)
This function obtains all the orders that have not been exported. This will include all orders that are new from the previous retrieval and acknowledgment. It is important that you make an acknowledge call for each order that you process after retrieving them. If there is a graphic available for the item then a thumbnail of width and height specified will be created. The URL for the thumbnail is returned on the Item object.
Order[] getOrdersForDateRangeWithCustomThumbnails(Credentials credentials, dateTime from, dateTime to, int thumbnailWidth, int thumbnailHeight)
This function obtains all orders that are either in the shipping department or in the completed stage between the specified from
and to
times. This method can be used to historically fetch order information in case of a processing problem after an order has been acknowledged. If there is a graphic available for the item then a thumbnail of width and height specified will be created. The URL for the thumbnail is returned on the Item object.
Do not use the versions of getOrders that take a from/to parameters if you are using any of the following: |
void acknowledge(Credentials credentials, String orderId)
This function acknowledges that the order has been downloaded and processed. This order will no longer appear in the next call to getOrders. If the interface is implemented in a unidirectional fashion then the order will also be marked as shipped within UltraCart. If the interface is bidirectional then the order will stay in the shipping department awaiting confirmation of shipment and tracking information.
Use the |
String[] acknowledgeMultiple(Credentials credentials, String[] orderIds)
This function acknowledges that the orders have been downloaded and processed. These orders will no longer appear in the next call to getOrders. If the interface is implemented in a unidirectional fashion then the orders will also be marked as shipped within UltraCart. If the interface is bidirectional then the orders will stay in the shipping department awaiting confirmation of shipment and tracking information. Returns the order ids that were successfully acknowledged. If everything goes smoothly the same orderIds passed in will be returned.
Please limit the number of elements in the orderIds array to 100. If you have more than 100 to acknowledge split them up into batches and make multiple calls. This will prevent you from receiving timeouts on the API call. |
void shipped(Credentials credentials, String orderId, String trackingNumber)
This function confirms that an order has been shipped and stores the tracking number on the order. This method must be used if the interface is bidirectional.
void shippedWithCost(Credentials credentials, String orderId, String trackingNumber, BigDecimal shippingCost)
This function confirms that an order has been shipped, stores the tracking number on the order and records the shipping cost. This method must be used if the interface is bidirectional.
void shippedWithMultipleTrackingNumbers(Credentials credentials, String orderId, String[] trackingNumbers)
This function confirms that an order has been shipped and stores multiple tracking numbers on the order. This method or shipped must be used if the interface is bidirectional. It is OK to call this method with a single tracking number in the array.
void shippedWithMultipleTrackingNumbersWithCost(Credentials credentials, String orderId, String[] trackingNumbers, BigDecimal shippingCost)
This function confirms that an order has been shipped, stores multiple tracking numbers on the order and records the shipping cost. This method or shipped must be used if the interface is bidirectional. It is OK to call this method with a single tracking number in the array.
boolean updateItemInventory(Credentials credentials, ItemInventory itemInventory)
This function updates the inventory for a single item. The result indicates if the update was successful or not. Please use the next method to update inventory in batches.
boolean[] updateItemInventories(Credentials credentials, ItemInventory[] itemInventories)
This function updates the inventory for a batch of items. The result is an array of boolean values indicating if the update was successful
Please limit the number of inventory item objects to 100. If you have more than 100 to update, split them up into batches and make multiple calls. This will prevent you from receiving timeouts on the API call. |
Credentials
Credentials to access the web service. All the fields for this object should be provided by the merchant after they configure the distribution center transport within UltraCart.
Order
Header level information about the order. This will contain payment information if the merchant has configured the distribution center web service transport to allow payment information to be sent.
Item
Item information
Option
Item option information.
ItemInventory
Inventory information associated with the item that can be updated.
Please do not poll for orders more than twice per hour. If you abuse the API your access will be terminated. |
Your programmer needs to call getOrders first to retrieve the orders and then call acknowledge or acknowledgeMultiple to tell UltraCart that they've been successfully picked up. |
Look at the Log underneath the shipping department. Every call that their program makes will be logged. Make sure that they are making the calls at appropriate intervals and no errors are being generated. |
The web service is configured as bi-directional. The programmer must return the tracking information to UltraCart using the shipped or shippedWithMultipleTrackingNumbers API call. |
Under Main Menu -→ Configuration → Checkout → Shipping → [edit], there is an option "Hold Before Shipment _____ (minutes)". If you configure that with 600, then UltraCart will hold the orders for 10 hours before sending them back in the result set of a getOrders call. |
UltraCart captures credit cards when the order moves from the shipping department to completed orders. If your integration is uni-directional then this will happen when acknowledge or acknowledgeMultiple is called. If your integration is bi-directional then this will happen when you call shipped or shippedWithMultipleTrackingNumbers. |
First, create a Service Reference using the WSDL link above. Name it DctServiceReference.
<?xml version="1.0" encoding="utf-8" ?> <configuration> <startup> <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5.2" /> </startup> <system.serviceModel> <bindings> <basicHttpBinding> <binding name="DctServiceV4SoapBinding" /> </basicHttpBinding> </bindings> <client> <endpoint address="http://secure.ultracart.com/axis/services/DctServiceV4" binding="basicHttpBinding" bindingConfiguration="DctServiceV4SoapBinding" contract="DctServiceReference.DctService" name="DctServiceV4" /> </client> </system.serviceModel> </configuration> |
using System; using UltraCartServices.DctServiceReference; namespace UltraCartServices { public class Program { public static void Main(string[] args) { var client = new DctServiceClient(); var credentials = new Credentials { merchantId = "DEMO", distributionCenterCode = "DFLT", key = "1234567890" }; var start = DateTime.Now.AddDays(-720); var end = DateTime.Now.AddDays(+1); var orders = client.getOrdersForDateRange(credentials, start, end); Console.WriteLine($"{orders.Length} orders returned"); orders = client.getOrders(credentials); Console.WriteLine($"{orders.Length} orders returned"); Console.ReadKey(); } } } |
Date | Version | Changes |
---|---|---|
11/13/2007 | 1.0 | Initial Version |
05/10/2013 | 2.0 | Added discount information to the Item object. Include special instructions on the order object. |
05/29/2013 | 2.0 | Added documentation on the getOrdersOption1 and getOrdersOption2 methods. |
07/17/2013 | 3.0 | Added additional fields to the Order object to cover merchantNotes, gift, giftCost, giftMessage, giftWrapCost, and giftWrapTitle. Orders are "SKU mapped" before the download process like all other fulfillment integrations. |
03/08/2018 | 4.0 | Added documentation about WithCost methods that allow feeding back cost information to UltraCart |