Shopping Cart API

Overview

This document outlines the purpose, technology, use cases, methods, objects and examples for using the Shopping Cart API.

This particular document focuses on the SOAP interface to this API.

Purpose

This API provides programmatic access to shopping sessions, and functionality for placing orders with the system. See the examples for use cases.

The Shopping Cart API exposes 2 primary native interfaces via .NET and SOAP.

Shopping Cart API Definition (.NET)

Full documentation for this interface is available in the API Reference.

Shopping Cart API Definition (SOAP)

This section documents the SOAP interface to the API.

Endpoint

The SOAP API endpoint for any site is located at https://[siteurl]/global/api/shoppingcart.asmx

This endpoint is enabled for access via SOAP v1.1. The Service Description is also available directly via this endpoint.

Note: For systems with satellite sites, the API will be available only under the primary site URL.

Security (SOAP Interface Only)

The Shopping Cart API via SOAP uses the Permissions System to allow and deny access to certain users. Use of the API requires a user to be granted the various actions (under iSAMS / API / Shopping Cart) to be able to authenticate, and perform the various actions available under this API.

Error Handling

Service errors are returned as part of the ApiResponse object which is the base of all service reponses. The ApiResponse.Success property needs to be checked to establish whether the service request was successful. If ApiResponse.Success is false a ShoppingCartApiResponseCode is returned in the ApiResponse.Code property and ApiResponse.Message contains a description of the error.

Where a "Call Identifier" is returned in the Message field of the ApiResponse, then a full exception trace will be available from [website url]/logs/api/{Call Identifier}.txt

Methods

Available methods are listed below.

Methods

GetCurrentCart

Returns the current state of the shopping session.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
Response

The current OrderStatus.Initiated Order wrapped in a ShoppingCartApiResponse.

Create

Creates a new shopping session and returns a session token in the ApiResponse message.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate
Response

A session token wrapped in a ApiResponse.

Notes

CreateWithOrder

Creates a new shopping session in the provided state and returns a session token in the ApiResponse message.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
order Order A Initiated Order to create a shoppig session with.
Response

A session token wrapped in a ApiResponse.

Notes

Submit

Submits the current shopping cart as an Order to the system.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by ShoppingCartApiSoapWrapper.Create or ShoppingCartApiSoapWrapper.CreateWithOrder.
Response

The Confirmed Order wrapped in a ShoppingCartApiResponse.

Abandon

Discards the current shopping cart and reverses any payments taken.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
Response

Any required refunds that were not able to be performed will be listed in the StringArrayApiResponse.

AssignCustomer

Assigns the provided Customer to the current shopping session.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
customer Customer The Customer to assign to the shopping session.
Response

The Customer.ID the new or updated Customer, wrapped in a IntegerArrayApiResponse.

AssignCustomerByID

Assigns a Customer to the current shopping session using the Customer.ID.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
customerID Int32 The Customer.ID of the Customer to assign to the shopping session.
Response

A ApiResponseCode wrapped in a ApiResponse.

AssignCustomerByEmail

Assigns a Customer to the current shopping session using the Customer.Email.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
email String The Customer.Email of the Customer to assign to the shopping session.
Response

A ApiResponseCode wrapped in a ApiResponse.

SetAddress

Sets the billing or shipping CustomerAddress for the shopping session.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
address CustomerAddress The billing or shipping CustomerAddress.
Response

A ApiResponseCode wrapped in a ApiResponse.

SetFreightProvider

Sets the freight provider for the current shopping session.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
providerName String The name of the freight provider to use.
Response

A ApiResponseCode wrapped in a ApiResponse.

SetPromoCode

Redeems a CouponPromo for the current shopping session.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
code String The CouponPromo.Code for the CouponPromo being redeemed.
Response

A ApiResponseCode wrapped in a ApiResponse.

GetAddresses

Returns the CustomerAddresses currently set against the shopping seesion.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
Response

CustomerAddresses wrapped in a CustomerAddressesApiResponse object.

GetFreightOptions

Returns the freight options available to the current order.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
Response

An array of NameValuePairs, with NameValuePair.Name as the freight provider name and NameValuePair.Value as the charge for this frieght provider, wrapped in a NVPApiResponse.

GetVouchers

Returns the vouchers available to the current shopping session.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
Response

An array of NameValuePairs, with NameValuePair.Name as the Voucher.ID and NameValuePair.Value as the Voucher.RemainingValue, wrapped in a NVPApiResponse.

AddItem

Adds items to the current shopping session. system pricing will be used.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
barcode String The item barcode, see ProductItem.Barcode
quantity Int32 The quantity of the item to add.
Response

A ApiResponseCode wrapped in a ApiResponse.

RemoveItem

Removes items from the current session.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
barcode String The item barcode, see ProductItem.Barcode
quantity Int32 The quantity of the item to remove.
Response

A ApiResponseCode wrapped in a ApiResponse.

AddVoucherItem

Add a voucher to the shopping session.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
buyerName String A person to credit for gifting the voucher.
deliveryDate DateTime The date that the voucher is to be sent to the recipient.
firstName String Recipient's first name.
lastName String Recipient's last name.
email String Recipient's email address.
message String The message that is to be included with the voucher delivery.
purchaseAmount Decimal The voucher's value.
Response

A ApiResponseCode wrapped in a ApiResponse.

RemoveVoucherItem

Removes a voucher from the current shopping session.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
voucherID Int32 The Voucher.ID
Response

A ApiResponseCode wrapped in a ApiResponse.

AddCreditCardPayment

Adds a credit card payment to the current Order to cover the outstanding Order.OrderTotal.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
card WebCard The WebCard to use to make the payment.
Response

An ApiResponse containing the payment provider response if the payment could not be added.

AddPartialCreditCardPayment

Adds a credit card payment to the current Order.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
card WebCard The WebCard to use to make the payment.
amount Decimal The amount to pay with this WebCard. If this is over the outstanding Order total, the outstanding total will be charged.
Response

An ApiResponse containing the payment provider response if the payment could not be added.

AddGiftCardPayment

Adds a gift card payment to the current Order to cover the outstanding Order.OrderTotal.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
card WebCard The WebCard to use to make the payment.
Response

An ApiResponse containing the payment provider response if the payment could not be added.

AddPartialGiftCardPayment

Adds a gift card payment to the current Order.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
card WebCard The WebCard to use to make the payment.
amount Decimal The amount to pay with this WebCard. If this is over the outstanding Order total, the outstanding total will be charged.
Response

An ApiResponse containing the payment provider response if the payment could not be added.

AddVoucherPayment

Adds a Voucher payment to the current Order to cover the outstanding Order.OrderTotal.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
voucherID Int32 The Voucher.ID of the Voucher to use to make the payment.
Response

An ApiResponse containing the payment provider response if the payment could not be added.

AddPartialVoucherPayment

Adds a Voucher payment to the current Order.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
voucherID Int32 The Voucher.ID of the Voucher to use to make the payment.
amount Decimal The amount to pay with this Voucher. If this is over the outstanding Order total, the outstanding total will be charged.
Response

An ApiResponse containing the payment provider response if the payment could not be added.

AddInternetBankingPayment

Adds a internet banking payment to the current Order to cover the outstanding Order.OrderTotal.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
Response

An ApiResponse containing the payment provider response if the payment could not be added.

AddPartialInternetBankingPayment

Adds a internet banking payment to the current Order.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
amount Decimal The amount to pay with via internat banking. If this is over the outstanding Order total, the outstanding total will be charged.
Response

An ApiResponse containing the payment provider response if the payment could not be added.

AddExternalPayment

Adds an externally verified payment to the current Order.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
value Decimal The value of the external payment
Response

An ApiResponse containing the payment provider response if the payment could not be added.

ClearPayments

Removes all payments on the current Order, any captured funds will be refunded.

Parameters
Name Type Description
authenticationToken String The token returned by ApiSoapWrapper.Authenticate.
sessionID String The token returned by Create or CreateWithOrder.
Response