Orders

/api/v1/orders — PUT

PUT/api/v1/orders

Upsert by external_id. A payload whose modified_at is older than the stored version is not written (unchanged), so out-of-order requests never overwrite newer data. Statuses are stored as raw slugs (a wc- prefix is removed); slugs missing from your status definitions come back in unmapped_statuses. Phone and email are kept so the assistant can verify callers; the phone is stored encrypted.

• Authentication: Authorization: Bearer rz_live_…
• Scope: ingest:orders
• Plan feature: none (available on every plan)
• Idempotency-Key: optional (recommended for retries)

Request body (application/json)

Fields marked * are required. Unknown fields are rejected with 422.

OrderBatch

Field	Type	Limits	Meaning
items *	ApiOrder[]	min items 1, max items 1000	1–1000 records.

ApiOrder

Field	Type	Limits	Meaning
external_id *	string	min 1, max 200	Order id on your site.
number	string | null	max 2000	Order number the customer says; defaults to external_id.
code	string | null	max 2000	Alternative order code.
status *	string	min 1, max 100	Raw status slug (e.g. processing).
customer_name	string | null	max 2000	Customer name.
email	string | null	max 2000	Email (for verification).
phone	string | null	max 2000	Phone (to recognise callers; stored encrypted).
customer_id	string | null	max 2000	Customer id.
payment_method	string | null	max 2000	Payment method.
payment_method_id	string | null	max 2000	Payment method id.
shipping_method	string | null	max 2000	Shipping method.
shipping_method_id	string | null	max 2000	Shipping method id.
shipping_city	string | null	max 2000	Shipping city/district.
items	ApiOrderItem[]	max items 500, default []	Line items.
total	number | string	^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$, default "0"	Total.
currency	string	min 3, max 3, default "TRY"	Currency.
carrier	string | null	max 2000	Carrier.
tracking_number	string | null	max 2000	Tracking number.
tracking_status	string | null	max 2000	Carrier status code.
tracking_url	string | null	max 2000	Tracking URL.
shipment_code	string | null	max 2000	Shipment code.
channel	string	min 1, max 50, default "site"	site / trendyol / hepsiburada.
flags	object	default {}	Order flags (e.g. kurumsal, taksit, tax_free).
coupons	string[]	max items 20, default []	Coupon codes used (marks the coupon as used).
sepet_id	string | null	min 1, max 200	dis_id of the cart that became this order.
created_at *	string (date-time)		Created at (ISO 8601; Turkey time if no offset).
modified_at	string (date-time) | null		Last change; defaults to now.
completed_at	string (date-time) | null		Completed at.

ApiOrderItem

Field	Type	Limits	Meaning
name *	string	min 1, max 500	Item name.
qty	integer	≥ 0, default 1	Quantity.
total	number | string	^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$, default "0"	Line total.
ref	string | null	max 2000	Product item_ref.

Example

curl -s -X PUT "$RZ_API/api/v1/orders" \
  -H "Authorization: Bearer $RZ_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: siparis-98765-v3" \
  -d '{"items": [{"external_id": "98765", "number": "98765", "status": "processing",
        "customer_name": "Ayşe Yılmaz", "phone": "05321234567", "email": "[email protected]",
        "items": [{"name": "Kablosuz Kulaklık X2", "qty": 1, "total": "1899.90", "ref": "1234"}],
        "total": "1899.90", "currency": "TRY", "carrier": "Örnek Kargo", "tracking_number": "123456789012",
        "created_at": "2026-09-24T10:15:00+03:00", "modified_at": "2026-09-24T12:00:00+03:00"}]}'

Response 200

Schema: OrderResult

Field	Type	Limits	Meaning
inserted *	integer
updated *	integer
unchanged *	integer
unmapped_statuses *	string[]

{
  "inserted": 1,
  "updated": 0,
  "unchanged": 0,
  "unmapped_statuses": []
}

Error statuses: 401, 403, 404, 413, 422, 429 — see Errors and limits.