Place Wonder orders
from your own app.

Quickstart

What a real integration looks like end to end. This runs the actual shape of the calls, so you can watch the two steps happen.

Get your key from Discord with /api. It is sent by DM and shown once.

# 1. price a cart — nothing is charged yet
curl https://yonderdrop.com/v1/checkouts \
  -H "Authorization: Bearer yd_live_..." \
  -H "Content-Type: application/json" \
  -d '{"cart_code":"ABC123","address":"742 Example Ave, Springfield, IL"}'

# → nothing charged yet. This is what comes back:
{
  "ok": true,
  "id": "chk_8f2a",          // use this to confirm or cancel
  "status": "pending",
  "restaurant": "Bella Vista Kitchen",
  "items": [
    { "name": "Chicken Burrito Bowl", "quantity": 1, "subtotal": "$20.80" }
  ],
  "price": {
    "subtotal": 20.80,      // the food
    "discount": -15.00,     // applied for you
    "service": 2.99,
    "tax": 0.78,
    "tip": 0.00,
    "credit": -0.00,       // account credit spent on this order
    "total": 9.57          // what the card is charged
  },
  "account": "buyer-04@…",   // who it orders as
  "card": "•••• 4242",
  "expires_in": 300         // seconds before the hold is released
}

# 2. confirm it — this is the one that spends a checkout
curl https://yonderdrop.com/v1/checkouts/chk_.../confirm \
  -H "Authorization: Bearer yd_live_..." \
  -H "Idempotency-Key: your-own-id"

# → {"ok":true,"order_id":"...","tracking":"https://yonderdrop.com/track/X7K2M9"}Copy

Authentication

Every request carries your key as a bearer token.

Authorization: Bearer yd_live_xxxxxxxxxxxxxxxxxxxxxxxxCopy

How an order works

Two steps, on purpose. The first one prices the cart and costs nothing. The second is the only thing in the whole API that spends money. Between them you can change anything, or walk away.

POST /v1/checkouts                → pending    priced, held 15 min, FREE
       │
       ├── PATCH  /v1/checkouts/{id}          change tip, notes, card…  still free
       ├── POST   /v1/checkouts/{id}/name     rename the account, still free
       ├── POST   /v1/checkouts/{id}/reprice  ask again, renew the hold
       │
       ├── POST   /v1/checkouts/{id}/cancel   → cancelled  nothing charged, ever
       ├── (do nothing for 5 minutes)         → expired    nothing charged, ever
       │
       └── POST   /v1/checkouts/{id}/confirm  → placed     CHARGED. order is live
                    ↓
              GET /v1/orders/{id}             → deliveredCopy

Stopping an order before it goes through

A checkout is not an order. Pricing one charges nothing, reserves nothing on your card and spends nothing from your daily plan — it only holds a lane for you for fifteen minutes. There are two ways to back out, and both cost exactly nothing:

# say so, and the lane is freed immediately for your next order
curl -X POST https://yonderdrop.com/v1/checkouts/chk_8f2a/cancel \
  -H "Authorization: Bearer yd_live_..."

# → {"ok":true,"id":"chk_8f2a","status":"cancelled"}Copy

Or do nothing at all. After fifteen minutes the hold lapses on its own, the lane goes back, and the checkout stops existing. You never have to clean up after yourself — cancelling is just faster, and gets your lane back for the next order sooner.

What "charged" actually means

Confirm does two separate things. It spends one checkout from your daily plan, and it puts a real order on a real card. If the order fails before it ever reaches the restaurant, your checkout is given straight back — you are not billed a slot for something that never happened.

If it fails after submission, the response says "outcome_known": false. That means the food may genuinely be on its way and we will not pretend otherwise, so nothing is refunded and you should check before trying again. Anything that reports "outcome_known": true provably never landed.

Every option

Only cart_code is ever required. Everything else has a sensible default, and anything you leave out falls back to your saved settings first, then to how the cart itself was built.

So a full order with a tip, driver notes and a hand-off preference is one call:

curl https://yonderdrop.com/v1/checkouts \
  -H "Authorization: Bearer yd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "cart_code": "ABC123",
    "address": "742 Example Ave, Springfield, IL",
    "address2": "Apt 4B",
    "tip": 5.00,
    "notes": "Ring the bell twice, gate code 4417",
    "dropoff": "LEAVE_AT_DOOR"
  }'Copy

Using one card for one order

Pass card and that order is paid with it — nothing goes into your pool, nothing is stored, and your pinned card is untouched. Useful when a customer's order should not come off your own card, or when you are testing.

-d '{
    "cart_code": "ABC123",
    "address": "742 Example Ave, Springfield, IL",
    "card": "4242424242424242,09/28,414,10001"
  }'Copy

Leave it out and it draws from your pool instead — the pinned card first, then whichever is at the front. If a card is refused you get CARD_DECLINED before anything is ordered; swap it with PATCH on the same checkout rather than starting over.

You do not have to carry card numbers around to retry. Send {"card": "pool"} and the next unclaimed card in your pool is drawn for you, exactly as the Discord panel's "try another card" does. An exhausted pool answers NO_CARD, and says whether it is empty or simply all on other open checkouts.

curl -X PATCH https://yonderdrop.com/v1/checkouts/chk_8f2a41c07b93 \
  -H "Authorization: Bearer yd_live_..." \
  -d '{"card": "pool"}'Copy

A fraud decline works the same way. The first FORTER_DECLINE on an account burns that card but keeps the checkout open, so a different card can be sent and confirmed again. If a second card is refused on the same account, the account itself is the problem: it is retired from the chain and the checkout closes, so build a new one on another chain.

Pickup is the same call with no address at all:

-d '{"cart_code": "ABC123", "fulfillment": "PICKUP", "tip": 2.00}'Copy

Changing it after pricing

Priced it and want something different? PATCH the checkout before you confirm. Send only what changes — the rest stays as it was, and the checkout is re-priced and returned.

curl -X PATCH https://yonderdrop.com/v1/checkouts/chk_8f2a \
  -H "Authorization: Bearer yd_live_..." \
  -H "Content-Type: application/json" \
  -d '{"tip": 8.00, "notes": "Leave with the doorman"}'

# → the whole checkout back, plus what actually changed:
#   "changed": ["tip", "notes"], "price": { ... "total": 12.57 }Copy

Endpoints

Errors

Every failure has a stable code, a sentence written for a human, and a flag telling you whether trying again could help.

{
  "ok": false,
  "code": "CHECKOUT_FAILED",
  "error": "Bella Vista Kitchen is open but does not serve this address",
  "retryable": true
}Copy

Plans & limits

A checkout is spent when an order is placed. Anything that fails, or that you cancel, costs nothing. The day resets at midnight.

Rate limits

Separate from the daily plan. The plan caps how many orders you place; these cap how fast you may call, and they are priced by what a call actually costs us. Every limit is counted per key.

Burst is how many you may fire at once before the rate starts to matter — it refills continuously, so a steady caller never notices it.

A limited request answers 429 with a Retry-After header and the same figure in retry_after, in seconds:

{
  "ok": false,
  "code": "RATE_LIMITED",
  "error": "Too many read requests. Try again in 4s.",
  "retryable": true,
  "retry_after": 4.2
}Copy

Every successful response also carries X-RateLimit-Remaining and X-RateLimit-Limit, so you can slow down before you are told to.

Tracking

Every placed order returns a link you can hand straight to your customer. It shows the driver, the ETA, every item with its photo and the drop-off photo, and never shows a price or an address you did not give it. The page updates itself until the food lands.

https://yonderdrop.com/track/X7K2M9Copy

Try it

Every endpoint, answering in the exact shape the real one answers in. The data below is invented — nobody's key, nobody's cart — but the fields, the error codes and the failure cases are the ones the server actually returns, so what you build against this works against the real thing.