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.

UltraCart Order Management Web Service Developers Guide

Background

The order management web service is a standard SOAP interface designed to allow merchants to build perform management actions related to orders.

Prerequisite skills for using the API

In order to program against this API you need to be very familiar with SOAP programming within your desired developer language. This is not for people that have never coded web services before.

Support

Due to the complex nature of implementing web services, all support related to building or troubleshooting a custom application that utilizes this service is considered premium support which has an hourly cost associated with it. All questions related to using this API are beyond the scope of regular free email or phone support. You should factor this in when considering whether to build a custom application.

WSDL Location

The WSDL for this web service is located at:
https://secure.ultracart.com/axis/services/OrderManagementServiceV2?wsdl

Object Model

There are lots of simple objects that comprise the API. Below we will list out the names of each object and describe what it is. Then on subsequent pages we will detail all the fields on the object.

Class	Description
Credentials	The user credentials that you are going to use to make the API Call.
PlaceSingleSignonOrderResult	Holds all the result information from a call to placeSingleSignonOrder
ShipmentStatus	This object holds the shipment details for an order returned by getShipmentStatus
AutoOrder	Details of an auto order. Used by getAutoOrder and updateAutoOrder.
AutoOrderItem	Details of an auto order item. Used by getAutoOrder and updateAutoOrder.

Credentials

This object represents a the credentials used to make the API call.

Field	Description
String login	The API user's login
String merchantId	The merchant ID of the account
String password	The password of the user

Configure an API specific user

NOTE: You should navigate to the user configuration and configure a user that is only used with the API that has limited permissions otherwise. This user should be different than the user you use to log in and manage your UltraCart account.

PlaceSingleSignonOrderResult

This object holds all the result information returned by the call to placeSingleSIgnonOrder.

Field	Description
boolean successful	True if the order was placed successfully.
String orderId	Order Id of the new order.
String receiptText	Copy of the receipt text
String[] errorMessages	Error messages if the order was not successfully placed.

ShipmentStatus

This object holds the shipment details for an order returned by getShipmentStatus

Field	Description
String orderId	The order ID queried
boolean shipped	True/false if the order has shipped.
Calendar shipDate	The date of the shipment or null if the order has not shipped.
String shippingMethod	The method that the order shipped by
String shippingMethodDisplayName	The customer facing version of the shipping method.
String[] trackingNumbers	The tracking number or numbers. If this order did not have a tracking number then the array will be zero length.
String[] trackingUrls	The tracking URLs that the customer can click to obtain detailed tracking information from the carrier.

AutoOrder

This object holds the auto order details returned by getAutoOrder. Some of the fields are read-only when you pass the object back to updateAutoOrder.

Field	Description	Read Only
String referenceOrderId	The original order id that this auto order is associated with.	Yes
String autoOrderCode	The unique code associated with the auto order.	Yes
boolean enabled	True if the auto order is still enabled.
Calendar nextAttempt	The next attempt to process the auto order.
String canceledByUser	The user that canceled the auto order.	Yes
Calendar canceledDts	The date/time that the auto order was canceled.	Yes
Integer cancelAfterNextXOrders	The number of orders to process before automatically canceling the auto order.
String failureReason	The reason for the last failure.	Yes
Calendar disabledDts	The date that the auto order was disabled due to too many failed attempts.	Yes
Integer overrideAffiliateId	The affiliate id that will be attributed with all future auto orders.	Yes
AutoOrderItem[] items	The items associated with this auto order.

AutoOrderItem

This object holds the auto order details returned by getAutoOrder. Some of the fields are read-only when you pass the object back to updateAutoOrder.

Field	Description	Read Only
String originalItemId	The original item id purchased by the customer.	Yes
BigDecimal originalQuantity	The original quantity ordered.	Yes
int itemReferenceOid	An internal reference identifier.	Yes
Calendar nextShipment	The next shipment date for this item.
String frequency	Frequency of the rebill. This will be null if a complex sequence is configured on the item.
Integer remainingRepeatCount	The number of rebills remaining.	Yes
BigDecimal lifeTimeValue	Lifetime value of this item.	Yes
int numberOfRebills	Number of rebills that have occurred on this item.	Yes
BigDecimal rebillValue	Rebill value of this item.	Yes
Calendar lastOrderDts	Date of last order.	Yes
Calendar noOrderAfter	No more rebills after this date.
BigDecimal arbitraryUnitCost	Arbitrary unit cost for further rebills. If not specified the rebill value is whatever is configured on the original item.
Integer arbitraryUnitCostRemainingOrders	The number of times to give the customer the arbitrary unit cost before reverting to the normal pricing schedule
String arbitraryItemId	Arbitrary item id to rebill. If not specified the rebilled item is whatever is configured on the original item.
BigDecimal arbitraryQuantity	Arbitrary quantity to rebill. If not configured the rebill quantity is whatever was on the original order.
Integer arbitraryScheduleDays	If the frequency is configured as "Every..." then this must be the number of days to rebill them on.
BigDecimal arbitraryPercentageDiscount	An arbitrary percentage discount off the normal pricing schedule.
Calendar nextPreshipmentNotice	The date to send the next preshipment notice.
boolean preshipmentNoticeSent	True/false if the next preshipment notice has been sent.	Yes

API Methods

cancelAutoOrderAsCustomerByOrderId

Method Signature boolean cancelAutoOrderAsCustomerByOrderId(Credentials credentials, String orderId);
Description
This method will cancel the auto order associated with the item ID as if the customer had filled out the cancellation form on your website.
Parameters Credentials credentials – The credentials of the API user that is making the call. String orderId – The order ID to cancel the associated auto order on.
Result boolean – returns true if the auto order was successfully cancelled.

cancelAutoOrdersAsCustomerByEmail

Method Signature boolean cancelAutoOrdersAsCustomerByEmail(Credentials credentials, String email);
Description
Cancels all auto orders associated with the email address provided as if the customer filled out the cancellation form on your website.
Parameters Credentials credentials – The credentials of the API user that is making the call. String email – the email address to cancel auto orders on.
Result boolean – returns true if any auto order is canceled.

cancelOrder

Method Signature boolean cancelOrder(Credentials credentials, String orderId);
Description
Attempts to cancel the order before shipment and void/refund the customer's transaction if necessary. This method will only work with distribution centers that use transmission schedules.
Parameters Credentials credentials – The credentials of the API user that is making the call.String orderId – the order ID to cancel.
Result boolean – returns true if the cancellation was successful

doesOrderContainItem

Method Signature boolean doesOrderContainItem(Credentials credentials, String orderId, String itemId);
Description
Checks to see if the specified order contains the given item Id.
Parameters Credentials credentials – The credentials of the API user that is making the call.String order Id – the order ID to checkString itemId – the item ID to look for on the order.
Result boolean – returns true if the order contains the specified item.

exportOrder

Method Signature byte[] exportOrder(Credentials credentials, String exportName, String orderId);
Description Export an order using a pre-defined export mapping configured under Main Menu -> Configuration -> Export Orders.
Parameters Credentials credentials - The credentials of the API user that is making the call. String order Id - the order ID to export.
Result byte[] - the bytes of the exported document. Format will depend upon the configuration of the export mapping.

exportOrder2

Method Signature String exportOrder2(Credentials credentials, String exportName, String orderId);
Description Export an order using a pre-defined export mapping configured under Main Menu -> Configuration -> Export Orders.
Parameters Credentials credentials - The credentials of the API user that is making the call. String order Id - the order ID to export.
Result String - base 64 encoded version the exported document. Format will depend upon the configuration of the export mapping. Use this method if you SOAP client does not understand the byte[] returned from exportOrder.

getActiveAutoOrderItem

Method Signature String[] getActiveAutoOrderItem(Credentials credentials, String email);
Description
This method will determine all the item ids that are on active auto order for a given email address..
Parameters Credentials credentials – The credentials of the API user that is making the call. String email – the email to check auto orders for.
Result String[] – a unique list of item ids that have active auto orders on.

getActiveAutoOrders

Method Signature String[] getActiveAutoOrderOrderIds(Credentials credentials, String email);
Description
This method will determine all the order Ids that are on active auto order for a given email address..
Parameters Credentials credentials – The credentials of the API user that is making the call.String email – the email address to search for auto orders on.
Result String[] – a list of all the order Ids that have active auto orders associated with them.

getActiveAutoOrdersForItem

Method Signature String[] getActiveAutoOrderOrderIds(Credentials credentials, String email, String itemId);
Description
This method will return all the order ids that are associated with the supplied email filtered for the item id supplied
Parameters Credentials credentials – The credentials of the API user that is making the call.String email – the email address to search for auto orders on.
Result String[] – a list of all the order Ids that have active auto orders associated with them.

getActiveAutoOrdersForItems

Method Signature String[] getActiveAutoOrderOrderIds(Credentials credentials, String email, String[ ] itemIds);
Description
This method will return all the order ids that are associated with the supplied email filtered for the item ids supplied
Parameters Credentials credentials – The credentials of the API user that is making the call.String email – the email address to search for auto orders on.
Result String[] – a list of all the order Ids that have active auto orders associated with them.

getAutoOrder

Method Signature AutoOrder getAutoOrder(Credentials credentials, String referenceOrderId);
Description
This method loads the auto order object associated with the original reference order id.
Parameters Credentials credentials – The credentials of the API user that is making the call. String referenceOrderId – the original order id.
Result AutoOrder - a record describing everything about the auto order.

getOrderCustomFields

Method Signature String[] getOrderCustomFields(Credentials credentials, String orderId);
Description
This method returns the seven custom fields on an order.
Parameters Credentials credentials – The credentials of the API user that is making the call. String orderId – the order id to return custom fields for.
Result String[] - an array with seven entries corresponding to custom fields 1 - 7 on the order.

getShipmentStatus

Method Signature ShipmentStatus getShipmentStatus(Credentials credentials, String orderId);
Description
Obtain the details of the shipment including date, shipping method, tracking numbers and tracking URL
Parameters Credentials credentials - The credentials of hte API user that is making the call. String orderId - the order id to query shipment information on.
Result ShipmentStatus - an object containing all the details of the order's shipping.

hasCustomerPaidFor

Method Signature boolean hasCustomerPaidFor(Credentials credentials, String email, String itemId);
Description
This method will determine if a customer has paid for a particular item.
Parameters Credentials credentials – The credentials of the API user that is making the call.String email – the email address to search for auto orders on.String itemId – Item ID that the customer purchased
Result boolean – returns true if the customer has paid for a particular item on an order associated with their email address.

isActiveAutoOrder

Method Signature boolean isActiveAutoOrder(Credentials credentials, String email);
Description
Checks to see if there is an active auto order associated with this email address.
Parameters Credentials credentials – The credentials of the API user that is making the call. String email – the email address to search for an active auto order on.
Result boolean – returns true if there is an active auto order for this email address.

placeSingleSignonOrder

Method Signature PlaceSingleSignonOrderResult placeSingleSignonOrder(Credentials credentials, String cpSsoOid, String cpccSsoOid, String[] itemIds, int[] quantities, String screenBrandingThemeCode);
Description
This order uses the customer profile information stored with single signon credentials to place a new order.
Parameters Credentials credentials – The credentials of the API user that is making the call.String cpSsoOid – the Single Signon Oid for the customer profile to associate this order with.String cpccSsoOid – The Single SIgnon Oid associated with the stored credit card to use on this new order.String[] itemIds – the item ids to add to this new orders.int[] quantities – The quantities associated with each item on the new order.String screenBrandingThemeCode – the screen branding theme code to associate with the new order.
Result PlaceSingleSignonOrderResult – All the result information associated with the call including over success, receipt text, order id and any errors when unsuccessful.

placeSingleSignonOrder2

Method Signature	PlaceSingleSignonOrderResult2 placeSingleSignonOrder2(Credentials credentials, String cpSsoOid, String cpccSsoOid, String[] itemIds, int[] quantities, String screenBrandingThemeCode, decimal[] arbitraryUnitCosts);
Description	This method is identical to placeSingleSignonOrder save for the extra parameter arbitraryUnitCosts, which allows for specifying arbitrary unit costs
Parameter	credentials - the credentials of the API user that is making the call. This will include your secure.ultracart.com 1) merchant id, 2) login, and 3) password
Parameter	cpSsoOid - the Single Signon Oid (Object IDentifier) for the customer profile to associate this with this order
Parameter	cpccSsoOid - the Single Signon Oid (Object IDentifier) associated with the stored credit card to use on this new order
Parameter	itemIds - the item ids to add to this new orders
Parameter	quantities - the quantities associated with each item on the new order
Parameter	screenBrandingThemeCode - the screen branding theme code to associate with the new order
Parameter	arbitraryUnitCosts - the arbitrary unit costs you wish to employ with this order
Result	PlaceSingleSignonOrderResult2 – All the result information associated with the call including over success, receipt text, order id and any errors when unsuccessful.

placeSingleSignonOrder3

Method Signature	PlaceSingleSignonOrderResult3 placeSingleSignonOrder3(Credentials credentials, String email, String[] itemIds, int[] quantities, String screenBrandingThemeCode);
Description	This method is identical to placeSingleSignonOrder save for the extra parameter arbitraryUnitCosts, which allows for specifying arbitrary unit costs
Parameter	credentials - the credentials of the API user that is making the call. This will include your secure.ultracart.com 1) merchant id, 2) login, and 3) password
Parameter	email - the email of the customer
Parameter	itemIds - the item ids to add to this new orders
Parameter	quantities - the quantities associated with each item on the new order
Parameter	screenBrandingThemeCode - the screen branding theme code to associate with the new order
Result	PlaceSingleSignonOrderResult3 – All the result information associated with the call including over success, receipt text, order id and any errors when unsuccessful.

If you need to place an order and do not know the customer's OID or credit card OID, use placeSingleSignonOrder3. It will use credit card on file (most recently used if more than one exists).

resendReceipt

Method Signature void resendReceipt(Credentials credentials, String orderId);
Description
Triggers the receipt to be resent for the specified order id.
Parameters Credentials credentials – The credentials of the API user that is making the call. String orderId – the order ID to resend the receipt for.
Result None

resendShipmentConfirmation

Method Signature void resendShipmentConfirmation(Credentials credentials, String orderId);
Description
Triggers the shipment confirmation to be resent for the specifid order id.
Parameters Credentials credentials – The credentials of the API user that is making the call. String orderId – the order ID to resend the shipment confirmation for.
Result None

updateAutoOrder

Method Signature boolean updateAutoOrder(Credentials credentials, AutoOrder autoOrder);
Description
This method updates the settings for an auto order. The auto order object should come from a call to getAutoOrder. Only those fields that are not read-only can be updated. You can not add/remove items from the object. They will be ignored if you try to modify the items array.
Parameters Credentials credentials – The credentials of the API user that is making the call. AutoOrder autoOrder - the auto order record to update.
Result boolean - true if the update was successful.

updateOrderCustomFields

Method Signature void updateOrderCustomFields(Credentials credentials, String orderId, String[] customFields);
Description
This method updates the custom fields associated with an order.
Parameters Credentials credentials – The credentials of the API user that is making the call. String orderId - the order ID to update the custom fields on. String[] customFields - array of up to 7 strings for the custom fields. The first entry in the array corresponds to custom field 1, etc.
Result boolean - true if the update was successful.

Browser not supported