BazaarOn.ai — Developer docs · Build an agent that shops

Overview

BazaarOn is an international-grocery marketplace with a first-class agentic interface. Two things matter before you write any code:

Discovery is open. Browsing the catalog, searching, matching recipe ingredients, reading the product feed, and looking up an order need no key.
Buying needs a key. Creating carts and checking out require an agent API key (bzk_…) — so any agent can evaluate the catalog, but only an authorized one can transact.

Base URL for every example on this page: https://bazaaron.ai

Quickstart — your first shopping agent

From zero to a placed order in three steps.

1 Get an API key

Sign in as a shopper at /shop → open your account → Your shopping agent → Create key. You'll get a secret like bzk_a1b2c3… — copy it once; it's never shown again. (Store operators can also issue keys from the admin.) Send it on write requests as a bearer token:

Authorization: Bearer bzk_your_key_here

Discovery calls below need no key — try them right now.

2 Discover products

POST https://bazaaron.ai/ucp/v1/catalog/search
Content-Type: application/json

{ "query": "basmati rice" }

Response (trimmed) — note amount is in integer cents and id is the product id you'll add to a cart:

{
  "capability": "dev.ucp.shopping.catalog",
  "query": "basmati rice",
  "results": [
    {
      "id": "prod_8f3…",
      "title": "Basmati Rice",
      "brand": "Royal",
      "price": { "currency": "USD", "amount": 999 },
      "inventory": { "available": true, "quantity": 100 },
      "seller": { "id": "store_1a…", "name": "Test Bazaar" },
      "attributes": { "category": "Rice", "size": "5 lb", "tags": ["rice"] }
    }
  ]
}

3 Build a cart & check out

Two ways to finish. Pick by who pays:

ACP — fully agentic (the agent supplies a delegated payment and completes the order):

# 1) create a session
POST https://bazaaron.ai/acp/v1/checkout_sessions
Authorization: Bearer bzk_your_key_here
Content-Type: application/json
Idempotency-Key: 7b1f…   # safe retries

{
  "items": [{ "product_id": "prod_8f3…", "quantity": 2 }],
  "buyer": { "name": "Ada", "email": "[email protected]" },
  "fulfillment_option_id": "pickup"
}
# → { "id": "acp_checkout_…", "status": "ready_for_payment", "totals": [...] }

# 2) complete it (charges the delegated payment, places the order)
POST https://bazaaron.ai/acp/v1/checkout_sessions/acp_checkout_…/complete
Authorization: Bearer bzk_your_key_here
Content-Type: application/json

{ "payment_data": { "token": "pm_card_visa" } }
# → { "status": "completed", "order": { "id": "order_…", "permalink_url": "…" } }

In test mode (no Stripe key configured) payment_data is optional and payments return mock_authorized, so you can complete an order end-to-end without a real card.

UCP — hand off to a human (build the cart, then a person pays in the browser):

POST https://bazaaron.ai/ucp/v1/carts
Authorization: Bearer bzk_your_key_here
Content-Type: application/json

{ "items": [{ "product_id": "prod_8f3…", "quantity": 2 }] }
# → { "cart": { "id": "cart_…", "subtotalCents": 1998, … } }

POST https://bazaaron.ai/ucp/v1/checkout-sessions
Authorization: Bearer bzk_your_key_here
Content-Type: application/json

{ "cart_id": "cart_…" }
# → { "checkout_session": { "checkout_url": "https://bazaaron.ai/shop?cart=cart_…#checkout" } }
# hand checkout_url to your user to pay

Try it live no key needed

These call the real, open discovery endpoints on this site. Type a product and search:

Behind the scenes this is POST /ucp/v1/catalog/search and GET /acp/v1/products — the same calls your agent makes.

UCP vs ACP — which do I use?

UCP

Cart + human handoff

Your agent assembles a cart and gets a checkout_url. A human finishes payment in the browser. Best when a person is in the loop and you don't hold payment credentials.

ACP

Fully agentic checkout

Your agent supplies a delegated payment token and calls /complete — the order is placed without a browser. Best for autonomous, end-to-end purchasing.

Both share the same catalog and product ids. You can start with discovery (open), then choose a checkout path per use case.

Authentication

Discovery is open. Cart and checkout require one of:

1 · Agent API key (most agents)

Send your key as a bearer token (or the X-API-Key header):

Authorization: Bearer bzk_your_key_here
# or
X-API-Key: bzk_your_key_here

Shoppers self-issue keys at /shop → account → Your shopping agent. A shopper's key shops "for them": the order links to their account and buyer details prefill from their saved profile.
Store operators issue keys from the admin for partner agents.
Keys are shown once and stored only as a hash. Revoke anytime — access stops immediately. Carts/sessions are private to the key that created them (cross-key access is 403; buyer PII is redacted from non-owners).

2 · Partner signature (server-to-server)

For platform partners, ACP write requests can be signed instead. When the merchant sets ACP_SIGNING_SECRET, send an HMAC-SHA256 of {timestamp}.{rawBody} with a fresh timestamp (5-minute window):

Timestamp: 1718830000
Signature: <hex hmac-sha256( "{timestamp}.{rawBody}", ACP_SIGNING_SECRET )>

The machine-readable auth descriptor lives in the UCP profile under ucp.auth.

Endpoint reference

Discovery open

GET/.well-known/ucpCapabilities + auth descriptor

POST/ucp/v1/catalog/searchSearch products by text

POST/ucp/v1/recipe-matchMap recipe ingredients → products

GET/ucp/v1/orders/:idPublic order status

GET/acp/feed.jsonlProduct feed (JSONL; .gz variant)

GET/acp/v1/productsProduct list (JSON)

GET/schemas/recipe-ingredient-match.jsonJSON Schema for recipe match

UCP — cart & checkout key

POST/ucp/v1/cartsCreate a cart from line items

GET/ucp/v1/carts/:idRead a cart (owner only)

PATCH/ucp/v1/carts/:idUpdate items / fulfillment

DELETE/ucp/v1/carts/:idCancel a cart

POST/ucp/v1/checkout-sessionsGet a checkout_url for handoff

ACP — agentic checkout key

POST/acp/v1/checkout_sessionsCreate a session (supports Idempotency-Key)

GET/acp/v1/checkout_sessions/:idRead a session

PATCH/acp/v1/checkout_sessions/:idUpdate items / buyer / fulfillment

POST/acp/v1/checkout_sessions/:id/completeCharge + place the order

POST/acp/v1/checkout_sessions/:id/cancelCancel a session

Full request/response field shapes are in the live spec and the JSON schemas.

Conventions & gotchas

Line items are flexible. Send items (with product_id or id + quantity) or a bare product_ids array — duplicates are summed server-side.
Money is integer cents. amount/subtotalCents/total are whole cents (USD).
Weight-sold items. Products have a unit of each, lb, or kg; weight items accept fractional quantity snapped to a step.
Idempotency. Send an Idempotency-Key header on ACP session creation to make retries safe.
Rate limits. ~240 reads and ~40 writes per minute per IP. Over the limit returns 429 with a Retry-After header.
Privacy. Buyer email/phone on a session are visible only to the owning key; others see them redacted.
CORS. Allowed request headers: Content-Type, Authorization, X-API-Key, Signature, Timestamp, Idempotency-Key, Request-Id, API-Version.
Errors. JSON body with an error/code + message; status codes you'll see: 400 bad request · 401 missing/invalid key · 402 payment declined · 403 not your cart/session · 404 not found · 409 inventory conflict · 429 rate limited.

Next steps

UCP discovery profile — capabilities, endpoints, and the auth descriptor.
ACP product feed — the full catalog as JSONL.
Recipe-match schema & docs.
Send your AI assistant to shop — create a key in your shopper account.

Build an agent that shops.