You use the AddItem method in the Baskets API to add items to baskets on Desktop and Mobile sites. (For Trade sites, use the AddItemTrade method described in AddItemTrade Method.)
It is important to understand how customer baskets are handled in the IRP when dealing with the AddItem (or AddItemTrade) method in the Baskets API. Two key concepts to comprehend are that:
- A
BasketID relates to a single row in a customer's basket.
- All of the rows are tied together by a
GUID (which is usually a customer's GUID).
AddItem has many variations in terms of what you can achieve with it and, as such, there are many values you can have in the object you send. However to get going with it you only need to pass in one of the IDs (in addition to the required AuthenticationToken, TimeStamp and Signature fields) - here are three simple examples (in the examples below, replace https://www.yourdomainname.com with the domain name where your API is located):
IRPStockID example:
var addItem = {
"AuthenticationToken" : "YmWaLx5DyTrZbKrxq2cfhKGw3/1XC8q6",
"TimeStamp" : "2018-10-01 16:03:15"
"Signature" : "f0ca44ba17afd5d5da7a6cc837f756ce18096ccc",
"IRPStockID" : 2910
};
$.post({'https://www.yourdomainname.com/api/v1/Baskets/AddItem',
addItem,
function (data) {// 'success' function
....
})
IRPExternalStockID example (note that ExternalStockID does not enforce uniqueness and the AddItem method will reject it if it finds more than one stock item with the value):
var addItem = {
"AuthenticationToken" : "YmWaLx5DyTrZbKrxq2cfhKGw3/1XC8q6",
"TimeStamp" : "2018-10-01 16:03:15"
"Signature" : "f0ca44ba17afd5d5da7a6cc837f756ce18096ccc",
"IRPExternalStockID" : "2910-BTS"
};
$.post({'https://www.yourdomainname.com/api/v1/Baskets/AddItem',
addItem,
function (data) {// 'success' function
....
})
IRPPartCode example (note that PartCode does not enforce uniqueness and the AddItem method will reject it if it finds more than one stock item with the value):
var addItem = {
"AuthenticationToken" : "YmWaLx5DyTrZbKrxq2cfhKGw3/1XC8q6",
"TimeStamp" : "2018-10-01 16:03:15"
"Signature" : "f0ca44ba17afd5d5da7a6cc837f756ce18096ccc",
"IRPPartCode" : "00002910"
};
$.post({'https://www.yourdomainname.com/api/v1/Baskets/AddItem',
addItem,
function (data) {// 'success' function
....
})
The AddItem can also take any of the values described in the following table.
Table 1. AddItem Method Allowed Values
| Field |
Required |
Type |
Notes |
AddAsNewOnBasketMissing |
No |
Boolean |
If a BasketID is provided but not found, setting this value to true will make a new basket item according to the rest of the values. Otherwise the request will fail. |
AdditionalInformation |
No, but when an object is provided, the Type and AdditionalInformation fields are required. |
Array of objects. Each object contains:
DisplayText (string)
Type (Int, 1- 4)
AdditionalInformation (string, in Base64 encoding) |
You can attach various formats of information to items that have been added to a basket via the API. Each AdditionalInformation object can contain three values – for more details, see Table 2. AdditionalInformation Possible Values below. |
BasketID |
No |
Int |
If you want to update an existing basket item, set this to the BasketID of that item. Otherwise omit this value. |
CurrencyISO |
No |
String
(3 characters) |
If you're providing a price to override the IRP Stock price, it will be treated as being the price in your default currency. If you want it to be treated as a foreign currency, pass in the appropriate ISO here (USD, JPY, etc.). NOTE: this will override the price listed on the website and should only be used when absolutely necessary. |
CustomerGUID |
No (Unless BasketID is provided, then a GUID must be provided and it must match the GUID stored against the BasketID.) |
String
(50 characters) |
This lets you add an item directly to a customer's basket, or lets you make a custom basket consisting of multiple items that can then be copied into any customer's basket by visiting the retrieve link returned from the method. If a GUID is not provided, one will be generated for the basket.
Example 1: If you want to add an item directly to a customer's basket, pass in that customer's GUID.
Example 2: If you want to have a basket containing three items that multiple customers can copy into their own baskets, send the first AddItem request with no GUID, then send the following two requests with the GUID that the first request returned. Now when a customer visits the BasketRetrieve page for that GUID, they will have all three items added their basket. |
EditURL |
No |
String
(1000 characters) |
This URL will override the model URL for the customer, therefore if the customer clicks the name of the product in their basket, it will direct them to this link and not the usual page for that model. |
ExternalReference |
No |
String
(50 characters) |
This value will not be shown to customers and will only be displayed in the event that the customer orders the item. It will then be visible on the Orders and OrderManage pages alongside any AdditionalInformation. |
ImageURL |
No |
String
(1000 characters) |
This URL will replace the thumbnail shown on the Basket page for this basket item. |
IRPExternalStockID |
No (Is required if IRPPartCode and IRPStockID are not provided) |
String
(50 characters) |
This is one of the values that can be provided to select the stock item you are trying to add to a basket. It will try to find a unique active stock item in your IRP that has this value as its ExternalStockID. Note that ExternalStockID does not enforce uniqueness and the AddItem method will reject it if it finds more than one stock item with the value. |
IRPPartCode |
No (Is required if IRPExternalStockID and IRPStockID are not provided) |
String
(50 characters) |
This is one of the values that can be provided to select the stock item you are trying to add to a basket. It will try to find a unique active stock item in your IRP that has this value as its PartCode. Note that PartCode does not enforce uniqueness and the AddItem method will reject it if it finds more than one stock item with the value. |
IRPStockID |
No (Is required if IRPExternalStockID and IRPPartCode are not provided) |
Int |
This is one of the values that can be provided to select the stock item you are trying to add to a basket. It will try to find a unique active stock item in your IRP that has this value as its StockID. |
OverwriteQuantity |
No |
Boolean |
If you are providing a BasketID, and therefore are trying to update an existing basket item, and you have provided a new Quantity value, then you must also pass in this value as true. If you provide a BasketID and a Quantity but do not provide this value, the Quantity that you provided will be ignored. |
OverwriteStockID |
No |
Boolean |
If you are providing a BasketID and you have also provided one of IRPStockID, IRPExternalStockID or IRPPartCode then the StockID of the stock item that is found must match the StockID that is associated with the BasketID. If this value is provided as true then, in that scenario, the stock item in the Basket row will be replaced with the new stock item. |
Quantity |
No |
Short |
This indicates how many of the item to add to the customer's basket. If this value is missing from the provided object, it will default to 1. |
Price |
No |
Decimal |
This value lets you override the price of the item that is stored against its stock item in the IRP. NOTE: this will override the price listed on the website and should only be used when absolutely necessary.
If the price is provided without a CurrencyISO it will be treated as being the default currency of your IRP.
If you provide a CurrencyISO with the price, when the customer views their basket the price that you provided will be converted from the currency you supplied to the currency of the customer using the current exchange rates of your IRP. However if those currencies are the same, they are shown the exact value that you supplied.
Any item that is added to a basket with an overriding price will still count towards, and be affected by promotions. However they will not count towards, or be affected by, stock quantity discounts. |
Each AdditionalInformation object can contain the three values described in the following table:
Table 2. AdditionalInformation Possible Values
| Valuye |
Description |
DisplayText |
(Optional): This is simply plain text that will be shown to the customer when they view their basket. |
AdditionalInformation |
(Required): The additional information itself, can be one of four types but whichever type it is it must be encoded in a Base64 format. This will not be visible to the customer but will be visible in your Admin section on the Orders and OrderManage pages |
Type |
(Required): This must be a number between 1 and 4:
- PDF (This is expected to be the URL of a PDF document.)
- Text (Plain text.)
- JPG (An image that will be rendered as a JPG on the appropriate Admin pages.)
- PNG (An image that will be rendered as a PNG on the appropriate Admin pages.) |
Here is an example of a single AdditionalInformation object that will display 'DisplayToCustomer' on the basket page and 'DisplayedInAdmin' on the Admin pages once the item is ordered:
[{
"Type": "2",
"DisplayText": "DisplayToCustomer",
"AdditionalInfo": "RGlzcGxheWVkSW5BZG1pbg=="
}]
It is important to note that, even when there is only a single piece of AdditionalInformation, it must still be provided as an array of the objects.
Here is an example of an acceptable object including the AdditionalInformation field to send to the AddItem method:
{
AuthenticationToken: "YmWaLx5DyTrZbKrxq2cfhKGw3/1XC8q6",
TimeStamp: "2018-10-02 11:53:39",
Signature: "107240227137141176892730201158482262021231351582078422",
IRPStockID: "1234",
Price: "25",
AdditionalInformation: [
{ DisplayText: "Added Custom Text To Product",
Type: "1",
AdditionalInfo: "aHR0cDovL2xvY2FsaG9zdDoyMzU2L1dlYkludGVyZmFjZS8=" }
] }
Any item that has a provided price override, or any additional information, will not stack with any other versions of the stock item that the customer has in their basket. This is important because a customer may have five items that are all the same stock item but, if two of them have differing overriding prices or different pieces of AdditionalInformation, they will display as three different items in the customer’s basket and therefore have three different BasketID values.
Note that you can add items to baskets without the items needing to be in stock; the customer will be warned on the basket page that the item is out of stock and the item will be removed from their basket when they go to checkout.
The object that is returned from a successful posting to AddItem will contain:
BasketID: This will either be the value that was posted for the fields or the value that the system generated as part of the process.CustomerGUID: This will either be the value that was posted for the fields or the value that the system generated as part of the process.RedirectURL: This will be a URL that points to the BasketRetrieve page for the entire basket (stored by the GUID) that, when visited by a customer, will copy the contents of the basket into theirs.- The default fields that are included in every returned object, as described previously (
Success, Messages, Signature, Timestamp).
Here is an example response from AddItem:
{
"BasketID":57284,
"CustomerGUID":"23a40c9b-b5c7-4926-8220-4cf41a92b6f8",
"RedirectURL":"http://yourdomain/WebInterface/BasketRetrieve.aspx?GUID=23a40c9b-b5c7-4926-8220-5fc64d83a7g9",
"Messages":[],
"Success":true,
"Signature":"2005688000b32706aa88592f33cb80d4587c1775",
"TimeStamp":"2018-10-17 14:40:45"
}
