Carrefour

Add one or more products to the shopping cart by their EAN. Accepts a list of {gtin, quantity} objects — works for a single item or a batch. Handles bulk additions in one request instead of calling the tool repeatedly. IMPORTANT: EANs MUST come from search_products, search_multiple_products, or get_substitutions results. When a request lists specific EANs (e.g. after the customer replaced items with substitutes in the list widget), add EXACTLY those EANs — never swap them back to the original search results, and never fabricate or guess an EAN. This tool renders no widget. The shopping-list widget keeps the cart in step on its own: it mirrors its list on arrival and writes every quantity change and substitution the customer makes, so a list the customer is looking at is already in their cart. Calling this tool again for products the list already holds resets quantities the customer chose. When the customer asks to add something outside that flow, this tool is how you do it — ask them first, since it writes to their cart. The response carries the basket as it now stands: quantities actually retained, per-line purchasing_min, purchasing_max and qty_to_sell, and max_quantity_buyable_per_offer on the basket. The API caps rather than refuses, and says so through a QUANTITY_REQUESTED_HIGHER_THAN_MAX_POSSIBLE message code on the line. Each basket carries its totals: products_total_price (the offers alone), services_total_price (delivery fee and/or returnable bags), bags_deposit_price (the returnable-bag share of the services), and grand_total_price (products + services). structuredContent.unavailable_products lists the lines the basket dropped by itself because the product can no longer be sold: they leave the widget and the total, so say which ones instead of letting them disappear without a word. What the customer is told is structuredContent.total_with_bags_deposit: the offers plus the bag deposit, which is exactly the figure the widget puts on screen. Unknown or out-of-assortment EANs are rejected: they are listed in structuredContent.rejected_gtins and are absent from the cart, so a call can partially succeed while some requested products never reached the basket. structuredContent.cart_in_carrefour_link is the customer's cart on Carrefour.fr; the shopping-list widget offers it as a button. A new cart is created automatically on the first call. Reuse the returned cart_id for subsequent calls. Prerequisites: search_products (to obtain EANs).

add_to_cart

Validate the customer's delivery address and AUTO-SELECT the most relevant Carrefour fulfillment center on their behalf. The user does NOT pick a store. Use this tool ONLY when pickup_mode is LAD (home delivery). For DRIVE, use search_store. Prerequisites: set_pickup_mode must be called first with mode 'LAD'. IMPORTANT: provide a full address (street + postal code + city) for precise geocoding. Returns the chosen fulfillment center in `structuredContent.auto_selected_store` — chain set_store with it — together with `min_order_amount` and a ready-made `min_order_message` when the delivery minimum order is known. That minimum is indicative only: it never blocks the order.

auto_select_delivery_location

Display the customer's current Carrefour cart. READ-ONLY — it adds, removes and changes nothing, so it is safe to run at any time. It renders the shopping-list widget filled with the cart's own lines instead of a search result: there is no separate cart widget, and a cart described in text does not produce one. The widget it renders does not push anything back to the cart — what it shows already is the cart — and it carries structuredContent.cart_in_carrefour_link as the way to finish the order on Carrefour.fr. Pass the cart_id when it is known; otherwise it is derived from the session. Each basket carries its totals: products_total_price (the offers alone), services_total_price (delivery fee and/or returnable bags), bags_deposit_price (the returnable-bag share of the services), and grand_total_price (products + services). What the customer is told is structuredContent.total_with_bags_deposit: the offers plus the bag deposit, which is exactly the figure the widget puts on screen. structuredContent.unavailable_products lists the lines the basket dropped by itself because the product can no longer be sold: they are gone from the widget and from the total, so say which ones before anything else instead of letting them vanish silently.

get_cart

Get the list of substitute products for a given product EAN. Used by the shopping-list widget to populate the inline substitution accordion. Returns purchasable alternatives only (image, title, brand, format, price, nutriscore, offerServiceId).

get_substitutions

Gets the current user's information (their 'uid_local' Carrefour customer identifier). The result always carries an `auth_status` field in `structuredContent`: `signed_in` (with `uid_local`), `signed_out`, or `unknown` when the identity provider could not be reached. On failure the result also carries `error` and `next_action` — follow `next_action` and never treat a failure as a signed-out user unless `auth_status` actually says `signed_out`.

get_user_info

Find nearby Carrefour stores based on customer location (address, city, or postal code) and let the customer pick one on a map. Use ONLY when pickup_mode is DRIVE (store pickup). For LAD (home delivery), use auto_select_delivery_location instead — that tool auto-selects the fulfillment center and shows no map (the user has no choice to make in delivery mode). Prerequisites: set_pickup_mode must be called first. Returns: list of stores; the user picks one, then call set_store with the chosen store.

search_store

Remove a product from the shopping cart by its EAN. This is the only way to drop a line: add_to_cart sets a line's quantity and its API rejects a quantity of 0, so it can lower a quantity but never reach zero. To reduce a quantity instead of removing the product, call add_to_cart with the new quantity. Returns the cart as it stands after the removal, with the same totals as add_to_cart — including total_with_bags_deposit, which drops with the line and is what to announce. This tool renders no widget: the shopping-list widget calls it itself when the customer empties a line or swaps a product, and shows the result. Prerequisites: the product must be in the cart (add_to_cart was called first).

remove_from_cart

Search for MULTIPLE products at once using a list of keywords (e.g., ["milk", "bread", "eggs"]). Use when customer mentions several items in one request. Pass ALL keywords in a SINGLE call — there is no per-call limit; do not split a shopping list into multiple calls. Handles batch searches in one request instead of calling search_products multiple times. The shopping-list widget it renders owns the cart from there on: it mirrors the list into the customer's cart, follows every quantity change and substitution, and offers structuredContent.cart_in_carrefour_link as the way to finish the order on Carrefour.fr. The list it returns is the cart plus the new results, so what the customer already holds stays on screen; a product dropped from the cart does not come back. The products of a list on screen are therefore already in the cart — adding them again through add_to_cart resets the quantities the customer chose. Prerequisites: search_store and set_store must be completed first.

search_multiple_products

Search for a SINGLE product by keyword (e.g., "milk", "bread", "shampoo") in the selected Carrefour store's inventory. Use when customer asks for ONE specific product or category. Prerequisites: search_store and set_store must be completed first. Returns: matching products with EAN for adding to cart. The widget it renders is a browse view: nothing reaches the cart until the customer presses Ajouter on a product. It builds no shopping list — that is search_multiple_products.

search_products

Set the delivery mode for the customer order: LAD (home delivery) or DRIVE (store pickup). Call this FIRST when a customer begins interacting — it determines which stores are available. If the customer changes pickup mode later, verify the location type matches the new mode (full address for LAD, city/postal code for DRIVE).

set_pickup_mode