Distribution Center Transport SOAP Service

Legacy API

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

Introduction

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.

Configuration

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.

API user?

You do not need to setup a API user to use this API. The required credentials are listed below:


CredentialPurpose
Access Key

The key is the password that is used by the program to access your order information.

 We recommend that you make it something very long (20 characters) with letters, numbers and a few punctuation characters.

What the merchant must provide to external integrator

The merchant will need to provide the developer building the external integration the following credentials details:

  • UltraCart Merchant ID
  • Access Key
  • Distribution Center access code 

    ***The DC "access code" is the code assigned to the distribution center.
    Login and navigate:
    HOME →  CONFIGURATION →  CHECKOUT →  SHIPPING →  DISTRIBUTION CENTERS 
BidirectionalSet 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".

Do not set this to yes unless the fulfillment house is performing credit card processing functionality for you.


Web Service Location

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!

Methods

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:
1) PayPal e-check orders or any other method that does not clear in real-time like a credit card.
2) You have a hold time configured on the distribution center.
3) You have multiple distribution centers.

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 acknowledgeMultiple method to acknowledge a batch of order ids efficiently.

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.


Objects

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.

Recommended API Workflow

Importing Orders from UltraCart into WMS

  1. Call the getOrders method and fetch a batch (up to 500 will be returned)
  2. Add the orders to your internal WMS system
  3. Call the acknowledgeMultiple method with the orderIds from the batch retrieved in step 1.
  4. If 500 orders were retrieved in step 1 then loop by performing steps 1-3 repeatedly until all orders have been imported.

Confirming Shipment from WMS to UltraCart (Bi-Directional Integrations)

  1. After each order ships call the shipped method and provide the order ID and tracking information.

Abuse of API

Please do not poll for orders more than twice per hour. If you abuse the API your access will be terminated.

Frequently Asked Questions

 Why are orders staying in the "pending immediate transmission" column?

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.

 My fulfillment house says everything is OK, but the orders are not moving through the stages properly. What should I do?

 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.

 Orders are staying in the unacknowledged column. What is wrong?

The web service is configured as bi-directional.  The programmer must return the tracking information to UltraCart using the shipped or shippedWithMultipleTrackingNumbers API call.

 How do I hold orders for 10 hours before releasing them for shipment to make it easier to handle quick changes/cancels?

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.

 When are credit cards captured for authorized orders?

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.


Sample Code

C#

First, create a Service Reference using the WSDL link above.   Name it DctServiceReference.

App.config
<?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>
Program.cs
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();
        }
    }
}


Version History

DateVersionChanges
11/13/20071.0Initial Version
05/10/20132.0Added discount information to the Item object.  Include special instructions on the order object.
05/29/20132.0Added documentation on the getOrdersOption1 and getOrdersOption2 methods.
07/17/20133.0Added 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/20184.0Added documentation about WithCost methods that allow feeding back cost information to UltraCart