`Runtime_BasketItemList_Insert`#

This is a runtime function intended to be called client side to add multiple products to a basket in a single request. Because this is a runtime (public) function no API key is required. This function is nearly identical to Runtime_BasketItem_Insert with the exception that it acts on a list of products rather than a single product, closely mimicking the ADPM action. Unlike Runtime_BasketItem_Insert, product inventory is verified via Runtime_BasketItemList_Is_Available_Inventory_Filter, which silently filters out any products that do not have available inventory rather than failing the entire request. For each requested product that matches an existing basket item of the “same” product, attributes, and subscription term, the existing item’s quantity is updated rather than inserting a duplicate record.

Request Parameters#

Parameter	Type	Description
`Session_Type`	String	Always “runtime”. No API key needed.
`Session_ID`	String	Required. Session ID for the basket you wish to add items to.
`Products`	Array	Required. Array of product objects to add to the basket.

`Products` Object Structure#

Each product in the Products array should contain:

Parameter	Type	Required	Description
`Product_ID`	Number	No	The id of the product to add. One of `Product_ID` or `Product_Code` is required.
`Product_Code`	String	No	The code of the product to add. One of `Product_ID` or `Product_Code` is required.
`Quantity`	Number	Yes	The quantity of the product to add.
`Product_Subscription_Term_ID`	Number	No	Optional id of the Subscription Term to apply to the item, if the product supports subscriptions.
`Attributes`	Array	No	Array of selected attribute code/value objects. Example: `[{"code":"size","value":"large"},{"code":"rush","value":""}]`

Note

Products that fail the inventory availability check via Runtime_BasketItemList_Is_Available_Inventory_Filter are silently skipped and will not be added to the basket, and will not appear in the response. This differs from Runtime_BasketItem_Insert, which returns an error when inventory is unavailable. If a UI exception is otherwise raised while processing the list (for example, an invalid product or missing required attributes), the response will return success: 0 with error_code set to the UI exception’s code and error_message describing the problem.

Response Parameters#

Parameter	Type	Description
`success`	Boolean	Boolean value indicating if the API request was successful
`total`	Number	Updated basket total price
`subtotal`	Number	Updated basket subtotal price
`formatted_total`	String	Currency formatted basket total price
`formatted_subtotal`	String	Currency formatted basket subtotal price

Example Request#

{
    "Store_Code": "{{Store_Code}}",
    "Function": "Runtime_BasketItemList_Insert",
    "Session_Type": "runtime",
    "Session_ID": "{{Session_ID}}",
    "Products": [
        {
            "Product_Code": "shirt",
            "Quantity": 2,
            "Attributes": [{"code": "color", "value": "blue"}, {"code": "size", "value": "large"}]
        },
        {
            "Product_Code": "hat",
            "Quantity": 1
        }
    ]
}

Example Response#

{
    "success": 1,
    "data": {
        "total": 1725.0,
        "subtotal": 1725.0,
        "formatted_total": "$1,725.00",
        "formatted_subtotal": "$1,725.00"
    }
}

Error Responses#

Missing Products Parameter:

{
    "success": 0,
    "error_code": "MER-JSN-RTM-00048",
    "error_message": "Missing required parameter"
}

Invalid Product:

{
    "success": 0,
    "error_code": "MER-JSN-00023",
    "error_message": "One or more parameters are invalid",
    "validation_error": true,
    "error_field": "Products[1]:product_code",
    "error_field_message": "Product not found",
    "input_errors": true,
    "error_fields": [
        {
            "error_field": "Products[1]:product_code",
            "error_message": "Product not found"
        }
    ]
}

Runtime_BasketItemList_Insert#