Order Management Web Service
- Perry Tew
- Jonathan Tew
- Hunter Schaeffer
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.