Guides / Sending agents

Connect a publisher assistant or sending agent to AIX with a self-serve key, the intent and handoff APIs, or MCP, and know the limits before you go live.

A sending agent participates explicitly in the exchange. AIX cannot read a private conversation from a referral tag, browser history, or the fact that a shopper arrived at a store.

Self-serve setup

1. Create a free AIX account and name your sending agent. The console shows your sandbox key (aix_test_pk_…) once. Store it on your server as AIX_PUBLISHER_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 assistant to AIX. The send-intent skill is the full integration guide.
3. Your server calls https://aix.brambles.ai/api/aix with Authorization: Bearer $AIX_PUBLISHER_KEY:

4. Send one test handoff with the sandbox key. It answers test_delivered with a preview of what a store would receive, and the console shows the agent as connected. In the sandbox the AIX link shows a test page naming the destination instead of redirecting, so nothing you test ever reaches a real store.
5. Create the production key (aix_live_pk_…) in the console and set it in production. Sandbox keys never reach a real store and never earn.

MCP hosts can connect https://aix.brambles.ai/api/aix/mcp with the same header and call submit_intent, report_handoff, delete_session and get_activity. The MCP submit_intent tool takes { "intent": { … } } with the same body as POST /intents (its turn input is reserved for Brambles-managed publishers; send exactly one of the two). Self-serve keys are bearer tokens, sent as they are; OAuth client registration is not offered to self-serve agents.

AIX must never slow down your shopper: call it from your server with a short timeout and carry on if it fails. Send only shopping requirements, never names, contact details or the whole conversation. Always send the shopper’s country. Shoppers in the EEA, the UK and Switzerland are shared only with their consent. The skill covers privacy signals, consent and sensitive topics in full.

What each answer means

Every accepted intent comes back with quality: a score from 0 to 100 and the named signals behind it. A store pays only for intents at or above its campaign’s quality bar (40 unless the store sets its own), so specific, believable tasks earn and vague or repeated ones do not. A sandbox intent without a country is accepted with a warning; production suppresses it.

A handoff answers one of these statuses, always with a handoff_url for the shopper and delivered (true or false). A recorded handoff adds handoff_id, environment (live or test), earnings_cents and quality_score.

409 no_active_intent means no accepted intent exists for that session yet; report the intent first. Nothing is charged, and nothing accrues, when a handoff is merely reported.

Limits

Plan for these before you go live; the API reference has the full list.

• Daily caps. A new publisher organization gets at most 100 paid deliveries a day for its first 30 days. After that the default is 1,000 paid deliveries a day; Brambles can raise it for you. Handoffs over the cap still send the shopper to the store, unbilled; your activity counts them under clicks_not_billed.publisher_cap.
• The one-hour window. An AIX link delivers only when the shopper opens it within one hour of the handoff report, and a store can redeem a handoff id within the same hour. A link opened again from a different network address sends the shopper to the store without the receipt.
• Automated opens never count. Crawlers, link previews, prefetch and prerender, HTTP libraries and headless browsers pass straight through to the store; they never deliver and never close the link. So do visits from the server that reported the handoff and clicks faster than a person could make.
• Destinations must be https URLs on the store’s own domain.
• Rate limits, per key and per minute: 120 intents (30 for message-only intents, which run an extraction), 120 handoffs, 120 deletion requests, 60 activity reads, 120 MCP calls. A 429 carries retry_after in seconds.

Earnings and payouts

Publishers pay nothing to use AIX and earn a share of each paid delivery; your dashboard and GET /activity show the share (revenue_share_bps), accepted intents, delivered intents and earnings separately. Earnings accrue when a shopper opens your link or lands with your id and the store is charged; they are paid monthly, on the 10th, through your connected Stripe account, for charges the store has already paid, in USD. Balances under $25 carry forward to the next run. A store charge that is refunded, disputed, credited or voided reverses the matching earning.

The AIX section of your Brambles dashboard reports on each sending agent for the last 7, 30 or 90 days: intent accepted and delivered by day, earnings, the stores you sent shoppers to, and the sales stores reported, as totals. Both the daily figures and every handoff download as CSV. Your earnings also appear on your dashboard's revenue overview and payouts card as AIX shopping intent.

Keep your own links

When a store would pay for the shopper's request (status delivers_on_click), the handoff answers aix_param, like aix=aixho_…. Keep the link you already use, affiliate, ad or plain, and add aix_param to the store URL inside it, before you wrap it, the way you add a UTM tag. landing_url is the store URL with it already added, for a plain link. The store picks it up when the shopper lands (its Brambles assistant, the AIX tag or its own server), and that's when the request is delivered and you earn. The same id rides through any redirect, in in-app browsers and into the store's app.

No link system of your own? Show handoff_url instead: an AIX link (https://aix.brambles.ai/h/…) that delivers on the shopper's click and always lands on the store page. Either way, never open or prefetch the link from your server; visits from the server that reported the handoff, bots and link previews are not counted.

A browser extension can hand the id to the store page with window.postMessage({ type: "aix:handoff", handoff_id }, "*") instead of changing any link.

Agentic checkout

If your agent buys for the shopper through the store's checkout API, there is no visit. Report the handoff as usual and pass its handoff_id in the checkout. The store redeems it, and you are credited as for a click:

• UCP (create, update or complete): "attribution": { "aix_handoff": "aixho_…" }
• ACP (create and complete): "affiliate_attribution": { "provider": "aix.brambles.ai", "token": "aixho_…", "touchpoint": "first" }, with "touchpoint": "last" when you attach it at complete

A store can redeem a handoff once, within an hour of the report. Put nothing else about the shopper in the attribution.

Agent frameworks

If your assistant is built with the Vercel AI SDK, the OpenAI Agents SDK, LangChain or the Claude Agent SDK, give the agent two tools: one that shares the shopper's task when they state or change it, and one that adds AIX to a store URL before it is shown. The key and the HTTP calls stay in your server code, and the shopper's country comes from your server, never from the model. Each guide has both tools ready to paste, with the prompt rules the model needs. For Google ADK, the send-intent skill has the same two tools in Python.

Publishers whose assistant Brambles runs

If Brambles already runs your shopping assistant, there is nothing to integrate. An admin opens AIX in your Brambles dashboard and turns on Share shopping intent from your Brambles assistant (after accepting the publisher terms). Your assistant then shares each shopper's task as they shop, and when a shopper clicks through to a store that would pay, the request is delivered on that click. Your product links, affiliate links and their attribution stay exactly as they are: the request rides along on the store URL inside them. Earnings appear in the same dashboard and are paid monthly through your connected Stripe account.

What is shared

The receiving agent gets a structured snapshot of the current task, not the raw transcript: category, a short summary, the budget state, and the stated requirements, preferences and exclusions with their revision and provenance, plus the destination and product you report and the domain and path of the shopper's page. A new task never inherits an earlier task's budget. The context and receipts guide defines the receiver-facing schema and identifiers.

The receipt carries its permitted uses and expiry. It does not authorize cross-site retargeting or model training, and the receiving agent sees the session only as a pseudonym unique to that store and that task. Removing names and contact details does not make a task anonymous: send only what AIX asks for, and keep your shopper notice in place.

Legacy credentials

Earlier integrations hold admin-issued ain_* credentials and call /api/ain/* paths; both keep working as aliases of the self-serve API, and the ain_ prefix does not mean the product is still named anything other than the Agentic Intent Exchange. New integrations use self-serve keys and /api/aix/*. Keep every credential in your server; never put it in a public page, a browser URL, a model prompt or a skill file.