How to create & manage orders on Taobao/1688

When to use this guide

Use this guide when your users need to place proxy purchasing orders on Taobao/1688 through Elimapi — from order preview and creation to tracking and wallet payment.

Note: This feature currently only supports the Vietnamese market. Other markets will be added later.

Full reference (statuses, endpoints, parameters, errors): Order API reference

Prerequisites

• API credentials (JWT or API Key) — see Authenticating API requests
• Product ID and SKU ID — get them from searching for products
• A valid shipping address in China

Overview of the flow

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

Each order has two independent statuses: status (platform) and payment_status (Elim wallet). Always display both in the UI — never merge them into one.

Step 1 — Preview the order

Call preview to get the estimated total and check item availability. This step does not create an order or deduct money.

POST /v1/orders/preview

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

Always check unavailable_items: if this array is not empty, do not allow creating the order — ask the user to resolve the problematic items (out of stock, wrong SKU, delisted) first.

The shipping address must be a valid address in China.

Step 2 — Create the order

Use the exact data validated in the preview step (same body) to create the real order:

POST /v1/orders

After a successful creation, redirect the user to the order detail page (/orders/ORD...) — the order has already been submitted to the platform, don’t keep the user in the cart.

Handle the response:

[!WARNING] If the response returns status: "unknown", show the warning “The order may not have been created — please contact support.” Do not continue the payment flow.

Step 3 — Query orders

List orders (paginated, identified by JWT):

GET /v1/orders?page=1&size=20&platform=taobao&status=paid

Filter parameters: page, size, platform (taobao/alibaba), status, created_from, created_to.

line_items in the list is a snapshot from order creation. For the latest data, call the order detail endpoint.

Order detail:

GET /v1/orders/:id

Note the response differences between platforms:

Cache the platform field from the list response to render the right component before calling detail.

Step 4 — Cancel the order (if needed)

POST /v1/orders/:id/cancel

Condition: only cancellable when status is creating or pending_payment. Disable the cancel button in other states. After cancelling, call GET /v1/orders/:id again for the latest status.

If the order has no platform order ID yet, the system returns { success: true, message: 'Internal order cancelled, no external order to cancel' } — cancelled in Elim but no operation happened on Taobao/1688.

Step 5 — Pay for the order

Elim acts as a purchasing agent: the user pays Elim via the purchasing wallet (in CNY), and Elim settles with the platform out of band.

1. Check wallet balance: GET /v1/purchasing/wallet → { balance, frozen_balance, available }
2. Confirm payment: POST /v1/purchasing/orders/:id/confirm → the system checks the wallet, deducts the amount, and updates payment_status = paid.
3. Use balance_after from the response to update the wallet balance without another call.
4. If the wallet has insufficient funds, the system returns 400 with { error: "insufficient_balance", deficit, current_balance, required } — show a modal with the missing CNY amount and top-up instructions.

Verify the result

• Preview returns a total matching expectations and an empty unavailable_items.
• Create returns data.id in ORD... form and status = pending_payment.
• Payment confirmation returns payment_status = paid with balance_after.
• Order detail shows the correct status and payment_status.

Common errors

Related links

• Reference: Order API reference — full statuses, parameters, error codes
• Auth: Authenticating API requests