...
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.
...
The WSDL for this web service is located at:
https://secure.ultracart.com/axis/services/OrderManagementServiceV1OrderManagementServiceV2?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 |
| Info | ||
|---|---|---|
| ||
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 String exportOrder2(Credentials c, String exportName, String orderId);
Description Export an order using a pre-defined export mapping configured under Main Menu -> Configuration -> Export Orders.
Parameters Credentials c - 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[] getActiveAutoOrderItemIdsgetActiveAutoOrderItem(Credentials c, String email);
Description
This method will determine all the item ids that are on active auto order for a given email address..
Parameters Credentials c – 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 c, String email);
Description
This method will determine all the order Ids that are on active auto order for a given email address..
Parameters Credentials c – 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 AutoOrder getAutoOrder String[] getActiveAutoOrderOrderIds(Credentials c, String referenceOrderId)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 c – 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 c, 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 c – 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 c, String referenceOrderId);
Description
This method loads the auto order object associated with the original reference order id.
Parameters Credentials c – 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.
...
Method Signature PlaceSingleSignonOrderResult placeSingleSignonOrder(Credentials c, 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 c – 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. |
| Tip |
|---|
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). |
...
Method Signature void updateOrderCustomFields(Credentials c, String orderId, String[] customFields);
Description
This method updates the custom fields associated with an order.
Parameters Credentials c – 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.