AgentService class (accessed via client.agent) is a set of tools for an AI shopping assistant working on a store. The assistant is yours — your model, your prompts, your conversation design, in a chat widget, a voice interface or a third-party assistant. These tools supply what the model cannot know or must not guess: live stock per variant, the price a shopper is actually charged, the promotion that applies, shipping and tax for an address, the store’s return window, and a checkout the shopper confirms themselves.
The tools fall into three kinds:
An assistant built on your own model uses only the deterministic tools and never touches the credit balance. The hosted helpers exist for integrations without a model of their own, or that would rather not spend one on turning a sentence into search filters.
An assistant never places an order or takes payment by itself. It can price a basket and hold the stock with a checkout intent; the order is placed only when the shopper confirms, and payment then follows the store’s normal payment flow.
The response envelope
Every tool returns the same envelope:
The two hosted helpers add
usage: credits_debited (in US dollars) and model_class. Most read tools accept fields, a comma-separated list of top-level data keys to return, to keep an assistant’s context small.
Credentials
Most tools need only an API key, and a publishable key is enough. Tools that read or act on one shopper’s own data also need that shopper’s credential — exactly one of:getUsage is the only tool that requires a secret key.
Discovering products
getCapabilities
The tool manifest for the store: every tool with its HTTP operation, a JSON Schema for its request and for its response data, the credential it needs, and its cost class (deterministic or hosted_helper). An assistant can register its tools from this manifest instead of from a hand-written list.
hosted_helpers_available says whether the two hosted helpers can be called now. When it is false, hosted_helpers_reason gives the reason — disabled (the merchant has not turned them on), paused, or insufficient_credits. The deterministic tools are always available. The response below shows one entry from the manifest’s tools array, with its request schema shortened to three properties.
Response
search
Constraint search over the catalogue. Every constraint is optional; each result carries match_reasons naming which constraints it satisfied, so an assistant can explain a recommendation from the data rather than from its own impression of the product.
price in a result is the catalogue selling price. What a shopper pays after dynamic pricing, promotions, shipping and tax comes from quote. semantic_search reports whether ranking by meaning was used for this call.
Response
interpret
A hosted helper. It turns a request in plain language into the exact constraint object search accepts, and lists in unresolved the parts it could not map to a constraint — a recipient, an occasion — so the assistant can ask a follow-up question or carry them into its own reply.
It debits the store’s Agent Compute credits at the true cost of the call and reports the amount in usage. A call that fails keeps no credits. query is required, up to 500 characters.
Response
getProductContext
A dossier on one product: each variant with its live stock and the price a shopper is charged, the promotion that applies to a single unit, published specifications (per variant and merged), the review summary with its rating distribution, where the store ships and at what base fees, and the store’s return window.
A specification the merchant has not published is absent — the dossier never fills a gap by inference. The exact shipping fee for a particular address comes from quote.
Response
compare
Two to five products side by side: price and price range, stock, rating and the return window, with spec_rows aligning every published specification across them. A specification one product does not publish is null in its column.
Response
checkFit
Checks one product against a set of constraints and sorts them into met, missed and unknown. unknown holds constraints that cannot be judged because the merchant has not published that attribute — the difference between “not black” and “colour not stated”. A price constraint is met when any variant’s price fits it, and a stock constraint when any variant is in stock. When a constraint is missed or unknown, alternatives lists in-stock products that meet more of them.
Response
getAlternatives
Alternatives to a product by mode: similar, cheaper (priced below the product’s lowest variant), in_stock, or same_spec (matching every specification both products publish, ignoring identity fields such as a model number). basis reports where the candidates came from — recommendations where the store’s recommendations are available, otherwise same_category. limit is 1–20, default 5.
Response
Pricing and carts
quote
The landed price of a basket: each line at the price a shopper is charged, the best promotion for the basket, shipping and tax for the address, and the grand total. The steps run in the order an order is priced — the promotion first, shipping on the discounted amount, tax last — so a quote and the order placed from it agree.
A line that cannot be bought as asked is flagged with available: false and an unavailable_reason; it stays in lines and is left out of the totals. Without an address, shipping and tax report status: 'address_required' and total_is_final is false. country (ISO 3166-1 alpha-2) is needed for tax; line1 with city, or latitude with longitude, for shipping.
Response
createCartDraft
A draft cart, kept apart from the shopper’s live cart, returned with its quote. An assistant can build and revise a draft through a conversation without touching what the shopper has already put in their cart. A draft expires after 24 hours. Sending a shopper credential records the draft against that shopper; without one the draft is anonymous.
Response
draftCartFromIntent
A hosted helper. An intent such as “a birthday gift for a runner, under 80” and an optional budget become a priced, stock-checked draft. The request is turned into constraints, the catalogue is searched for in-stock products, and a model chooses from those results only, by variant — it never supplies a price. Every amount in the draft comes from the quote, and over_budget reports whether the quoted total exceeds the budget. selections gives the reason for each choice.
It debits the store’s Agent Compute credits for both model steps; usage reports the total. A request that no in-stock product matches returns 404.
Response
getCartDraft
A draft with a fresh quote: prices, promotion and availability, and — when the draft was created with an address — shipping and tax, all read again at the time of the call.
Response
applyCartDraft
Adds each of the draft’s items to the shopper’s live cart and returns the cart. applied reports the outcome per item. A draft is applied once. Requires the shopper’s credential.
Response
getCartInsights
What an assistant might point out about a cart: lines that can no longer be bought as they are, prices that changed since each item was added, the promotion the cart qualifies for, the gap to free shipping for a destination, and complementary items where the store’s recommendations provide them.
It reads a draft when draftId is given; otherwise the shopper’s live cart, identified by their credential or, for an anonymous cart, by xSessionId. Pass the destination (country, and optionally postalCode, city, state, line1) for the free-shipping gap.
Response
The shopper’s own data
These tools read only the shopper’s own records, identified by their credential.getShopperContext and getReorderSuggestions read the shopper’s order history for personalisation, so they also require the shopper’s consent; without it they return 403 consent_required. This consent is separate from email marketing consent.
getConsent
Whether the shopper has allowed agent tools to use their own history.
Response
setConsent
Records the shopper’s choice. Pass personalization: false to revoke.
Response
getShopperContext
From the shopper’s own data only: sizes they have ordered, the price band of what they buy, their recent orders, and their wishlist with availability. Requires consent. The example is a shopper with no orders yet.
Response
getWishlistInsights
The shopper’s wishlist with each item’s current stock and the price they would be charged now, and whether that price is below the item’s list price — the basis for “back in stock” and “now cheaper” prompts.
Response
getReorderSuggestions
Items the shopper has bought before, most often first, with how many they usually buy and the current price and stock. Requires consent.
Response
getOrderStatus
The status of one of the shopper’s own orders: order and payment status, tracking, the return window for this order, and allowed_actions — what the shopper can do next, such as request_return until a date, track_shipment, or complete_payment. placed_through_agent is true for an order placed from a checkout intent.
Response
Checkout intents
A checkout intent is how an assistant hands a purchase to the shopper. The assistant creates the intent; the basket is priced for the address, the price is frozen, and the stock is held for 30 minutes. It returns a single-useconfirmation_token. The shopper reviews the frozen quote in your interface and approves it, and your application confirms the intent with the token. Only then is an order placed, with payment pending; payment is then taken through client.payments.initializePayment, exactly as for any other order.
The token is returned once, when the intent is created, and is stored only as a hash — a retry with the same Idempotency-Key returns the intent without it. It is single use: a second confirmation returns 409 intent_not_pending, and a wrong token returns 403 invalid_token without disclosing anything about the intent. An intent that is not confirmed in time reads as expired and its stock is released.
createCheckoutIntent
Creates an intent for a basket and an address. idempotencyKey is required; a retry with the same key returns the same intent. A shopper credential, when sent, ties the intent to that shopper, who must then confirm with it.
The intent is refused, with the quote in error.details, when a line cannot be bought (409 items_unavailable), the store does not deliver to the address (409 shipping_not_deliverable), or shipping or tax cannot be priced for it (409 quote_incomplete).
Response
getCheckoutIntent
The intent’s status and its frozen quote. status is one of pending_confirmation, confirmed, expired, cancelled or completed.
Response
confirmCheckoutIntent
The shopper’s approval. Send the confirmation_token with the shopper’s credential, or — for a guest — with contact (email and name, optionally phone). payment_method optionally records the method the shopper intends to use.
The basket is priced again first. If anything the shopper pays has changed — a line price, the discount, shipping, tax or the total — the response is 409 quote_changed with the new quote in error.details, and nothing is placed: show the shopper the new figures and create a new intent. Otherwise the order is placed with payment pending, using the held stock, and the response carries payment.initialize_body — the body client.payments.initializePayment takes, which your server sends signed like any other payment initialisation — and the store’s payment methods.
Response
cancelCheckoutIntent
Cancels a pending intent and releases its stock hold at once.
Response
Store and usage
getStorePolicies
The facts a shopper asks before buying: whether the store accepts returns, its return window and reasons, where it ships and the base fees, the payment methods it accepts, and its currencies. With a live key, only payment methods configured for live payments are listed.
Response
getUsage
The store’s Agent Compute credit balance, the state of its automatic recharge and of its hosted helpers, and this month’s hosted-helper spend by tool, with production and sandbox shown separately. Requires a secret key, so call it from your server.
Response
Agent Compute credits
The hosted helpers are paid for from the store’s Agent Compute credit balance, which the merchant funds. The shopper never pays for them. Each call is debited at its true cost, reported inusage.credits_debited; a call that fails keeps no credits.
Hosted helpers are off until the merchant turns them on, which requires automatic recharge with a monthly limit, so the balance does not run out mid-conversation. When the helpers cannot run, they answer 403 helpers_unavailable (not enabled, or paused) or 402 insufficient_credits, and every deterministic tool keeps working — an assistant can fall back to building constraints itself and calling search. Calls made with a test key run the model too and debit the same balance; getUsage reports that spend separately.
The hosted helpers carry an additional rate limit of 60 calls a minute per client and 1,000 an hour per key, on top of the standard limits.
Webhook events
A store’s webhook endpoints receive three events for checkout intents:order.created carries source_channel — storefront, or agent for an order placed from a confirmed checkout intent — and, for an agent order, agent_client_ref, which identifies the API key (key:<id>) or the connected application (connect:<id>) that created the intent.