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.
...
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 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 cancelAutoOrdersAsCustomerByEmail(Credentials c, 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 c – 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 c, 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 c – 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
...
Method Signature boolean doesOrderContainItem(Credentials c, String orderId, String itemId);
Description
Checks to see if the specified order contains the given item Id.
Parameters Credentials c – 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 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 byte[] - the bytes of the exported document. Format will depend upon the configuration of the export mapping.
...
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.
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.
getShipmentStatus
Method Signature ShipmentStatus getShipmentStatus(Credentials c, String orderId);
Description
Obtain the details of the shipment including date, shipping method, tracking numbers and tracking URL
Parameters Credentials c - 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.
...
Method Signature boolean isActiveAutoOrder(Credentials c, String email);
Description
Checks to see if there is an active auto order associated with this email address.
Parameters Credentials c – 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 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.
...
Method Signature void resendReceipt(Credentials c, String orderId);
Description
Triggers the receipt to be resent for the specified order id.
Parameters Credentials c – 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 c, String orderId);
Description
Triggers the shipment confirmation to be resent for the specifid order id.
Parameters Credentials c – 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 c, 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 c – 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.