Order API Reference

Summary

This page lists the statuses, endpoints, parameters, and error codes of the order module. For the full end-to-end workflow, see the Guide to placing & paying for Taobao/1688 orders. How to receive order updates over webhooks has its own reference page.

Scope: Multiple markets are supported. Payment is unified in VND, USD, or RMB (CNY) — the purchasing wallet is topped up in one of these three currencies; balances and order amounts in the API are normalized to a common unit (*_cny).

Elim is a technology platform that handles order fulfilment and payment — it does not sell retail and does not take end customers directly. Your system pays Elim through the purchasing wallet, and Elim in turn pays the seller on the platform. Because of this, every order carries two independent statuses — the platform status (status) and the payment status with Elim (payment_status) — plus one indicator of the platform-side payment result (platform_payment_status).

Every endpoint requires JWT authentication (Authorization: Bearer <token>) or an API Key (x-api-key). See Authenticating API requests.

Platform status (status)

The order’s processing progress on Taobao / 1688.

creating → pending_payment → paid → shipped → completed
                                            ↘ cancelled

Elim payment status (payment_status)

The payment progress between the user and Elim. Independent of status.

unpaid → requested → approved → paid → refunded
   ↑         ↓
   └──── rejected

From requested, the user can withdraw their own request to go back to unpaid (see cancel-payment-request). After approved, the only way back is a refund.

Platform payment result (platform_payment_status)

Only has a value after Elim has attempted payment with the platform.

Always show both status and payment_status in your interface. platform_payment_status is mainly for diagnostics when something goes wrong.

Order endpoints

Prefix /v1/orders. Rate limits are per second window.

Preview and create order — body

{
  "platform": "alibaba",
  "receiver_address": {
    "name": "Nguyen Van A",
    "phone": "02812345678",
    "mobile": "13800138000",
    "address": "广州市天河区体育西路123号",
    "province": "广东省",
    "city": "广州市",
    "area": "天河区",
    "town": "天河南街道"
  },
  "line_items": [
    { "product_ref": "734467086498", "sku_ref": "5578084256927", "quantity": 2, "price": 15.5 }
  ],
  "preview_token": "c5f75ec1-9f8d-4bf6-9de2-048d50fef349",
  "idempotency_key": "checkout-2026-08-25-001",
  "remark": "Note for the seller",
  "promotion_id": "PROMO123"
}

line_items[]

Each element identifies an item by the product_ref + sku_ref pair, taken directly from product search / detail.

The mp_id + mp_skuid (marketplace ID) pair is still accepted for backward compatibility.

receiver_address

Preview response

{
  "success": true,
  "preview_token": "c5f75ec1-9f8d-4bf6-9de2-048d50fef349",
  "currency": "CNY",
  "total_product_amount": 31.0,
  "total_post_fee": 8.0,
  "total_amount": 39.0,
  "shops": [
    {
      "seller_id": "b2b-2201234567",
      "seller_name": "广州某某贸易有限公司",
      "post_fee": 8.0,
      "shop_amount": 31.0,
      "items": [
        { "product_id": "734467086498", "sku_id": "5578084256927", "quantity": 2, "unit_price": 15.5, "total_price": 31.0 }
      ]
    }
  ],
  "unavailable_items": []
}

Create order response

{
  "status": "pending_payment",
  "data": {
    "id": "ORD0000000123",
    "order_list": [
      {
        "success": true,
        "amount": 39.0,
        "post_fee": 8.0,
        "lines": [
          { "sub_id": "E2101234567890", "product_id": "734467086498", "sku_id": "5578084256927", "quantity": 2, "amount": 31.0 }
        ]
      }
    ]
  }
}

A new order is always at payment_status = unpaid.

List orders — filter parameters

GET /v1/orders

Response: { total, page, size, items: OrderListItem[] }.

{
  "total": 1, "page": 1, "size": 20,
  "items": [
    {
      "id": "ORD0000000123",
      "platform": "alibaba",
      "status": "paid",
      "payment_status": "paid",
      "total_amount_cny": 39.0,
      "total_amount": 39.0,
      "products": [
        { "id": "734467086498", "name": "某某商品", "price": 15.5, "quantity": 2, "img_urls": ["https://..."] }
      ],
      "created_at": "2026-04-09T10:30:00.000Z"
    }
  ]
}

line_items / products in the list are a snapshot from order creation. For the latest data, call GET /v1/orders/:id.

Order detail — differences by platform

GET /v1/orders/:id — auto-syncs the status from the platform before responding.

The platform field is present in the list response — store it to pick the display path before calling detail.

package_id is an integer taken from the Taobao order detail response, not an ORD... ID.

Cancel order — conditions

POST /v1/orders/:id/cancel — only when status is creating or pending_payment.

If the order has no platform order code yet: { "success": true, "message": "Internal order cancelled, no external order to cancel" }.

Purchasing wallet endpoints

Prefix /v1/purchasing.

GET /v1/purchasing/wallet

{
  "balance": 1670.30,
  "frozen_balance": 286.50,
  "available_balance": 1383.80,
  "total_deposited": 5000.00,
  "total_spent": 3329.70,
  "updated_at": "2026-06-19T00:00:00.000Z"
}

GET /v1/purchasing/wallet/transactions

Parameters: page, size, type, date_from, date_to. Response: { total, page, size, items }.

GET /v1/purchasing/exchange-rates

An array of active exchange rates per currency pair (VND→CNY, USD→CNY): source_currency, target_currency, rate (market rate), markup_percent, effective_rate (the rate Elim applies after markup).

Order payment endpoints

Prefix /v1/purchasing/orders/:id. :id takes the ORD... form.

POST …/request-payment

{
  "success": true,
  "order_id": "ORD0000000123",
  "frozen_amount": 286.50,
  "goods_amount_cny": 281.50,
  "shipping_fee_cny": 0,
  "service_fee_cny": 5.00
}

Insufficient wallet error — 400:

{
  "error": "insufficient_balance",
  "current_balance": 120.00,
  "available_balance": 90.00,
  "required": 286.50,
  "deficit": 196.50
}

POST …/confirm

{
  "order_id": "ORD0000000123",
  "goods_amount_cny": 281.50,
  "shipping_fee_cny": 0,
  "service_fee_cny": 5.00,
  "total_amount_cny": 286.50,
  "payment_status": "paid",
  "wallet_balance_after": 1383.80
}

Use wallet_balance_after to update the displayed balance without calling GET /v1/purchasing/wallet again.

State transitions performed by Elim

Users do not call these operations. They are listed to explain how payment_status will change and when you receive payment.updated.

Receiving order updates over webhooks

Register a webhook so Elim calls into your system whenever an order’s status or payment_status changes — instead of polling for status. Two events relate to the order module:

The payload carries an order snapshot: data.order.id, status, payment_status, platform_payment_status, total_amount_cny, updated_at. Return HTTP 2xx once processed.

The registration endpoint, the full payload structure, headers, HMAC signature verification, and the retry policy: see the Webhook reference.

Error codes

Error responses follow the shape { statusCode, message, error }. message is sometimes in Vietnamese and can be shown directly.

ID conventions

• Internal order ID: ORD + 10 digits, e.g. ORD0000000123. Used for every endpoint.
• Platform order code (order_id): issued by Taobao/1688, only present after the order is created successfully.
• package_id: an integer, used for Taobao shipping tracking.

Related links

• Guide to placing & paying for Taobao/1688 orders — step-by-step workflow
• Webhook reference — receive order.updated / payment.updated updates
• Authenticating API requests
• Full API reference