Order Management Web 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.


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

AutoOrderDetails of an auto order.  Used by getAutoOrder and updateAutoOrder.
AutoOrderItemDetails 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.

FieldDescriptionRead Only
String referenceOrderIdThe original order id that this auto order is associated with.Yes
String autoOrderCodeThe unique code associated with the auto order.Yes
boolean enabledTrue if the auto order is still enabled.
Calendar nextAttemptThe next attempt to process the auto order.
String canceledByUserThe user that canceled the auto order.Yes
Calendar canceledDtsThe date/time that the auto order was canceled.Yes
Integer cancelAfterNextXOrdersThe number of orders to process before automatically canceling the auto order.
String failureReasonThe reason for the last failure.Yes
Calendar disabledDtsThe date that the auto order was disabled due to too many failed attempts.Yes
Integer overrideAffiliateIdThe affiliate id that will be attributed with all future auto orders.Yes
AutoOrderItem[] itemsThe 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.

FieldDescriptionRead Only
String originalItemIdThe original item id purchased by the customer.Yes
BigDecimal originalQuantityThe original quantity ordered.Yes
int itemReferenceOidAn internal reference identifier.Yes
Calendar nextShipmentThe next shipment date for this item.
String frequencyFrequency of the rebill.  This will be null if a complex sequence is configured on the item.
Integer remainingRepeatCountThe number of rebills remaining.Yes
BigDecimal lifeTimeValueLifetime value of this item.Yes
int numberOfRebillsNumber of rebills that have occurred on this item.Yes
BigDecimal rebillValueRebill value of this item.Yes
Calendar lastOrderDtsDate of last order.Yes
Calendar noOrderAfterNo more rebills after this date.
BigDecimal arbitraryUnitCostArbitrary unit cost for further rebills.  If not specified the rebill value is whatever is configured on the original item.
Integer arbitraryUnitCostRemainingOrdersThe number of times to give the customer the arbitrary unit cost before reverting to the normal pricing schedule
String arbitraryItemIdArbitrary item id to rebill.  If not specified the rebilled item is whatever is configured on the original item.
BigDecimal arbitraryQuantityArbitrary quantity to rebill.  If not configured the rebill quantity is whatever was on the original order.
Integer arbitraryScheduleDaysIf the frequency is configured as "Every..." then this must be the number of days to rebill them on.
BigDecimal arbitraryPercentageDiscountAn arbitrary percentage discount off the normal pricing schedule.
Calendar nextPreshipmentNoticeThe date to send the next preshipment notice.
boolean preshipmentNoticeSentTrue/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.