add_item_to_cart
Add one or more items to the shopping cart.
If no cart exists, this tool makes a new cart. This tool adds products and gift certificates.
Steps
Call the 'search_products' tool to find a product.
Call the 'get_product_details' tool to get the variants and the modifier options.
Call this tool to add the item.
Call the 'create_checkout_url' tool to get a checkout URL.
The response returns the whole cart. Each item in 'cart.lineItems' has an 'entityId'. Use it as 'line_item_id' in the 'update_cart_item' tool. Use it as 'item_id' in the 'remove_item_from_cart' tool.
Rules
Send 'quantity' and 'productEntityId' for each item. If the configuration that the user chose has a variant, send 'variantEntityId'. Send 'variantEntityId' as null only for a configuration with no variant. See "Configurations with no variant" for when this is allowed.
Modifier options
A modifier option is a product choice that is not a variant. Examples are an engraving message and a nicotine strength. The 'get_product_details' tool returns these options in 'modifierOptions'.
If the product has no 'modifierOptions' and you send a variant, do not send 'selectedOptions'. If you send a variant in 'variantEntityId', do not send a variant option in 'selectedOptions'. The variant sets those options.
An option is required if 'isRequired' is 'true'. Send each required option. If you do not send a required option, the server does not add the item.
To send an option:
Read the bucket name from 'selectedOptionsKey'.
Add the option to 'item.selectedOptions' in that bucket.
Send the 'optionEntityId' of the option.
For a choice option, send 'optionValueEntityId'. Its number is the 'valueEntityId' of the value that the user selected.
Send only the buckets that you need.
Example. A required choice option has a 'selectedOptionsKey' of "multipleChoices", an 'optionEntityId' of 108, and a selected value with a 'valueEntityId' of 251: { "item": { "quantity": 1, "productEntityId": 88, "variantEntityId": 67, "selectedOptions": { "multipleChoices": [ { "optionEntityId": 108, "optionValueEntityId": 251 } ] } } }
A free-entry bucket takes a typed value in place of an ID. 'textFields' and 'multiLineTextFields' take "text". 'numberFields' takes "number". 'dateFields' takes "date". Obey the 'constraints' of the option.
If a required option has more than one value, ask the user to select one value. Do not select a value yourself. Do not use the default value.
If 'unsupported' is 'true', you cannot send the option. If such an option is also required, tell the user to buy the product on the website.
Configurations with no variant
A variant option value can have no variant. The default value, such as "None", is often one. The 'get_product_details' tool lists every value in 'variantOptions'. A value with 'hasVariant' of 'false' is used by no variant that can be bought. It has no variant, or its variants are not on sale now, for example because they are out of stock.
Send 'variantEntityId' as null only if all of these are true:
The user chose a value with 'hasVariant' of 'false'.
'variants' is not empty. If it is empty, every value has 'hasVariant' of 'false', and the product may not be on sale. Do not add the product. Tell the user.
If every value that the user chose has 'hasVariant' of 'true', and no variant in 'variants' matches all of the values, that configuration does not exist. Do not add the base product in its place. Tell the user that the configuration is not available.
If the store has no variant for the configuration, it adds the base product. If a variant exists but cannot be bought, the server rejects the item. Give that reason to the user.
To add it:
Send 'variantEntityId' as null.
Send every variant option of the product in 'item.selectedOptions.multipleChoices'. Send the 'optionEntityId' of the option and the 'optionValueEntityId' of the value that the user selected. Send the options that have a variant too, not only the value that has none.
Send each required modifier option as usual.
Example. Variant option 81 has the value 899, which has no variant. Required modifier option 108 has the value 251: { "item": { "quantity": 1, "productEntityId": 88, "variantEntityId": null, "selectedOptions": { "multipleChoices": [ { "optionEntityId": 81, "optionValueEntityId": 899 }, { "optionEntityId": 108, "optionValueEntityId": 251 } ] } } }
If you leave out a variant option, the server rejects the item with the message "This product has options, variant ID is required". The message is misleading. A variant option that you did not send, or a value that does not belong to the option, causes it.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"item": "<item>"
},
"name": "add_item_to_cart"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cart | Yes | ||
| message | No | ||
| success | Yes |