You use the AddItemTrade method in the Baskets API to add items to baskets on Trade sites.
AddItemTrade is a version of the AddItem method that works exclusively on the Trade site and has more limitations on what it can do:
- You cannot pass in a
GUID and, as such, items must always be added to a customer's basket by directing them to the RedirectURL returned from the method.
- You cannot override the price in the trade basket – all prices will be according to the price list set against the trade customer.
AddItemTrade 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 addItemTrade = {
"AuthenticationToken" : "YmWaLx5DyTrZbKrxq2cfhKGw3/1XC8q6",
"TimeStamp" : "2018-10-01 16:03:15"
"Signature" : "f0ca44ba17afd5d5da7a6cc837f756ce18096ccc",
"IRPStockID" : 2910
};
$.post({'https://www.yourdomainname.com/api/v1/Baskets/AddItemTrade',
addItemTrade,
function (data) {// 'success' function
....
})
IRPExternalStockID example (note that ExternalStockID does not enforce uniqueness and the AddItemTrade method will reject it if it finds more than one stock item with the value):
var addItemTrade = {
"AuthenticationToken" : "YmWaLx5DyTrZbKrxq2cfhKGw3/1XC8q6",
"TimeStamp" : "2018-10-01 16:03:15"
"Signature" : "f0ca44ba17afd5d5da7a6cc837f756ce18096ccc",
"IRPExternalStockID" : "2910-BTS"
};
$.post({'https://www.yourdomainname.com/api/v1/Baskets/AddItemTrade',
addItemTrade,
function (data) {// 'success' function
....
})
IRPPartCode example (note that PartCode does not enforce uniqueness and the AddItemTrade method will reject it if it finds more than one stock item with the value):
var addItemTrade = {
"AuthenticationToken" : "YmWaLx5DyTrZbKrxq2cfhKGw3/1XC8q6",
"TimeStamp" : "2018-10-01 16:03:15"
"Signature" : "f0ca44ba17afd5d5da7a6cc837f756ce18096ccc",
"IRPPartCode" : "00002910"
};
$.post({'https://www.yourdomainname.com/api/v1/Baskets/AddItemTrade',
addItemTrade,
function (data) {// 'success' function
....
})
The following fields are accepted by the AddItemTrade method.
Table 1. AddItemTrade Method Allowed Values
| Field |
Required |
Type |
Notes |
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. |
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. |
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. |
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. |
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. |
Each AdditionalInformation object can contain the three values described in the following table:
Table 2. AdditionalInformation Possible Values
| Value |
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.
The returned object from AddItemTrade will return only:
RedirectURL: This will be a URL that points to Trade/BasketRetrieve for the basket item that was just created and will ensure that a customer is logged into a trade account before copying the API item to their basket.- The default fields that are included in every returned object (
Success, Messages, Signature, Timestamp).
