Orders quick start

Base URL (staging): https://orders.staging.turnstay.com
Interactive docs: /api/v1/public/docs

Dashboard: Invoicing → Orders. Open an order and use the tabs.

Dashboard walkthrough

Create an order and add products from My catalogue or Suppliers.
Forex controls
- Single currency consolidation: one listing currency. The invoice and every payment link use it.
- Dynamically map currencies: one invoice per listing currency you map into.
- After you pick EUR / GBP / USD / ZAR, choose which TurnStay Payments account in that currency generates the payment link.
Schedule how the guest pays (pay in full, deposit + balance, instalments).
Issue the invoice.
Fulfillment is later: supplier wallet, bank, or cash retain. That is not Forex.

APIs that matter

Replace {order_id} with the order UUID. Send a Descope Bearer token.

What	Method	Path
Create order	`POST`	`/api/v1/orders`
Add / change lines	`POST` / `PATCH`	`/api/v1/orders/{order_id}/lines`
Preview FX	`GET`	`/api/v1/orders/{order_id}/fx/preview?settlement_currency=USD`
Save FX plan	`POST`	`/api/v1/orders/{order_id}/fx/consolidate`
TurnStay Payments accounts for links	`PATCH`	`/api/v1/orders/{order_id}/payment-routing`
Payment schedule	`PUT`	`/api/v1/orders/{order_id}/schedule`
Issue invoice	`POST`	`/api/v1/orders/{order_id}/documents/issue`
Mint payment link	`POST`	`/api/v1/orders/{order_id}/payment-links`

The query field is still named settlement_currency on the API. In the dashboard it is listing currency (what the guest is invoiced in).

Save a single listing currency

curl -X POST "$ORDERS/api/v1/orders/$ORDER_ID/fx/consolidate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settlement_currency": "USD",
    "fx_strategy": "fixed",
    "currency_map": null
  }'

Pin TurnStay Payments accounts for payment links

curl -X PATCH "$ORDERS/api/v1/orders/$ORDER_ID/payment-routing" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "turnstay_account_id": 101,
    "accounts_by_currency": { "USD": 101, "ZAR": 202 }
  }'

accounts_by_currency is used when you map into more than one listing currency. Mint picks the account for that payment link’s currency, then falls back to turnstay_account_id.

treasury_source_wallet_id on the same object is the merchant wallet for supplier payouts. Set it on Fulfillment, not on Forex.

Mint a link

curl -X POST "$ORDERS/api/v1/orders/$ORDER_ID/payment-links" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "schedule_item_id": "…" }'

The orders service sends account_id to TurnStay Payments from the routing you pinned.