Browse docs
previewThese docs describe OpenIntents as it is being built. Endpoints and payloads may change before launch.

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
}
FieldTypeDescription
idstringUnique ID, prefixed int_.
statusstringOne of the statuses below.
intentstringThe natural-language request, as sent.
max_amountintegerSpending cap in cents, including tax and delivery. Optional.
contextobjectStructured details the agent may use (addresses, names, preferences).
metadataobjectYour own key/value pairs, returned untouched.
paymentobjectSet when requires_payment: the payment_url to send the payer, the total, the fee and the reason it waits. See when a purchase waits.
input_requestobjectSet 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.
sign_inobjectSet when requires_login: the url to send your customer, the shop and expires_at.
resultobjectSet when completed: merchant, items, total, fee, confirmation, receipt URL. A ride also says kind: "ride" and state: "requested". See paying at the shop.
errorobjectSet when failed: code and a human-readable message. Also set on a cancelled intent whose order the shop may already have (may_be_placed).
progressobjectThe latest milestone its runs reached, once one is: stage, at, and what was known by then. See following a purchase.
review_before_orderbooleanWhether 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.
affiliateobjectSet 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.
testbooleantrue 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
StatusMeaning
queuedAccepted, waiting for a browser. Usually under a second.
runningThe API is doing the agentic work in a real browser.
requires_paymentAt checkout, and the payer has a step to take in their wallet 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_inputThe 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 and the intent carries on.
requires_loginThe 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.
completedPaid from the payer's wallet and confirmed. result is set.
failedCould not be completed (out of stock, over max_amount, the wallet declined, merchant error). Free.
cancelledCancelled 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 event, and every step lands on the intent's timeline, 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"
}
stageReached when
shop_openedThe browser is on the shop's site, not a search engine. shop is set.
signed_inThe agent signed your customer in to the shop, with the code or the approval they gave.
checkoutThe cart is at the payment step: merchant, items, total and currency are set.
payingPaying at the shop only: the way to pay is chosen, and paid_with is cash_on_delivery or upi_qr.
placingThe 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 and, for endpoints that ask for it by name, an intent.progress webhook.

When a purchase waits

Live purchases are paid from the payer's own wallet 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:

reasonMeaning
connect_walletThe payer connects their wallet, or signs in to it again.
add_moneyThe wallet is short of total; the payer adds money to it.
identity_checkThe wallet needs the payer to confirm who they are first.
wallet_processingThe wallet is still taking the money (from a card the payer saved, say); the link shows how it is going.
over_limitThe purchase is over a spending limit; on a wallet, the payer raises the limit they set.
requestedYou 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 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

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 [email protected]. See the affiliate disclosure for how it works.

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, create the intent with "sign_in_link": false: it then fails with login_required straight away.