Order API Guide

The Order API allows you to create and manage proxy purchasing orders on Taobao and 1688 (Alibaba). Each order maintains two independent statuses: the platform status (status) returned by Taobao/1688, and the Elim payment status (payment_status) managed by the purchasing wallet system.

All endpoints require JWT authentication via the Authorization: Bearer <token> header or API Key (X-API-KEY).

Authentication guide: Authentication

Order Statuses

Before using the API, understand the two status dimensions of an order to avoid confusion when displaying to end users.

Platform Status (status)

Reflects the processing progress of the order on Taobao or 1688.

Elim Payment Status (payment_status)

Reflects whether the order has been paid to Elim. This is independent of status — an order can be at status=shipped but still payment_status=unpaid if there is an issue.

Preview Order

View details: Preview order

Before creating a real order, call the preview endpoint to get the estimated total and check item availability. This step does not create an order or deduct funds — it only returns information for the user to confirm before checkout.

Rate limit: 20 requests / 60 seconds

POST /v1/orders/preview

Body:

{
  "platform": "alibaba",
  "receiver_address": {
    "name": "Nguyen Van A",
    "phone": "02812345678",
    "mobile": "13800138000",
    "address": "广州市天河区体育西路123号",
    "province": "广东省",
    "city": "广州市",
    "area": "天河区"
  },
  "line_items": [
    {
      "mp_id": "734467086498",
      "id": "5578084256927",
      "quantity": 2,
      "price": 15.5
    }
  ]
}

line_items Field Explanation

Handling unavailable_items

The response returns an unavailable_items array containing products that cannot be ordered (out of stock, invalid SKU, discontinued). Do not allow order creation if this array is non-empty — ask users to resolve the problematic items first.

{
  "unavailable_items": [{ "mp_id": "123456", "id": "sku_789", "reason": "out_of_stock" }]
}

Optional Parameters

Create Order

View details: Create order

Creates a real order on the platform. The body is identical to preview — use data already validated from the preview step to create the order and avoid discrepancies.

Rate limit: 10 requests / 60 seconds

POST /v1/orders

After successful creation, redirect the user to the order detail page (/orders/ORD...). Do not keep the user on the cart page since the order has already been submitted to the platform.

Response Handling

ID Convention: Elim IDs always follow the ORD + 10 digits format (e.g., ORD0000000123). A successfully created order will also have the platform’s order_id.

List Orders

View details: List orders

Returns the order list for the current user (identified via JWT). Results are paginated.

Rate limit: 30 requests / 60 seconds

GET /v1/orders

Filter Parameters

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

Order Detail

View details: Order detail

Returns the complete and most up-to-date information for an order.

Rate limit: 30 requests / 60 seconds

GET /v1/orders/:id

Pass the ID in ORD... format.

Response Differences Between Taobao and 1688

The two platforms return different data structures — handle them separately:

The platform field is available in the list response — cache it from the list view so you know which component to render before calling detail.

Cancel Order

View details: Cancel order

Cancels an order that is in a cancellable status. After the system successfully cancels, call GET /v1/orders/:id again to get the latest status.

Rate limit: 10 requests / 60 seconds

POST /v1/orders/:id/cancel

Condition: Can only cancel when status is creating or pending_payment. Disable the cancel button for all other statuses.

Logistics Tracking

View details: Logistic detail

Returns domestic China shipping tracking information. Taobao only — 1688 orders already have logistics.logistics_info[] embedded in the order detail response.

Rate limit: 20 requests / 60 seconds

GET /v1/orders/:packageId/logistic-detail

packageId is an integer, obtained from the Taobao order detail response — not the ORD... format ID.

Order Payment

Elim acts as a purchasing agent: users pay Elim through a purchasing wallet (denominated in CNY), and Elim pays the platform outside the system. Full flow:

Preview → Create order (payment_status=unpaid) → Confirm wallet payment → payment_status=paid

Check Wallet Balance

GET /v1/purchasing/wallet

Response: { balance, frozen_balance, available } — available = balance - frozen_balance.

Confirm Payment

POST /v1/purchasing/orders/:id/confirm

The system checks the wallet → deducts funds → updates payment_status = paid.

Success response (200):

{
  "order_id": "ORD0000000001",
  "goods_amount_cny": 299.0,
  "shipping_fee_cny": 15.0,
  "service_fee_cny": 15.7,
  "total_amount_cny": 329.7,
  "paid_at": "2026-04-13T10:00:00.000Z",
  "balance_after": 1670.3
}

Use balance_after to update the wallet balance in local state without calling GET /v1/purchasing/wallet again.

Handling Insufficient Balance

When the wallet has insufficient funds, the system returns 400 with body:

{
  "error": "insufficient_balance",
  "deficit": 50.3,
  "current_balance": 279.4,
  "required": 329.7
}

Display a modal showing how much CNY is needed and guide the user to top up. The top-up process is handled outside the system (bank transfer) — admin confirms and credits the wallet manually.

Service Fee

Service fee formula: max(order_total × fee_percent, min_fee). The percentage and minimum are configured by admin.

Wallet Transaction History

GET /v1/purchasing/wallet/transactions

Exchange Rates

GET /v1/purchasing/exchange-rates

Returns the current exchange rates VND → CNY and USD → CNY configured by Elim. Display this to users before they top up.

Error Handling

All error responses follow the shape { statusCode, message, error }. Messages are sometimes in Vietnamese — they can be displayed directly to the user.