UltraCart Order Management Web Service Developers Guide

Written by UltraCart Support
Copyright© 2011 BPS Info Solutions, Inc.
Last Updated 3/30/2011

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/OrderManagementServiceV1?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

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

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.

API Methods

cancelAutoOrderAsCustomerByOrderId

Method Signature boolean cancelAutoOrderAsCustomerByOrderId(Credentials c, 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 c - 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 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

doesOrderContainItem

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 booelan - returns true if the order contains the specified item.

getActiveAutoOrderItemIds

Method Signature String[] getActiveAutoOrderItemIds(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.

getActiveAutoOrderOrderIds

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.

hasCustomerPaidFor

Method Signature boolean hasCustomerPaidFor(Credentials c, String email, String itemId);
Description
This method will determine if a customer has paid for a particular item.
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.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 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.

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.

resendReceipt

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