Get the details of one or more products. The details are the variants, the options, and
the images.
Arguments
productIds - The list of product IDs. Get these IDs from the 'search_products' tool.
Request only the products that the user needs.
The server has a maximum count of IDs. The default maximum is 20.
If you send too many IDs, the server returns an error. Then send fewer IDs.
option_values - The option IDs and the value IDs of one variant.
Use this argument with one product ID only. This argument applies to the B2C catalog.
For a B2B buyer, the tool returns all the variants. Then select one variant.
channelId - Optional. This argument selects the B2B catalog.
The default is the channel of the request.
variantCursor - Optional. This argument gets the next page of variants.
Use this argument with one product ID only.
Take the value from 'nextVariantCursor' in the previous result.
If 'nextVariantCursor' is absent, or is null, or is the text "null", do not send this
argument.
Results
The tool returns a list of products in 'products'. The output schema gives all the
fields.
A product has 'modifierOptions' only if the product has modifier options.
A variant has a price, an inventory level, a purchase flag, and bulk prices only for a
B2B buyer.
If the tool does not find a product, the list does not include that product.
Modifier options
A modifier option is a product choice that is not a variant.
Examples are an engraving message and a gift note.
A variant option is never a modifier option.
If a product has no 'modifierOptions', add the product to the cart without
'selectedOptions'.
An option is required if 'isRequired' is 'true'.
Send each required option to the 'add_item_to_cart' tool.
If you do not send a required option, the server does not add the item.
A variant selection does not replace a required option.
Each option has 'optionEntityId', 'displayName', and 'selectedOptionsKey'.
'selectedOptionsKey' is the name of the field to send the option in.
A choice option has 'values'. Each value has 'valueEntityId' and 'label'.
A free-entry option has 'constraints' in place of 'values'.
If 'unsupported' is 'true', you cannot send the option. A file upload is one example.
If such an option is also required, tell the user to buy the product on the website.
Variant pages
The list of variants can be one page of a longer list. The server sets the page size.
If 'hasMoreVariants' is 'true', more variants exist than the tool returned.
Then do not tell the user that a variant does not exist. You did not receive all the
variants.
To get the next page, call this tool again. Send the same product ID, and only that
product ID. Send 'variantCursor' with the value of 'nextVariantCursor'.
A filter is better than a page walk. If the user named the variant, send 'option_values'
instead. One filtered call is cheaper than many pages.
Do not change 'option_values' between pages. The cursor is a position in the list of the
previous call. A different filter gives the wrong variants.
Stock
Each product has 'inStock'. It tells you if the store has units in stock.
It does not tell you if the user can buy the product.
If 'inStock' is 'false', do not refuse the request.
Many stores accept orders for products that are not in stock.
Tell the user that the product is not in stock, and that delivery can take more time.
Then add the product if the user agrees.
If the store blocks the purchase, the 'add_item_to_cart' tool fails and gives a reason.
Give that reason to the user.
If 'inStock' is 'true', the store reports no out-of-stock condition.
A store that does not count stock reports 'true' for all products.
Therefore do not tell the user a quantity.
'inventoryLevel' is present only if the store publishes stock counts.
If 'inventoryLevel' is absent, the count is unknown. The count is not zero.
Each variant has its own 'inStock'. Use the value of the variant if you add one variant.
Steps
1. Call the 'search_products' tool to get the product IDs.
2. Call this tool with the product IDs.
3. Call the 'add_item_to_cart' tool with the results of step 1 and step 2.
If a product has variants, you must tell the 'add_item_to_cart' tool which variant to
add.
If a product has required modifier options, you must send those options.