# Intents

An **intent** is a request, in natural language, for something to be bought or
booked. OpenIntents turns it into a completed transaction or a clear failure.

## Writing a good intent

Be as specific as a person would need to be. The agent asks as little as it
can mid-run, so include what matters:

- **What:** _"large oat flat white"_, _"UberX, not Comfort"_
- **Where or from whom:** a merchant, a location, or _"cheapest option"_
- **When:** _"pickup 8:45"_, _"leaving at 7am"_, _"arrive by Friday"_
- **Constraints:** _"aisle seat"_, _"under $400"_, _"refundable only"_

Anything structured (addresses, names, loyalty numbers) is better passed in
`context` than in the sentence.

## The intent object

```json
{
  "id": "int_7f3a2c",
  "object": "intent",
  "status": "running",
  "intent": "one-way flight JFK to Lisbon on the 14th, aisle seat, under $400",
  "max_amount": 40000,
  "currency": "usd",
  "context": { "traveler": { "name": "Ada Lovelace", "dob": "1990-12-10" } },
  "metadata": { "trip_id": "tr_881" },
  "result": null,
  "error": null,
  "test": false,
  "created_at": "2026-10-01T08:30:00Z",
  "completed_at": null
}
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Unique ID, prefixed `int_`. |
| `status` | string | One of the statuses below. |
| `intent` | string | The natural-language request, as sent. |
| `max_amount` | integer | Spending cap in cents, including tax and delivery. Optional. |
| `context` | object | Structured details the agent may use (addresses, names, preferences). |
| `metadata` | object | Your own key/value pairs, returned untouched. |
| `payment` | object | Set when `requires_payment`: the `payment_url` to send the payer, the `total`, the `fee` and the `reason` it waits. See [when a purchase waits](#when-a-purchase-waits). |
| `input_request` | object | Set when `requires_input`: what the agent needs from your customer to sign them in to the shop, such as the code it sent. See [signing in by message](#signing-in-by-message). |
| `sign_in` | object | Set when `requires_login`: the `url` to send your customer, the `shop` and `expires_at`. |
| `result` | object | Set when `completed`: merchant, items, total, fee, confirmation, receipt URL. A ride also says `kind: "ride"` and `state: "requested"`. See [paying at the shop](#paying-at-the-shop). |
| `error` | object | Set when `failed`: `code` and a human-readable `message`. Also set on a `cancelled` intent whose order the shop may already have (`may_be_placed`). |
| `progress` | object | The latest milestone its runs reached, once one is: `stage`, `at`, and what was known by then. See [following a purchase](#following-a-purchase). |
| `review_before_order` | boolean | Whether your customer checks the order before it is placed: `true` by default with a live key, `false` with a test key. See [checking the order first](#checking-the-order-first). |
| `affiliate` | object | Set when a live purchase is at a store whose affiliate program may pay OpenIntents a commission on it: the `program`, the store's `name` and the `network`. The price is the store's own either way. See [affiliate commissions](#affiliate-commissions). |
| `test` | boolean | `true` for intents created with a test key. |

## Lifecycle

```text
queued ──► running ──► (paid from the wallet) ───────► completed
              │                                           ▲
              ├──► requires_payment ──► (step done) ──► queued, then on as above
              │           │
              │           └──► cancelled (link expired or cancelled)
              ├──► requires_input ──► (answered) ──► running, then on as above
              │           │
              │           └──► (no answer, or a password) ──► requires_login
              ├──► requires_login ──► (signed in) ──► queued, then on as above
              │           │
              │           └──► failed (login_required: declined or expired)
              └──► failed
```

| Status | Meaning |
| --- | --- |
| `queued` | Accepted, waiting for a browser. Usually under a second. |
| `running` | The API is doing the agentic work in a real browser. |
| `requires_payment` | At checkout, and the payer has a step to take in their [wallet](/docs/wallets) first (connect it, add money, raise a limit, confirm who they are), or you asked for their approval. `payment.payment_url` is set; once the step is done the intent goes back to `queued` and carries on. |
| `requires_input` | The agent is signing your customer in to the shop and needs something only they know: their phone number or email, or the code the shop just sent. `input_request` says what; [answer it](#signing-in-by-message) and the intent carries on. |
| `requires_login` | The shop wants your customer signed in. `sign_in.url` is set: send it to them; once they sign in, the intent carries on by itself. See [sign-in links](#sign-in-links). |
| `completed` | Paid from the payer's wallet and confirmed. `result` is set. |
| `failed` | Could not be completed (out of stock, over `max_amount`, the wallet declined, merchant error). Free. |
| `cancelled` | Cancelled by you before payment. Free. Cancelled after the order was placed at the shop, the purchase stops but the shop may have the order: `error.code` is `may_be_placed`, so check it with the shop. |

`completed`, `failed` and `cancelled` are final. Every transition emits a
[webhook](/docs/webhooks) event, and every step lands on the intent's
[timeline](/docs/events), which you can follow live.

## Following a purchase

While an intent is `running`, `progress` says how far it got, so you can tell
your customer without reading the whole timeline:

```json
"progress": {
  "stage": "paying",
  "at": "2026-10-27T10:04:12Z",
  "shop": "blinkit.com",
  "merchant": "Blinkit",
  "items": [{ "name": "Maggi 2-Minute Noodles", "quantity": 2, "amount": 9600 }],
  "total": 9600,
  "currency": "inr",
  "paid_with": "cash_on_delivery"
}
```

| `stage` | Reached when |
| --- | --- |
| `shop_opened` | The browser is on the shop's site, not a search engine. `shop` is set. |
| `signed_in` | The agent signed your customer in to the shop, with the code or the approval they gave. |
| `checkout` | The cart is at the payment step: `merchant`, `items`, `total` and `currency` are set. |
| `paying` | [Paying at the shop](#paying-at-the-shop) only: the way to pay is chosen, and `paid_with` is `cash_on_delivery` or `upi_qr`. |
| `placing` | The button that places the order is being pressed. Whether the order went through is for the final status to say. |

Each part is `null` until it is known, and a later stage keeps what earlier
ones knew. A run reaches each stage at most once, usually in this order, and
may skip some (no sign-in, or a wallet payment, which has no `paying`). A
run that continues after your customer answered, signed in or paid may reach
a stage again. Milestones never change the `status`, are written by
OpenIntents from what the run did (no model writes them), and each is also a
`progress` event on the [timeline](/docs/events) and, for endpoints that ask
for it by name, an [`intent.progress`](/docs/webhooks#events) webhook.

## When a purchase waits

Live purchases are paid from the payer's own [wallet](/docs/wallets) at
Perflo. The payer meets their wallet only when a purchase needs it, so the
first live purchase usually waits once:

```json
{
  "id": "int_7f3a2c",
  "status": "requires_payment",
  "payment": {
    "reason": "connect_wallet",
    "payment_url": "https://openintents.io/api/pay/pay_7f3a2c",
    "merchant": "Blue Bottle Coffee",
    "total": 550,
    "fee": 0,
    "currency": "usd",
    "expires_at": "2026-10-01T09:00:00Z"
  }
}
```

Send `payment_url` to the payer. It opens one page that runs only the steps
left for this purchase, and skips the ones already done. `reason` says why it
waits:

| `reason` | Meaning |
| --- | --- |
| `connect_wallet` | The payer connects their wallet, or signs in to it again. |
| `add_money` | The wallet is short of `total`; the payer adds money to it. |
| `identity_check` | The wallet needs the payer to confirm who they are first. |
| `wallet_processing` | The wallet is still taking the money (from a card the payer saved, say); the link shows how it is going. |
| `over_limit` | The purchase is over a spending limit; on a wallet, the payer raises the limit they set. |
| `requested` | You asked for the payer to see a link first (`require_payment_link`). |

Others may appear: send the link whatever the reason. Once the step is done,
the intent goes back to `queued` by itself, with the same cart, and on to
`completed`. Later purchases go straight through while the wallet's money,
limits and identity check hold. The link expires after 30 minutes, and an
intent whose link expired is cancelled, free. Test keys never pay, so test
intents never wait here.

## Signing in by message

Some shops won't sell without an account. Many sign people in with a phone
number or an email and a one-time code. There, the agent signs your customer
in itself, and asks you for each thing only they know. The intent waits in
`requires_input`:

```json
{
  "id": "int_7f3a2c",
  "status": "requires_input",
  "input_request": {
    "id": "inp_8f2c41d0a9e7b3f15c62d1aa",
    "kind": "code",
    "shop": "blinkit.com",
    "prompt": "Enter the 4-digit code blinkit.com just sent to your phone.",
    "channel": "sms",
    "length": 4,
    "url": "https://openintents.io/input/inp_8f2c41d0a9e7b3f15c62d1aa",
    "expires_at": "2026-10-14T10:05:00Z",
    "attempts_left": 2
  }
}
```

1. **Ask your customer** exactly `input_request.prompt`, the way you reach
   them: in a chat, say. `kind` is `phone`, `email`, `code` or `approval`
   (approve the sign-in on their phone; nothing to type).
2. **Send their answer** within 5 minutes:

   ```bash
   curl https://api.openintents.io/v1/intents/int_7f3a2c/input \
     -H "Authorization: Bearer $OPENINTENTS_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "input": "inp_8f2c41d0a9e7b3f15c62d1aa", "value": "4829" }'
   ```

   Send `"decline": true` if they'd rather not, or `"done": true` once they
   approved an `approval`.
3. **The intent carries on.** It is `running` again at once. The agent types
   the answer into the shop's page for you, and may ask once more (the code,
   after the phone number). Their next intents at that shop find them signed
   in already.

The answer is typed only into the shop's own page, and only where it was
asked. It is sealed while it waits, never shown back, and deleted once
typed: the agent's model never sees it. A password is never asked for this
way, nor anything of a payment. Prefer that the code not pass through your
chat? Send your customer `input_request.url` instead: they type it on our
page, where their phone can fill in the code from the message.

Know your customer's phone number or email already? Pass it as
`sign_in_hint` when you create the intent (`{ "phone": "+919812345678" }`),
and the agent won't ask for it. It is kept sealed, used once, and deleted
when the intent ends.

When the shop asks for a password, shows a captcha, or your customer doesn't
answer in time, the intent moves on to a [sign-in link](#sign-in-links)
instead (if you allow links), where your customer signs in themselves. To
never be asked, create the intent with `"sign_in_agent": false`.

### When something is missing

The same status covers anything else the purchase needs that your request
didn't give: the email the shop wants for the order, a size, a colour. The
agent asks instead of failing, with `kind` `detail`: `prompt` is then its own
question, and `options` lists the choices when the page offers them (answer
with one of them). Answer as above, with `value`. An intent asks at most 6
such questions, and never for a password, a code, a PIN, card or bank
details, or an ID number. If your customer declines or doesn't answer, the
intent fails with `needs_information`.

On a live intent (or a test one with `review_before_order: true`) your
customer may also be asked to choose, as a `detail` request with `choices`,
answered with the id they pick:

- which product, when more than one of the shop's results fits the request
  (each with its name, size and price). If they decline every one, nothing
  is ordered and the intent fails with `needs_information`;
- which saved address, when the shop lists more than one (the one that
  matches the request first);
- what becomes of a line in the shop's cart the request didn't ask for and
  that can't be taken out: `removed` (they took it out in the shop's own
  app), `keep` (it is ordered with the rest) or `cancel` (nothing is
  ordered, and the intent fails with `order_declined`).

A test intent without a review never waits on these: the best fit and the
saved address that matches the request are taken, and a line that can't be
taken out stays in the cart. The same goes for an intent that has used up
its questions, except that on a live intent with no review a line that
can't be taken out ends the intent with `not_possible`.

## Paying at the shop

With `pay_at_shop: true` your customer pays the shop themselves, in their own
UPI app, instead of the purchase being paid from their wallet. At the payment
step the agent brings up the shop's UPI QR code and the intent waits in
`requires_input` with a `payment` request:

```json
{
  "id": "int_7f3a2c",
  "status": "requires_input",
  "input_request": {
    "id": "inp_3b9d02e6c1f84a7d5e20b9cc",
    "kind": "payment",
    "shop": "swiggy.com",
    "prompt": "Scan the QR code with your UPI app to pay swiggy.com 149.00 INR, then confirm here that you paid. Do not pay a different amount.",
    "url": "https://openintents.io/input/inp_3b9d02e6c1f84a7d5e20b9cc",
    "image_url": "https://openintents.io/api/input/inp_3b9d02e6c1f84a7d5e20b9cc/image",
    "expires_at": "2026-10-14T10:05:00Z",
    "attempts_left": 0
  }
}
```

Show your customer `image_url` (or send them `url`, which shows the code and
a button), and answer `done` once they paid, or `decline`. The agent then
checks the shop's confirmation and the intent completes with its receipt.
No wallet is needed, and the fee is waived for now. The code expires after 5
minutes. A payment not confirmed by then is never asked for again, since the
payer may have paid all the same: the intent completes if the shop shows the
order, and otherwise fails with `needs_review` for us to check. Live keys
only: a test key's intent stops at the payment step as always.

Where the shop takes cash on delivery, the agent chooses that instead and
places the order; your customer pays when it arrives, and the receipt's
`paid_with` is `cash_on_delivery`. The intent completes once the shop's page
shows the order went through, with the order's number as `confirmation`
where the page gives one. If the shop's total is higher by then (a cash on
delivery fee, say), the intent completes with the shop's total as long as it
is within `max_amount`.

Where the shop's page does not show which way to pay is chosen, your
customer may be asked first: a `detail` request with the `choices`
`cash_on_delivery` and `upi_qr`, answered with the id they pick. If they
decline, the intent fails with `not_possible`; with no answer within 5
minutes, with `input_expired`. Nothing is ordered in either case.

A ride (Uber, Ola, Rapido) is paid the same way: your customer pays the
driver in cash, never by a code. The intent completes once the app is
looking for a driver, and its receipt says so:

```json
{
  "merchant": "Uber",
  "items": [{ "name": "Uber Go", "quantity": 1, "amount": 18000 }],
  "total": 18000,
  "fee": 0,
  "currency": "inr",
  "confirmation": "the shop's page shows \"looking for nearby drivers\"",
  "receipt_url": null,
  "paid_with": "cash_on_delivery",
  "kind": "ride",
  "state": "requested"
}
```

`requested` means the ride was asked for, not that a driver took it: tell
your customer to follow it, and find its PIN, in the ride app. The receipt
never carries the PIN.

## Checking the order first

With `review_before_order: true` nothing is ordered until your customer has
seen the order as the shop will take it and said yes. It is on by default for
intents made with a live key: send `review_before_order: false` to place the
order without the check. Intents made with a test key skip it unless you send
`true`, so automated test runs never wait on a person. At the payment step the
intent waits in `requires_input` with a `review` request, whose `review` is
the order:

```json
{
  "id": "int_7f3a2c",
  "status": "requires_input",
  "review_before_order": true,
  "input_request": {
    "id": "inp_8c1e4f0a9d2b7e6f3a5c1d08",
    "kind": "review",
    "shop": "blinkit.com",
    "prompt": "Check your blinkit.com order before it is placed.",
    "url": "https://openintents.io/input/inp_8c1e4f0a9d2b7e6f3a5c1d08",
    "review": {
      "merchant": "Blinkit",
      "items": [{ "name": "Amul Taaza Milk 1L", "quantity": 2, "amount": 13600 }],
      "fees": [{ "label": "Delivery fee", "amount": 1500 }],
      "total": 15100,
      "currency": "inr",
      "payment_method": "cash_on_delivery",
      "deliver_to": "Home, 12 MG Road, Bengaluru 560001",
      "eta": "12 minutes"
    },
    "expires_at": "2026-10-14T10:05:00Z",
    "attempts_left": 2
  }
}
```

Show your customer the order (or send them `url`, which shows it with three
buttons), then answer with what they chose:

- `done: true` places the order as shown.
- `value`, one line of at most 300 characters, asks for a change in their
  own words (_"no coconut water"_, _"deliver to my office"_). The agent makes
  it and asks them to check the order again.
- `decline: true` orders nothing: the intent fails with `order_declined`.

Amounts are in cents, fees included in `total`. `payment_method` is
`cash_on_delivery`, `upi_qr`, `wallet` or `payment_link`. If the shop's
total changes after your customer said yes, they are asked again before
anything is placed. An intent asks at most 3 times. A review not answered
within 5 minutes fails the intent with `input_expired`, and nothing is
ordered. The completed intent's `result.deliver_to` is the address your
customer approved. A test key's intent is reviewed too, then stops at the
payment step as always. Where OpenIntents may earn a commission on the
order, `review.affiliate` says so (see [affiliate commissions](#affiliate-commissions)).

## Affiliate commissions

Some stores pay OpenIntents a commission when a purchase reaches them through
their affiliate link. The agent does not know which stores pay, so it never
picks a store for that, and the price is the store's own either way. Where a
live purchase is at such a store, the intent says so in `affiliate` as soon
as the purchase reaches the store, before anything is ordered:

```json
"affiliate": { "program": "klook", "name": "Klook", "network": "travelpayouts" }
```

The order's `review` carries the same object, and the review page shows your
customer the line _"Affiliate: OpenIntents may earn a commission from Klook
on this purchase, at no extra cost to you."_ If you show the order yourself,
show your customer that line too, before they place the order. Test intents
never carry it. To have your account's purchases never opened through an
affiliate link, write to [hello@openintents.io](mailto:hello@openintents.io).
See the [affiliate disclosure](/affiliate-disclosure) for how it works.

## Sign-in links

When the shop wants your customer signed in in a way the agent can't do by
message (a password, say), the intent doesn't fail: it waits in
`requires_login` with a link.

```json
{
  "id": "int_7f3a2c",
  "status": "requires_login",
  "sign_in": {
    "url": "https://openintents.io/signin/sgn_4fQ9…",
    "shop": "amazon.com",
    "expires_at": "2026-10-01T09:00:00Z"
  }
}
```

1. **Send the link to your customer only**, the way you reach them (a
   message, an email, your app), and don't open it yourself. It works for 30
   minutes, on the first device that opens it: any other device, yours
   included, sees only that it is in use, unless the first one leaves it
   alone for a few minutes.
2. **They open it and sign in.** They see the shop's real sign-in page, live,
   in their own browser that OpenIntents runs: the one their purchases use.
   They tap, type and drag as on any page, codes by SMS, captchas and
   sliders included. That browser never pays, places orders or enters card
   details, and stays on the shop's site.
3. **The intent carries on.** Once they're signed in it goes back to
   `queued` (reason `signed_in`) and on to `completed` as usual. Their next
   intents at that shop find them signed in already.

If they decline, or the link expires, the intent fails with `login_required`.
Nothing is charged either way. To sign customers in yourself instead, with
[browser sessions](/docs/sessions), create the intent with
`"sign_in_link": false`: it then fails with `login_required` straight away.
