API and developers

Create an order

post/v1/orders

Record a sale made outside a WhatsApp conversation (in a store, by phone, on Instagram or elsewhere) for the authenticated merchant.

Example

curl -X POST "https://api.ya.onl/v1/orders" \
  -H "X-API-Key: yv_live_v1_…" \
  -H "Content-Type: application/json" \
  -d '{"sales_channel":"…","customer":"…","currency":"…","total_amount":"…","pending_amount":"…","payment_method":"…","items":"…"}'

Parameters

Idempotency-Keystringheaderrequired

Unique key for this sale. A retry carrying the same key returns the order already created instead of a second one, whatever its body, so never reuse a key for another sale.

Request body

sales_channel"store" | "phone" | "instagram" | "other"required

Where the sale was made. store and phone sales may omit address; instagram and other need one.

contact_idstring | null

Contact the sale belongs to. When omitted, customer.phone_number finds or creates it.

customerOrderCreateCustomerrequired

Customer information

currencySupportedCurrencyrequired

Currency code (ISO 4217)

total_amountnumber | stringrequired

Total order amount including delivery fee

pending_amountnumber | stringrequired

Amount still pending payment

delivery_feenumber | string | null

Delivery fee charged to the customer

payment_termsPaymentTerms | null

Payment terms for the order (pending when omitted)

payment_methodstringrequired

Payment method used

itemsOrderCreateItem[]required

Line items in the order

addressOrderAddress | null

Delivery address

Responses

201
Successful Response
401
Invalid or missing API key
403
API key lacks the orders:write scope
409
The customer's phone matches several contacts (contact_ambiguous, with candidates), or another conflict the order cannot be recorded through
422
Invalid request or order: a missing Idempotency-Key, a malformed body, or an order the store refuses (invalid_order)
429
Rate limit exceeded
502
An internal service failed or timed out; retry with the same Idempotency-Key
Need help?