This document contains examples of typical use cases for the Shopping Cart API. These examples demonstrate calls to the SOAP interface and are provided as is.
Full API documentation is available here.
The following examples demonstrate calls to the Shopping Cart API in C#.
These examples assume the use of a generated XML web service client. To generate such a client, a tool such as WSDL.exe can be used. A detailed description on this tool can be found on MSDN - you will need to point this program at your site's Shopping Cart API endpoint. A detailed description of how to generate a web service client is beyond the scope of this document.
Note that these examples include minimal or no error handling. Any API callers are expected to handle errors appropriately.
The typical first step in processing a shopping session will be calling the Create() method.
This creates a new shopping session using the default webstie, display state and currency settings for the target retailer.
A successful reponse includes the session ID required by all the other shopping cart methods.
string sessionToken;
ApiResponse response = service.Create(authenticationToken);
if (response.Success){
sessionToken = response.Message;
} else {
// Handle Error
}
Once a shopping session has been created the details of its current state can be retreived at any time by passing the session token returned by the create method to GetCurrentCart. The shopping session is represented by an Initiated Order object.
ShoppingCartApiResponse response
= service.GetCurrentCart(authenticationToken, sessionID);
if (response.Success){
Order cartState = response.Data;
} else {
// Handle Error
}
The recommended next step is to assign the customer to the shopping session, this ensures any customer specific discounts will be recevied from this point on.
If this customer has not yet be added to the system it will be added at the same time as being assigned to the shopping session.
ApiResponse response
= service.AssignCustomer(authenticationToken, sessionID, customer);
if (response.Success){
// If this is a new customer you can obtain the
// Customer ID from the response message.
customer.ID = response.Data.Single();
} else {
// Handle Error
}
Items can now be added and removed to the shopping session as required. The barcode is obtained from a Product Item, this a specific size and/or colour of a Product. The available products in the system may be retrieved using the Products API.
ApiResponse response
= service.AddItem(authenticationToken, sessionID, barcode, quantity);
if (!response.Success){
// Hanlde Error
}
ApiResponse response = service.RemoveItem (
authenticationToken
, sessionID
, barcode
, quantity
);
if (!response.Success){
// Hanlde Error
}
To get freight options for the shopping session the cart must:
The NVPApiResponse.Data property contains as list of NameValuePairs with the name set to the freight provider name and the value being the charge for this freight provider.
It is not reommended to set the freight option for the shopping session until the cart contents are finalised as adding and removing items may affect the freight options and charges. If a freight option is no longer available it will be removed from the session automatically, it is up to you to confirm a freight option is set before submitting a order.
NVPApiResponse response
= service.GetFreightOptions(authenticationToken, sessionID);
if (response.Success){
// Freight options are returned as name value pairs.
var options = response.Data.Select(nv => new {
ProviderName = nv.Name,
Charge = nv.Value
});
} else {
// Handle Error
}
The shipping and billing address must be set before submitting an order to the system, additionally the shipping address needs to be set to retrieve accurate freight charges.
The CustomerAddress Type must be set to either "Shipping" or "Billing" when setting addresses for a shopping session.
CustomerAddress shipping = new CustomerAddress(){
Type = "Shipping",
...
}
ApiResponse response
= service.SetAddress(authenticationToken, sessionID, shipping);
if (!response.Success){
//Handle Error
}
Once the cart contents and shipping address have been finalised a valid list of freight options can be retrieved using GetFreightOptions. The choosen freight provider can then be set by passing the provider name to SetFreightProvider.
NVPApiResponse response
= service.GetFreightOptions(authenticationToken, sessionID);
if (response.Success){
// Freight options are returned as name value pairs.
var options = response.Data.Select(nv => new {
ProviderName = nv.Name,
Charge = nv.Value
});
// Select first provider for this example,
// the desired options should be selected by the end
// user in a real system.
string selectedProviderName
= options.Select(o => o.ProviderName).FirstOrDefault();
if (selectedProviderName != null) {
ApiResponse response = service.SetFreightProvider (
authenticationToken,
sessionID,
providerName
);
if (!response.Success) {
// Handle Error
}
}
} else {
// Handle Error
}
It is recommended payments are not added until the client has confirmed the order, if the cart contents need to be modified after a payment has been added ClearPayments must be called first.
The API currently supports the following payment methods:
A single payment can be used to cover the entire order value or a mixture of payment types can be used to make up the order value. The following combinations of payment methods are supported:
Note only one credit card payment can be used on a order.
// Test WebCard object WebCard card = new WebCard(){ Type = "MasterCard", Name = "John Doe", Number = "5431111111111111", CSC = "123", Month = 3, Year = 15 } // Adds a credit card payment for the full value of the order. ApiResponse response = service.AddCreditCardPayment (authenticationToken, sessionID, card); if (!response.Success) { // Handle Error } // Splitting the order total accross two payments. ShoppingCartApiResponse response = service.GetCurrentCart(authenticationToken, sessionID); if (response.Success){ Order cartState = response.Data; // Adds a credit card payment for half the value of the order. ApiResponse response = service.AddPartialCreditCardPayment( authenticationToken, sessionID, card, cartState.OrderTotal / 2 ); if (response.Success) { // Adds a internet banking payment for half // the value of the order. ApiResponse response = service.AddPartialInternetBankingPayment( authenticationToken, sessionID, card, cartState.OrderTotal / 2 ); if (!response.Success) { // Handle Error } } else { // Handle Error } } else { // Handle Error }
Once the shopping cart is finalised it can be submitted as an Order to the system using the Submit method. The requirments before submitting an order are:
Submit returns the new Order, this can be used as a order confirmation in your client. Once the shopping session is submitted it is closed and the session Id is no longer valid, access to the submitted order is available through the Orders API.
ShoppingCartApiResponse response
= service.Submit(authenticationToken, sessionID);
if (response.Success){
// response.Data is the confirmed Order.
Order newOrder = response.Data;
} else {
// Handle Error
}
If an Order will not be submitted you should close the shopping session using the Abandon method. This will reverse any payments taken for the order and close the shopping session in the system. Once closed the session ID will no longer be valid.
StringArrayApiResponse response
= service.Abandon(authenticationToken, sessionID);
if (!response.Success) {
// Handle Error
}