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.
interpret answers whether or not the hosted helpers are on, so an integration without a model of its own can always call it.
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.
On a marketplace
A client created with a marketplace operator key shops every seller of that marketplace, and no other marketplace. The tools that span sellers work with it; the tools that act on one store’s data need that store’s own key and answer403 to a marketplace key.
What changes with a marketplace key:
- Discovery.
search,compareandgetAlternativesread every active seller of the marketplace. Each result names its seller inmerchant_store_idandmerchant_name, prices are in the marketplace’s own currency, andsearchreportssellers_matched. A product that is not sold on the marketplace answers404incompareandgetAlternatives. - Quote.
quotereturns what the marketplace checkout will charge: each line, asellersbreakdown with each seller’s merchandise total and shipping, marketplace-wide promotions indiscount.amount, and thegrand_total. Tax is not added (tax.status: 'not_charged', withamount: 0): the marketplace checkout charges no tax, sogrand_totalis exactly the amount the shopper pays. A line may name its seller withmerchant_store_id; a variant not sold on the marketplace is flaggednot_available_on_this_marketplace, and one sold by a different seller than named is flaggednot_sold_by_that_seller.shipping_selectionschooses a carrier option a seller offered in an earlier quote. - Hosted helpers.
interpretanddraftCartFromIntentare paid from the marketplace operator’s own AI credits, never a seller’s.interpretreads the message by rules when the operator has not switched hosted helpers on or its credits are exhausted.draftCartFromIntentwith a secret key answers403 helpers_unavailablewhen the operator has not switched hosted helpers on, and402 insufficient_creditswhen the operator’s credits are exhausted; a publishable key receives403 helpers_unavailablewhatever the reason, as on a single store. A draft fromdraftCartFromIntentholds only that marketplace’s items, each naming its seller, and is priced with the marketplace quote;getCartDraftwith the same key re-quotes it, and its items go straight intocreateCheckoutIntent. - Checkout intents. An intent records each seller’s lines in
sellers. Only token confirmation is available. Stock is held when the shopper confirms, for the payment window. Confirming requirescontact.emailandcontact.name, and a shopper credential, when sent, is recorded on the purchase. Confirmation places one marketplace order across the sellers and returns a single payment: the storefront confirmspayment.client_secretwith the payment provider’s own card form. Once paid, each seller receives their own order, marked as placed through a shopping assistant.
Response
Response
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.
On a marketplace key the manifest also carries guest_person_proof_required, whether a guest’s checkout confirmation needs the six-digit code emailed to them (person_proof); it reflects the marketplace’s setting.
hosted_helpers_available says whether the two hosted helpers can be called now. When it is false, interpret reads messages by rules at no cost, and draftCartFromIntent called with a publishable key returns 403 helpers_unavailable, the same answer whatever the reason; a secret key receives the reason. The deterministic tools are always available. assistant carries the name and logo the merchant has given their shopping assistant (name and logo_url, each null when not set), so an assistant shopping the store can present itself the way the store does. 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 store’s catalogue, ranked by the store’s own search. With a query, results keep the order the store’s search gives that query, with the merchant’s search rules applied: a product pinned for the query is shown first, a boosted one is lifted and a buried one is shown last. The store’s synonyms apply, so a search for a word the merchant treats as a synonym also finds the alternatives. The store’s ranking by popularity, promotions and stock applies when the merchant has turned it on, and a sentence that matches no product name (“best products for summer”) is read for its meaning, as in the store’s own search, so the storefront’s search and this one return the same products. The other constraints only remove results, so what remains keeps the store’s order (ranking: "store_search"). A direct match on brand, category, SKU or tags, and the products of a collection the query names, follow the store’s results; the collections are listed in collections, so “summer” finds the store’s Summer collection. Without a query the most-added-to-cart products come first, then products on sale or in an offer, then the rest by name (ranking: "catalogue").
Each result carries match_reasons, naming which constraints it satisfied in words a shopper can read, and badges, short labels for display. A result carries no score.
Paging. limit results are returned from offset (default 0) of one ordered set: the store’s search order, then what this search adds, then what a rule buried. next_cursor, or next_offset, continues it; has_more is false on the last page and total_matched is the size of the whole set. A cursor is valid only for the constraints and personalisation it was issued for; a mismatched one is refused with 400. The order is computed the same way for every page, so a page repeats nothing and skips nothing unless the catalogue changes between requests. Paging applies to a store key; a marketplace search returns one page.
Summary and redirect. summary is a one- or two-sentence lead-in to show above the results, built from facts the search computed over the whole result set rather than the current page, so every page of one search reads the same: the matches, the collection the words named, how many results are on sale and in stock, their price range and the filters applied. Amounts print in the store’s currency format, such as $12.00. It is always present. redirect names where the merchant sends the query (a page address, a collection, a category or a product) with the same shape as the store search’s redirect; it is a suggestion to offer beside the results, nothing navigates on its own, and it is null when there is none.
Badges are listed in display order and are empty on a marketplace key. Which products a rule buries is not disclosed.
price in a result is the shopper price of the product’s default variant (its online sale price when one applies, otherwise its online price), and list_price is that variant’s online 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
It reads one message from a shopper and says what kind of message it is. It works with or without the hosted helpers. A request for products becomes the exact constraint object search accepts, with the parts it could not map to a constraint — a recipient, an occasion — in unresolved, so the assistant can ask a follow-up question or carry them into its own reply.
Only a
shop message carries constraints, so a greeting is never searched for. A reply is composed from what the store has published; a fact the store has not published is never stated, and the reply gives the contact the store did publish. A greeting, a thank-you or a goodbye on its own debits nothing (usage.credits_debited: 0). suggestions holds two or three follow-up prompts drawn from the store’s collections and categories; each text can be sent back to interpret as it is.
With
conversation_id, the request is read as a follow-up: the conversation’s last six turns, the prices of the results last shown and the constraints the previous call returned. A new value replaces the old one, a new attribute is added, “cheaper” sets price_max just below the lowest price last shown and “more expensive” sets price_min just above the highest. The constraints are kept on the conversation for the next follow-up; no turn is added, and only a shop message updates them. The call is refused as the conversation endpoints are (403 shopping_assistant_disabled, history_disabled or guests_not_allowed), and a conversation that is not the caller’s answers 404 not_found.
Without the hosted helpers. A greeting, a thank-you, a goodbye, a question about an order and a plain question about the store (delivery with an optional place, returns, opening hours, payment, contact) are read by fixed rules and cost nothing, whether or not the store has the hosted helpers on; a message that asks several of those is answered for each. Every other message is read by the hosted helper when the store has it on, and by the same rules over the store’s own vocabulary when it does not: a price limit (“under 50”, “between 20 and 40”), in stock, a colour that is one of the store’s own colour values and a category named as the store names it become constraints; any other words stay in query, and a word the rules cannot turn into a filter is listed in unresolved. classified_by is rules or helper and says which read the message. The call never answers 403 helpers_unavailable.
A message read by the hosted helper debits the store’s AI credits at the true cost of the call and reports the amount in usage (credits_debited is 0 for a message read by rules). A helper call that fails keeps no credits, and the message is read by the rules instead. With a publishable key, helper reads count against a daily spend cap the merchant sets (USD 10 a store by default, up to USD 1,000; 0 turns publishable-key helper reads off); over the cap, or when the helpers are off, paused or out of credits, the rules read the message and nothing is debited. Secret keys are not capped.
Naming a conversation. With a conversation_id whose conversation has no title, the first shopping request names it: conversation_title returns a short noun phrase such as Summer Essentials or Blue lamps. A title already set is never changed, and the field is absent otherwise.
A shopper who passes the store’s fair-use budget for the helpers receives 429 agent_rate_limited (see Response codes).
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. A line’s quantity defaults to 1, and a variant’s total across lines is at most 100. 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 AI credits for both model steps; usage reports the total. A request that no in-stock product matches returns 404. With a publishable key, helper calls count against a daily spend cap the merchant sets (USD 10 a store by default, up to USD 1,000; 0 turns publishable-key helper calls off). Over the cap the answer is 403 helpers_unavailable. Secret keys are not capped.
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. quote.shipping_address is null unless the call uses a secret key or the credential of the shopper the draft belongs to.
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: exactly one of xAuthToken, xExternalAuth or xIdpToken. A draft already applied returns 409 conflict. When no item can be added, the call returns 409 with the same envelope as a success: applied[].error gives the cart’s reason for each refused line and cart is null.
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 quotes at most 25 lines.
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 or act on only the shopper’s own records, identified by their credential.getShopperContext and getReorderSuggestions read the shopper’s order history for personalisation, and standing instructions act on the shopper’s behalf over time, 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. recent_order_count is the number of the shopper’s most recent non-cancelled orders the other figures are computed from, at most 50; it is not a lifetime count. The example is a shopper with no orders yet.
Response
getWishlistInsights
The shopper’s wishlist (the first 25 items; the two counts cover those items) 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, drawn from the 10 most-ordered items of the shopper’s 50 most recent orders, 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
requestReturn
Lodges a return for one of the shopper’s own orders — the action getOrderStatus lists as request_return while the order is inside the store’s return window. The call returns 422 when the store has returns switched off (returns_disabled) or the order was not paid or was cancelled (order_not_paid). Omit items to return every line in full, or name lines with order_item_id and a quantity (and optionally a condition). reason_code is one of damaged, defective, wrong_item, not_as_described, wrong_size, no_longer_needed, arrived_late or other; other also needs reason_description. return_type is full_refund (the default), partial_refund, exchange or store_credit.
The return arrives as pending: the store reviews it and decides the refund, and the shopper is emailed that it was received. It is the same return a shopper lodges through Returns, so it appears in the store’s returns queue like any other.
Response
error.message. An order that is not the shopper’s own answers 404.
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, and the shopper’s approval is collected in one of two ways, chosen with confirmation_mode:
token(the default) — 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 throughclient.payments.initializePayment, exactly as for any other order.hosted— the intent also returnsconfirmation_url, a link to the store’s own confirmation page. The assistant gives the link to the shopper, and the page shows the frozen quote, takes the shopper’s contact details, confirms the intent and passes payment to the store’s payment provider: a Stripe Checkout redirect, a Paystack popup, PayPal buttons, or a custom provider’s redirect. Card details are entered only on the provider’s page. This suits an assistant that has no checkout interface of its own.
Idempotency-Key returns the intent with confirmation_token and confirmation_url set to null and replayed: true. getCheckoutIntent, confirmCheckoutIntent and cancelCheckoutIntent do not return either field. It is single use: a second confirmation returns 409 intent_not_pending, and a wrong token returns 403 invalid_confirmation_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. confirmation_mode is token (the default) or hosted; in token mode confirmation_url is null.
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
hosted mode the response is the same intent with confirmation_mode: "hosted" and a confirmation_url of the form https://{store host}/confirm/{intent_id}#t={confirmation_token}. The token travels in the URL fragment, which a browser does not send to any server.
data above is shortened to the fields that differ by mode; items and quote are as in the token-mode response.
An intent holds stock, and a publishable key can be read from any storefront, so intents created with a publishable key are bounded:
Past a limit the intent is refused with
409 hold_limit_reached and the limit in details.limit, or, for the hourly limit, 429 rate_limited with a Retry-After header. A secret key — the store’s own server — is bound only by its plan.
An address here is the requester’s network (IP) address. Requests from a recognised assistant platform are limited per platform instead: a request that carries a valid Web Bot Auth signature (HTTP Message Signatures with tag="web-bot-auth", verified against the platform’s published key directory) or that arrives from the IP ranges a platform publishes for its assistant traffic counts against that platform’s allowance of 600 new intents an hour and 100 waiting per store. Recognised platforms include ChatGPT (agent and user-initiated requests), Claude, Perplexity, Google-Agent, Amazon Bedrock AgentCore Browser and Cloudflare Browser Run. The per-intent unit limits and the share-of-stock limit apply to them unchanged, and a request whose signature does not verify is treated like any other.
getCheckoutIntent
The intent’s status and its frozen quote. status is one of pending_confirmation, confirmed, expired, cancelled or completed. The shopper’s personal data — customer_id and quote.shipping_address — is included for a secret key, or for a publishable key sent with a shopper credential (xAuthToken, xExternalAuth or xIdpToken) for the intent’s own customer. A publishable key alone, a guest intent read with a publishable key, or another shopper’s credential receives the intent without those two fields; status, lines and totals are the same. A credential that is sent and cannot be verified returns its own error. The response below is a publishable-key read of a guest intent.
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.
A guest confirmation is completed only with a six-digit code emailed to contact.email, unless the merchant has turned that check off. The first call sends the code and answers 409 person_proof_required, with the masked address in error.details.sent_to; the code is valid for 15 minutes. Send the same request again with the code as person_proof. A wrong code returns 403 invalid_person_proof; each code allows five tries (429 too_many_attempts), and an intent gets at most five codes, at least 60 seconds apart (429 too_many_codes). Confirming with the shopper’s credential never asks for a code. With a marketplace key, the marketplace operator’s setting decides whether the code is asked.
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. When the intent holds no stock and an item is no longer available in the quantity quoted, the response is 409 out_of_stock: nothing is placed or charged, and the intent stays pending. 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. The cancelled intent carries the shopper’s personal data on the same terms as getCheckoutIntent; the response below is a publishable-key cancel.
A secret key may cancel any intent. With a publishable key, an intent prepared for a signed-in shopper, or created with confirmation_mode hosted, is cancelled only with its confirmation_token in requestBody or with that shopper’s credential; anything else returns 403 forbidden, and a wrong token 403 invalid_confirmation_token. A guest intent in token mode is cancelled with its id alone. With a marketplace key, a secret key cancels any of that marketplace’s intents, and a publishable key cancels only with the intent’s confirmation_token; a shopper credential does not stand in for it.
Response
Standing instructions
A standing instruction (a mandate) is a purchase the shopper asks for in advance and confirms later: reorder an item on a schedule, or buy it when it comes back in stock or drops to a price. Each is bounded on every side, and none of them pays for anything by itself.
Every kind fires only when the item is available at or below
max_unit_price per unit and the store can price shipping and tax for the stored address. quantity is 1–10. An instruction expires after expires_in_days (at most 365, default 180), and a shopper can keep at most 10 with one store.
When the condition holds, Galactic Core prepares a hosted checkout intent for the shopper at the price it found, sends the agent.mandate.triggered webhook event with the intent’s confirmation_url, and emails the shopper that link under the store’s own name. The prepared intent stays open for 48 hours and holds no stock; the shopper confirms on the store’s page, and nothing is paid until they do. If the shopper withdraws personalisation consent, their instructions pause (status: 'paused', status_reason: 'consent_revoked').
Standing instructions need the shopper’s credential and their personalisation consent.
createMandate
Response
max_unit_price is in the store’s currency, recorded in currency. interval_days is required for reorder and not allowed for the other kinds. shipping_address needs line1 (or latitude and longitude) and country. A bound that is not met is refused with 400:
409 mandate_limit, and an address the store does not deliver to with 409 shipping_not_deliverable.
listMandates
The shopper’s standing instructions with this store, newest first (at most 50), in every status: active, paused, cancelled, completed or expired. last_intent_id is the checkout intent prepared the last time one fired.
Response
cancelMandate
Cancels one of the shopper’s standing instructions. A checkout it already prepared is unaffected and expires unless the shopper confirms it. Cancelling one that is no longer active answers 409.
Response
Subscribe & Save
An assistant can show a product’s Subscribe & Save offers and, with the shopper’s consent, prepare and manage the shopper’s subscriptions. Every method here returns the standard envelope and requires the shopper’s personalization consent; the shopper methods require the shopper’s credential. A subscription is never confirmed through the API:createAgentShopperSubscription returns a hosted checkout link on which the shopper reads the terms and agrees to them. See Subscribe & Save.
getSubscribeSaveOffersForProduct
Subscribe & Save offers on a product.
The Subscribe & Save offers that cover a product: each offer’s label, the delivery intervals it allows,
its discount, any different discount on the first delivery, the minimum number of deliveries, the yearly
skip limit and whether shipping is free. The list is empty when the store offers none.
With variant_id, each offer also carries per_delivery: the price of one delivery of that variant
(times quantity) for the first delivery and for every later one, worked out from the variant’s live
catalogue price. These prices cover the items only; shipping and tax are added at checkout. Without
variant_id, per_delivery is null.
A subscription is started with POST /v1/agent/me/shopper-subscriptions.
Response
GET /v1/agent/products/{id}/subscribe-save
listAgentShopperSubscriptions
List the shopper’s Subscribe & Save subscriptions, newest first (at most 100).
The shopper’s Subscribe & Save subscriptions with this store, newest first: status, delivery interval,
the date of the next delivery, the items, the terms the shopper accepted, and the saved card’s brand and
last four digits. Requires the shopper’s credential and personalization consent.
Response
GET /v1/agent/me/shopper-subscriptions
createAgentShopperSubscription
Start a Subscribe & Save subscription.
Prepares the first order of a Subscribe & Save subscription as a hosted checkout and returns the link
the shopper opens. The items are priced for the address with the offer’s first-delivery discount, and
the stock is held for 30 minutes, as for any checkout intent.
The shopper confirms the order on the store’s own checkout page, never through the API. The page shows
the terms in subscribe_save.terms: the items, the price per delivery with the discount, the interval,
that it renews until cancelled, how to cancel, the minimum number of deliveries and the dates of the
first charge and the next delivery. The shopper ticks an unticked consent box, and the exact wording
accepted is recorded with the subscription. Confirming a subscription with the confirmation token
through POST /v1/agent/checkout-intents/{id}/confirm answers 409 hosted_confirmation_required.
The card used for the first payment is kept for the later deliveries where the store’s payment provider
allows it; otherwise the shopper is sent a payment link for each delivery. The subscription begins when
the first order is paid, never before.
Requires the shopper’s credential and personalization consent. A request without a shopper credential
answers 409 account_required. A replay of the same Idempotency-Key returns the same intent with
confirmation_token and confirmation_url null.
Response
POST /v1/agent/me/shopper-subscriptions
updateAgentShopperSubscription
Change a Subscribe & Save subscription.
Changes how often one of the shopper’s subscriptions delivers, or what it delivers. Send either
interval_unit with interval_count (one of the intervals the offer allows), or items, the full new
list of products and quantities (each covered by the offer). The next delivery date is recalculated from
the last delivery. A store can turn off item changes for shoppers, in which case items answers
409. Requires the shopper’s credential and personalization consent.
Response
POST /v1/agent/me/shopper-subscriptions/{id}/update
pauseAgentShopperSubscription
Pause a Subscribe & Save subscription.
Pauses one of the shopper’s subscriptions. No delivery is prepared or charged while it is paused. With
until, deliveries resume on that day (from tomorrow, up to a year ahead); without it, the subscription
stays paused until the shopper resumes it. Only an active subscription can be paused. Requires the
shopper’s credential and personalization consent.
Response
POST /v1/agent/me/shopper-subscriptions/{id}/pause
skipAgentShopperSubscription
Skip the next Subscribe & Save delivery.
Skips the next delivery of one of the shopper’s subscriptions; the delivery after it stays on schedule.
The offer may limit how many deliveries can be skipped in a year, and a delivery that is already being
prepared cannot be skipped. Requires the shopper’s credential and personalization consent.
Response
POST /v1/agent/me/shopper-subscriptions/{id}/skip
cancelAgentShopperSubscription
Cancel a Subscribe & Save subscription.
Cancels one of the shopper’s subscriptions. When the offer has a minimum number of deliveries that has
not yet been reached, the cancellation is requested now and takes effect after the last of them;
cancel_effective_on is that date, and the subscription’s own cancel_effective_on carries it too.
Otherwise it takes effect at once.
Send preview: true to learn the effective date and the deliveries still owed without cancelling, so
the shopper can be told before they decide. Requires the shopper’s credential and personalization consent.
Response
POST /v1/agent/me/shopper-subscriptions/{id}/cancel
Saved conversations
A storefront’s shopping assistant can keep its conversations so a shopper returns to them. The caller is a signed-in shopper (one ofxAuthToken, xExternalAuth or xIdpToken) or, when the store allows guests, a guest session (xSessionId). A shopper credential wins when both are sent. Only conversations in the API key’s environment are returned.
The store’s choices are published in the store information as store.shopping_assistant. While the assistant is off the calls answer 403 shopping_assistant_disabled; while conversations are not saved, 403 history_disabled; for a guest session while guests are not allowed, 403 guests_not_allowed. Deleting is never refused by these settings. A shopper keeps at most 50 conversations and a guest session 10; starting one more deletes the least recently active. Money in a turn’s results is in major units (12.50), as the storefront showed it.
Every conversation call returns the standard envelope with currency: null.
listAssistantConversations
The caller’s saved conversations, most recently active first. Limited to 120 reads a minute per address and store.
Response
createAssistantConversation
Starts a saved conversation for the caller. Limited to 60 writes a minute per address and store.
Response
getAssistantConversation
One of the caller’s conversations with every turn in order. A conversation that does not exist and one that belongs to someone else both answer 404 not_found.
Response
appendAssistantConversationTurn
Saves one turn exactly as the storefront showed it. Nothing is generated or changed. A conversation holds at most 200 turns (409 conversation_full); start a new one after that. Send idempotencyKey to make a retry safe: the same key on the same conversation returns the turn already saved, with 200, instead of adding it twice.
Response
deleteAssistantConversation
Deletes one of the caller’s conversations and its turns. Someone else’s conversation answers 404 not_found.
Response
deleteAllAssistantConversations
Deletes every saved conversation of the caller in the API key’s environment.
Response
adoptGuestAssistantConversations
Call once after a guest signs in, with the new shopper credential and the guest’s xSessionId. Every saved conversation of that guest session becomes the shopper’s and the guest session no longer reaches it. The shopper’s 50-conversation limit then applies, and pruned counts any deleted to keep it. Calling it again moves nothing.
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 AI 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
AI credits
The hosted helpers are paid for from the store’s AI credit balance, which the merchant funds. The shopper never pays for them. Each call the helper handles is debited at its true cost, reported inusage.credits_debited; a call that fails keeps no credits. An interpret message read by rules debits nothing.
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, interpret reads the message by rules and debits nothing. draftCartFromIntent called with a publishable key receives 403 helpers_unavailable with no reason, whatever the cause, so no store reads publicly as switched off or out of credits; a secret key receives the reason: 403 helpers_unavailable with details.reason (disabled, paused or unavailable), or 402 insufficient_credits. 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 four events for checkout intents and standing instructions:feature.status_changed fires with feature: "agent_hosted_helpers" when the hosted helpers become available or unavailable, and store.updated lists agent_assistant_name or agent_assistant_logo_url in changed_fields when the merchant renames the assistant or changes its logo.
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.

