---
name: order-on-bazaaron
description: Place a grocery order on BazaarOn.ai on the user's behalf via the agentic-commerce (ACP) API. Use when the user asks to buy, order, reorder, or "add to cart and check out" groceries from BazaarOn. Covers discovery → create checkout session → complete → confirm.
---

# Order on BazaarOn.ai (agentic checkout)

BazaarOn exposes an agentic-commerce API. You (an AI agent) can search the catalog,
build a checkout session, and place the order **as the user** — no browser needed.

## What you need first

- **Base URL:** `https://bazaaron.ai`
- **API key:** a `bzk_…` key the user created at **/shop → account → Your shopping agent**.
  Send it as `Authorization: Bearer bzk_YOUR_KEY` on every cart/checkout call.
  Treat it like a password; never print it back to the user or log it.

## The five rules that prevent the common failures

1. **Discovery is open; checkout is gated.** Search/feed need no key. Creating a session
   and completing it **require** `Authorization: Bearer bzk_…`. A `401` means the key is
   missing or wrong — the body includes a `hint` and a `docs` URL; follow them.
2. **There is no "add one item" endpoint.** You create **one checkout session with all
   items at once.** Do not look for `/cart/add` or `/api/v1/cart` — those don't exist.
3. **Use the product `id` from search, never the product name.** Passing a name yields a
   `400 checkout_session_failed` (the body's `hint` says exactly this).
4. **One store per order.** All items in a session must be from the same store (`seller`).
   If the user wants items from two stores, place two separate orders.
5. **Test mode = no real charge.** Omitting `payment_data` completes the order as
   `mock_authorized` (nothing is charged). See "Paying" below for real charges.

## The flow

### 1. Discover — get product IDs (no key needed)

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

{ "query": "india gate basmati rice" }
```
Response → `results[]`, each: `{ id, title, price:{ amount, currency, base_amount? }, inventory:{ quantity, available }, seller:{ id, name } }`.
- `amount` is cents. If `base_amount` is present, the item is **on sale** (`amount` is the sale price).
- Pick the `id` of the product the user meant. Repeat per requested item.

### 2. Create a checkout session (key required)

```
POST https://bazaaron.ai/acp/v1/checkout_sessions
Authorization: Bearer bzk_YOUR_KEY
Content-Type: application/json
Idempotency-Key: <random-stable-id>     # lets you safely retry without double-ordering

{
  "items": [
    { "id": "prod_60775afd8f7cef3c", "quantity": 1 },
    { "id": "prod_2b2b08d5c2b28824", "quantity": 1 }
  ],
  "fulfillment_option_id": "pickup"      # or "local_delivery"
}
```
Response → `{ id: "acp_checkout_…", status: "ready_for_payment", buyer, totals[], line_items[] }`.
- `buyer` (name/email/phone) and, for delivery, the address **auto-fill from the user's account**.
  Override only if asked: add `"buyer": { "name", "email", "phone" }` and/or
  `"fulfillment_address": { "line1", "line2", "city", "state", "zip" }`.
- `totals` has a `type:"total"` row with the amount in cents. Show the user the total and the
  line items before completing, if you want confirmation.
- Pickup needs no address; `local_delivery` uses the saved address (or the one you pass).

### 3. Complete — place the order (key required)

```
POST https://bazaaron.ai/acp/v1/checkout_sessions/acp_checkout_…/complete
Authorization: Bearer bzk_YOUR_KEY
Content-Type: application/json

{ }                                       # test mode → mock_authorized, no charge
```
Response → `{ status: "completed", order: { id: "order_…", permalink_url } }`.
This call is **idempotent** — re-completing a finished session returns the same order.

### 4. Confirm (optional)

```
GET https://bazaaron.ai/api/orders/order_…
```
Response → `{ order: { id, status, paymentStatus, fulfillmentMode, customerName, subtotalCents, items[] } }`.
`paymentStatus: "mock_authorized"` confirms a test order. The order also appears in the
user's **/shop → account → My orders** because the key links it to their account.

Report back to the user: order id, items + total, fulfillment mode, and the
`permalink_url` to track it.

## Paying for real (when not testing)

`payment_data.token` is a **Stripe PaymentMethod id** charged directly.
- **Omit it** → `mock_authorized` (no charge).
- **Stripe test mode** → pass a built-in test method: `{ "payment_data": { "token": "pm_card_visa" } }`
  (`pm_card_chargeDeclined` forces a `402` to test declines).
- **Live cards** are out of scope for a self-tokenizing agent — they need a delegated/"shared"
  wallet token. BazaarOn runs in test mode.

## Errors you may get (and what to do)

| Status | Meaning | Fix |
|---|---|---|
| `401` | Missing/invalid key | Send `Authorization: Bearer bzk_…`; see the body's `docs`/`hint` |
| `400 checkout_session_failed` | Bad item — usually a name instead of an id | Use the `id` from step 1 |
| `402 payment_declined` | Payment failed | Check `payment_data.token`; in test use `pm_card_visa` |
| `403` | Cart/session belongs to another agent | Use your own session id |
| `409` | Inventory conflict | Re-check stock via search; lower quantity |
| `429` | Rate limited | Back off and retry after `Retry-After` |

## Alternative: hand off to a human (UCP)

When you should **not** pay (no payment authority), build a cart and hand the user a URL:
```
POST /ucp/v1/carts                  (Bearer key)  → { cart: { id } }
POST /ucp/v1/checkout-sessions      (Bearer key)  body { "cart_id": "cart_…" }
   → { checkout_session: { checkout_url } }        # give checkout_url to the user to pay
```

## Quick checklist

1. Have a `bzk_` key? If not, tell the user to create one at /shop → account → Your shopping agent.
2. Search each requested item → collect `id`s (same store).
3. POST one `/acp/v1/checkout_sessions` with all items + `fulfillment_option_id` + `Idempotency-Key`.
4. POST `…/complete` (`{}` for test, or `payment_data` for a charge).
5. Confirm and report the `order.id` + `permalink_url`.

Full docs: https://bazaaron.ai/developers