Orders

Base path: /api/v1/merchant/orders

Identifiers

Field	Meaning
id	Chuchu order UUID. Use this for get and cancel.
orderNumber	Human-readable Chuchu number, e.g. ORD-2026-001234.
externalOrderId	Your system's order id. Unique per API key / integration client.

You do not need Chuchu customer UUIDs. Send customer.phone and optionally customer.externalCustomerId.

Create

POST /api/v1/merchant/orders

Requires orders:write and Idempotency-Key.

v1 always submits a real order ready for fulfillment (the same result as creating and confirming in Chuchu). A delivery is created when Chuchu's normal confirmed-order flow creates one. delivery may be null only if the platform does not create one immediately.

collectionMode and collectionAmount are courier collection, independent of total.

Mode	Amount	Meaning
NONE	0 or omitted	Prepaid / no courier collection. A positive amount is rejected (MERCHANT_API_INVALID_ORDER).
COLLECT	exact positive amount	Driver collects this amount. 0 or omitted is rejected.

Monetary values are decimal strings, e.g. "55000" or "55000.00". v1 currency is MNT.

requestedDeliveryDate is a calendar date (YYYY-MM-DD). Chuchu stores it as that UTC date and returns the same YYYY-MM-DD. It is not shifted into another timezone.

Store pickup is not a Chuchu delivery. Do not POST a pickup order here and do not invent a fake address.

SKUs

When items[].sku is set, Chuchu maps it to that merchant's catalog product. Unknown or inactive SKUs return 422 with PRODUCT_SKU_NOT_FOUND or PRODUCT_SKU_INACTIVE. Chuchu does not create products from unknown SKUs.

Omit sku only for an ad-hoc non-stock line.

Customers

1. If externalCustomerId was already used by this API client, that customer is reused.
2. Otherwise a single merchant-scoped match on normalized phone is used.
3. If none exists, a customer is created.
4. Ambiguous phone matches return 422 CUSTOMER_PHONE_AMBIGUOUS. Customers are never shared across merchants.

Read

• GET /api/v1/merchant/orders/:orderId — one order, this merchant only.
• GET /api/v1/merchant/orders — filters: externalOrderId, orderNumber, status, customerPhone, createdFrom, createdTo, page, pageSize.

Cancel

POST /api/v1/merchant/orders/:orderId/cancel

{ "reason": "Cancelled in merchant ERP" }

Uses the same cancellation rules as Chuchu. Terminal or illegal states return an error. Linked deliveries follow Chuchu's normal cancel behavior.

curl https://api.chuchu.mn/api/v1/merchant/orders \
  -H "Authorization: Bearer $CHUCHU_API_KEY"

curl https://api.chuchu.mn/api/v1/merchant/orders/ORDER_UUID \
  -H "Authorization: Bearer $CHUCHU_API_KEY"

curl -X POST https://api.chuchu.mn/api/v1/merchant/orders/ORDER_UUID/cancel \
  -H "Authorization: Bearer $CHUCHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Cancelled in merchant ERP"}'