Chuchu Merchant API

The Merchant API lets a merchant-owned system — ERP, e-commerce, POS, CRM, or internal software — create and inspect Chuchu orders without a human logging into Chuchu.

This is version 1. The HTTP surface is /api/v1/merchant/.... Public request and response shapes are a compatibility boundary. Internal Chuchu screens and database fields can change without changing this contract.

Quickstart

1. In Chuchu, open Settings → Developer / API.
2. Create an API key and copy the secret immediately. It is shown only once.
3. Store the secret as CHUCHU_API_KEY. Never commit it.
4. Create an order, then read it back. Retries must send the same Idempotency-Key.

curl -X POST https://api.chuchu.mn/api/v1/merchant/orders \
  -H "Authorization: Bearer $CHUCHU_API_KEY" \
  -H "Idempotency-Key: SHOP-10492" \
  -H "Content-Type: application/json" \
  -d '{
    "externalOrderId": "SHOP-10492",
    "customer": {
      "externalCustomerId": "CUS-991",
      "name": "Bat",
      "phone": "99112233",
      "email": null,
      "address": {
        "label": "Delivery",
        "contactName": "Bat",
        "contactPhone": "99112233",
        "district": "Bayanzurkh",
        "khoroo": "26",
        "addressLine": "Full human-readable address",
        "latitude": "47.918",
        "longitude": "106.944",
        "deliveryInstructions": "Call before arriving"
      }
    },
    "requestedDeliveryDate": "2026-09-07",
    "collectionMode": "COLLECT",
    "collectionAmount": "55000",
    "currency": "MNT",
    "notes": "External order",
    "items": [
      {
        "externalItemId": "LINE-1",
        "sku": "PAPER-A4",
        "name": "A4 Paper",
        "quantity": "2",
        "unit": "box",
        "unitPrice": "27500",
        "discount": "0"
      }
    ]
  }'

Interactive OpenAPI: https://api.chuchu.mn/docs/merchant

Guides

• Authentication
• Orders
• Products
• Idempotency
• Errors
• Rate limits

Versioning

Breaking changes to public DTOs, paths, or auth require a new version (/api/v2/merchant/...). Additive optional fields on responses are not breaking.

Do not send X-Merchant-Id. The API key selects the merchant.