Guides / Receiving agents

Receive a verified AIX shopping brief over HTTPS or MCP, continue the conversation, and acknowledge actual use. Catalog access is optional.

Start with context-only continuity: receive the shopper's selected requirements and let your existing agent continue without asking them to start over. You do not need to upload or connect a product catalog to AIX. Your own catalog/search tools become useful when you want real product recommendations, prices, or availability.

Self-serve setup

1. Create a free AIX account and a receiving agent. The console shows your sandbox key (aix_test_rk_…) once. Store it on your server as AIX_RECEIVER_KEY.
2. Paste the console’s setup prompt into your coding agent. Or install the AIX skills once with npx skills add https://aix.brambles.ai and ask the agent to connect your store to AIX. The receive-intent skill is the full integration guide.
3. Your server calls https://aix.brambles.ai/api/aix with Authorization: Bearer $AIX_RECEIVER_KEY:

A shopper handed off to your site lands with ?aix=<handoff_id> (added to the publisher's own link) or ?aix_receipt=<receipt_id> (after a click on an AIX link); see Capture the shopper's arrival. Fetch the context for the receipt on your server and start your assistant or ranking from it. If your agent is built with Google ADK or LangChain, the receive-intent skill shows how to give it the request as data (session state with {aix_request?} in ADK, a @dynamic_prompt middleware in LangChain). MCP hosts can connect https://aix.brambles.ai/api/aix/mcp with the same header.

4. To receive real shoppers, verify the domain they land on in the console. If your Brambles account email is at that domain, the site already runs your Brambles shopping assistant, or you open a one-time link the console emails to any company address there, it verifies instantly and you are approved automatically. Otherwise add the meta tag, DNS TXT record or file the console shows (it says where to add them on Shopify, WooCommerce, Wix, Squarespace, BigCommerce and other platforms), and Brambles reviews you once. Then add a card and start a campaign with a monthly budget. You pay per delivered intent, billed through Stripe: an intent is delivered when a shopper arrives on your site through it (and passes the bot and fraud checks), or when your checkout redeems it from the shopper's agent. Sandbox deliveries are always free.

Testing your receiver

Three ways to get a free, signed test delivery addressed to your sandbox identity (<agent id>:test), all the same delivery: the console's Send a test delivery button, POST /test-deliveries with your sandbox key, or POST /handoffs/{handoff_id}/redeem (or the MCP redeem_handoff tool) with your sandbox key and any well-formed aixho_ id. There is no separate MCP tool for test deliveries. Acknowledge the test delivery verified to flip the console to Connected and unlock the production key; a bare HTTP 200 from your webhook leaves it waiting for a retry.

Principals and keys

Receipts, references and acknowledgments are keyed on your principal id: your agent id (for example aixapp_dcad0746ebb68099bdf7) with a production key, <agent id>:test with a sandbox key. There is no :live suffix. Self-serve keys are bearer tokens, sent as they are; OAuth client registration is not offered to self-serve agents. A missing, revoked or unknown key answers 401 unauthorized; a key without the scope an operation needs answers 403 insufficient_scope (GET /deliveries/{receipt_id}, POST /deliveries/ack and GET /receiver/config answer 401 in both cases).

Capture the shopper's arrival

Publishers keep their own links, so the AIX id can reach you through any affiliate or ad redirect, as ?aix=<handoff_id>, or as ?aix_receipt=<receipt_id> after a click on an AIX link. Pick one way to pick it up:

• The AIX tag (any site, no server code). Add one line to every page:

  htmlCopy

  <script src="https://aix.brambles.ai/aix-tag.js" async></script>

  It takes the id off the address bar, claims a handoff for your site (only on your verified domains), keeps the receipt id in a first-party cookie, aix_receipt, for an hour, and fires an aix:arrival event with event.detail.receipt_id for your own scripts. Your server reads the request with GET /deliveries/{receipt_id}.

• Your server. Read aix or aix_receipt on the landing request. Redeem an aix id with POST /handoffs/{handoff_id}/redeem and {"via": "landing"}, which answers the receipt id.

• A Brambles store. Your Brambles shopping assistant already does this.

In your app, the universal or app link carries the same parameters. A shopping extension may hand the id to your page with window.postMessage({ type: "aix:handoff", handoff_id }, "*") instead of changing any link; the AIX tag and the Brambles assistant listen for it. Each id is delivered once, within an hour of the handoff report, and only on your verified domains, and a shared URL never hands one shopper's request to another visitor: a link opened again from a different network address reaches your store without the receipt.

Brambles stores: one-click receiving

If your store runs the Brambles shopping assistant, there is nothing to build. Its domain verifies itself when you add it in the console, because your assistant is already on the homepage. Once your receiving agent has a live campaign, a shopper who arrives through AIX is greeted by your assistant with what they asked for, so they don't start over: on desktop and in inline chats at once, on phones when they open the chat. The request stays on the server, is used only in that shopper's chat for 30 minutes, and is acknowledged applied once the assistant has greeted them. Turn the greeting off in the console's Production tab.

Agentic checkout (UCP, ACP)

A shopper's agent can buy through your checkout API without visiting your site. When it was sent to you through AIX, it passes the AIX handoff id in the checkout:

• UCP: "attribution": { "aix_handoff": "aixho_…" } on the checkout.
• ACP: "affiliate_attribution": { "provider": "aix.brambles.ai", "token": "aixho_…" }.

When your checkout handler sees one, redeem it from your server:

POST https://aix.brambles.ai/api/aix/handoffs/aixho_…/redeem
Authorization: Bearer $AIX_RECEIVER_KEY

{"redeemed": true, "receipt_id": "aindeliv_…", "context_url": "…"} delivers the shopper's request and charges it under your live campaign, exactly as a click would: once per handoff, and a repeat answers "duplicate": true for free. Fetch context_url for the request, use it, and acknowledge as usual. {"redeemed": false, "reason": …} (for example expired after an hour, or not_redeemable) delivers and charges nothing. Only the store a handoff was for can redeem it; any other id answers 404. With your sandbox key, any aixho_ id returns a free test delivery, so you can test the checkout path. Never let a redemption failure hold up the checkout.

Verify, store, acknowledge

Each delivery is the aix.delivery.v1 envelope: schema_version, the exact reference, the signed receipt, your ain_member_id, delivered_at and acknowledgment_url. Read the unmodified body and the x-ain-signature header (t=<unix seconds>,v1=<hex>), check the HMAC with the receiver_secret from GET /receiver/config, reject bodies older than a minute, then verify the receipt against the pinned issuer and https://aix.brambles.ai/.well-known/jwks.json, store it keyed by receipt_id, and answer with your signed verified acknowledgment as the response body. A plain HTTP 200 does not acknowledge verification; the delivery stays waiting for a retry until a signed acknowledgment arrives, by webhook response or POST /deliveries/ack. The Node and Python cards on the quickstart carry the signature check; the context and receipts guide has the receipt profile.

Record applied (agent_context_loaded or catalog_ranked) only after your backend actually put the brief into the shopper's agent turn or ranked your catalog with it, and only after a verified event for the same receipt. Make retries safe by keying on receipt_id: AIX deduplicates repeated logical events and answers the same event_id with duplicate: true. Keep the fixed integration instructions separate from the untrusted shopping data. An acknowledgment proves a reported backend event, not that a model understood the brief or that a sale occurred. If your callback fails, do not report applied. Acknowledgments and receipt retrieval never charge again.

Current shopper instructions take precedence over an old brief: before using a receipt, check that it matches the shopper's current task and has not been superseded by a correction or a declined offer of help, and stop using it at its expiry.

Report sales and see your results

When an order follows a delivery, report it from your order or checkout code. The receipt id arrives on the landing URL (aix_receipt), and the AIX tag keeps it in the first-party aix_receipt cookie for an hour:

POST https://aix.brambles.ai/api/aix/deliveries/aindeliv_…/outcome
Authorization: Bearer $AIX_RECEIVER_KEY
Content-Type: application/json

{"converted": true, "order_value_cents": 12999}

Send {"converted": false} when the shopper left without buying. Only a receipt you verified can be reported, and a later report replaces the earlier one. Over MCP the tool is report_outcome. Link a receipt to an order only to report it, never to identify the shopper.

The AIX section of your Brambles dashboard reports on your receiving agent for the last 7, 30 or 90 days:

• deliveries by day and what they cost;
• what shoppers asked for, kept for 30 days as the terms require;
• where shoppers came from (chat, search results, recommendations) and how many sending agents sent them;
• your recent deliveries, with what your systems did with each;
• the sales you reported.

Both the daily figures and every delivery download as CSV. Publishers see only totals of the sales you report, never a receipt or an order. The report doesn't name the publishers that sent your shoppers, just as receipts don't.

Optional: use your own catalog

Connect the agent's existing product-search tool when you want catalog-assisted recommendations. Map the brief's required, preferred, and excluded facts to your actual product attributes; the activation object in GET /deliveries/{receipt_id} already derives filters, boosts, exclusions and a price constraint. Unknown or cleared budgets remain unknown. Ranking is allowed under the signed contextual_product_ranking permitted use; record catalog_ranked only after your backend actually applied a ranking.

MCP for your agent backend

The endpoint is https://aix.brambles.ai/api/aix/mcp using Streamable HTTP, with the same bearer header. A key sees only the tools it can call, so a publisher key is never offered receiver tools, and any sending agent with a production publisher key can supply intent for your store once your domain is verified and a campaign is live.

Connecting MCP does not install skills, add catalog access, or make an agent act automatically. The host must still load the brief into its agent, and onsite assistance, cart changes, purchases, outbound contact, background monitoring and further sharing each need the appropriate permissions and integrations.

Billing

You pay only in production, only through a campaign you start, and only for delivered intents: a shopper's click on an AIX link, their landing on your site with the id, or your redemption of the handoff id, confirmed by Brambles' checks. Nothing is charged when a publisher merely reports a handoff, and a campaign pays only for intents at or above its quality bar (min_quality, 0 to 100; the default is 40). A campaign's monthly budget is an integer in cents, at least the price per intent and at most 100,000,000, and AIX never charges a campaign more than its budget in a month.

Charges are metered through Stripe Billing on the card you save in the console: Stripe invoices you, in USD, when the month's usage reaches $25 and again at month end, and sends receipts and invoices. Nobody prepays. Refunds, credits and disputes are handled through Stripe; a charge that is refunded, disputed, credited or voided is reversed, and the publisher's matching earning is reversed with it. A failed payment pauses delivery until a payment succeeds.

Outcome reporting uses receipt_id, not only intent_id. Report actual observed outcomes; these are merchant assertions, not independently verified conversions or proof of lift. Product purchase amounts are separate from context-delivery charges.

Legacy credentials

Earlier integrations hold admin-issued ain_* credentials and call /api/ain/* paths; both keep working as aliases of the self-serve API. The signing issuer and credential type keep their original identifiers: use the issuer from GET /receiver/config, not the hostname inferred from an incoming receipt or your API URL. Independent per-agent receiver-secret rotation is not available in v1; contact hello@brambles.ai to rotate one.

See the context and receipts guide, sending-agent guide, and overview.