Manual orders

Andrea messages you on WhatsApp from Trujillo and asks for two T-shirts. You build her order with the Admin API, send her a link, and she pays in your store.

Requirements

• An Admin token with the draft:create, draft:read, and draft:update permissions in ECOMIQ_TOKEN. To record a payment, also order:update and payment:create. See Quickstart.
• The /drafts/{shareToken} route in your store. Ecomiq themes already have it. In a headless store, you build it.
• Node.js, or Python with requests, for the examples.

Create the draft

A manual order starts as a draft. Send the currency and the customer's details.

curl -X POST https://api.ecomiq.pe/api/v1/order-drafts \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currencyCode": "PEN",
    "email": "andrea.ramos@example.com",
    "firstName": "Andrea",
    "lastName": "Ramos",
    "phone": "+51987654321",
    "source": "whatsapp"
  }'

It returns 201 with the draft's id. The next steps reuse ADMIN, headers, and HEADERS.

• Without customerId, send email, firstName, and lastName. With it, the draft copies the customer's details and default address.
• The draft starts as draft and gets a store number: D1, D2…
• GET /v1/order-drafts sorts by draftDate descending. Change the order with sortBy (draftDate, draftNumber, total, createdOn, or updatedOn) and sortDirection (asc or desc).

Add the products

Add a catalog variant with its quantity. discount is the discount for the whole line, as a negative amount, or 0 for none. shipping adds up each line's shipping and the selected shipping methods.

curl -X POST https://api.ecomiq.pe/api/v1/order-drafts/7204558912004324769/items \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "catalogVariant",
    "variantId": "7204558912004321180",
    "quantity": 2,
    "discount": -20
  }'

{
  "items": [
    {
      "id": "7204558912004323771",
      "title": "Cotton T-shirt",
      "quantity": 2,
      "discount": -20.0,
      "total": 158.0
    }
  ],
  "tax": 24.1,
  "total": 158.0
}

• unitPrice changes the price in this draft only. For something outside the catalog, use "kind": "custom" with title and unitPrice.
• Tax on catalog products is calculated for you.
• Change a line with PATCH /v1/order-drafts/{draftId}/items/{itemId}. Use quantity: 0 or DELETE to remove it.

Add the address and shipping

Send the shipping address. PATCH only changes what you send.

curl -X PATCH https://api.ecomiq.pe/api/v1/order-drafts/7204558912004324769 \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shippingAddress": {
      "name": "Andrea Ramos",
      "address1": "Av. España 1520",
      "city": "Trujillo",
      "countryCode": "PE"
    }
  }'

Then ask for the shipping options for that address.

curl https://api.ecomiq.pe/api/v1/order-drafts/7204558912004324769/shipping-options \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

Each option has displayName, price, shippingMethodId, target, targetId, and rateId. Set one with those last four values; the draft ends up with shipping: 12 and total: 170.

curl -X PUT https://api.ecomiq.pe/api/v1/order-drafts/7204558912004324769/shipping-method \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "shippingMethodId": "7204558912004328810", "target": "automatic" }'

• Send billingAddress the same way: converting needs both, each with name, address1, city, and countryCode.
• If you change the shipping address or the products, set the shipping again. DELETE /v1/order-drafts/{draftId}/shipping-method removes it.
• With several sellers or shipping profiles, each group needs its own shipping: pass sellerId or shippingProfileId.

Share the payment link

Create the link and send it to the customer on WhatsApp. shareExpiresAt is optional and must be in the future; without it, the link never expires.

curl -X POST https://api.ecomiq.pe/api/v1/order-drafts/7204558912004324769/share \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "shareExpiresAt": "2026-10-09T05:00:00Z" }'

{
  "shareToken": "Jm2xQ9vT4pLk8sWb1nZr6cYh0uEa3dFg",
  "sharePath": "/drafts/Jm2xQ9vT4pLk8sWb1nZr6cYh0uEa3dFg"
}

The link is your store's primary domain plus sharePath. See List store domains.

• The draft moves to sent. Each call creates a new token and the previous one stops working.
• With "allowAnonymousShareAccess": false, the customer must sign in to your store.
• To send it by email, use Send draft invoice.

Collect in your store

At /drafts/{shareToken}, your store shows the draft with the Storefront API. When the customer confirms, it turns the draft into an order.

The GET returns what the buyer sees: draft number and status, contact, addresses, items with shipping, tax, and warranty, amounts, and shipping methods with their price and delivery dates. Internal notes, tags, and metadata aren't included.

curl https://storefront.ecomiq.pe/v1/order-drafts/share/<share-token> \
  -H "x-Store-Domain: mi-tienda"

curl -X POST https://storefront.ecomiq.pe/v1/order-drafts/share/<share-token>/checkout \
  -H "x-Store-Domain: mi-tienda" \
  -H "Content-Type: application/json" \
  -d '{ "invoiceType": "ticket" }'

The checkout returns orderPaths, with /orders/{statusToken} paths. Send the customer there to pay the balance, as in Checkout and payment.

• Opening the draft moves it to viewed, and the checkout to converted. Check it with GET /v1/order-drafts/{draftId}, or list the viewed ones with GET /v1/order-drafts?status=viewed.
• If it was already converted, GET returns orderPaths: redirect the customer.
• One order is created per seller and shipping profile, each with its own path.

Or collect from the admin

If the customer already paid with Yape, convert the draft yourself.

curl -X POST https://api.ecomiq.pe/api/v1/order-drafts/7204558912004324769/convert \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invoiceType": "ticket" }'

{
  "orderIds": ["7204558912004325350"],
  "order": {
    "orderNumber": "ORD-2026-0001",
    "status": "new",
    "financialSummary": { "balanceDue": 170.0 }
  }
}

Then record the payment on each order in orderIds, for its balanceDue.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325350/payments \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "method": "yape", "currencyCode": "PEN", "amount": 170,
        "reference": "Operation 845120", "idempotencyKey": "D1-yape" }'

• Converting needs items, both addresses, and shipping for each group.
• If the draft was already converted, it returns 200 with the same orders.
• When the payment covers the total, the order moves to confirmed.

Cancel a draft

You don't delete a draft: you cancel it.

curl -X POST https://api.ecomiq.pe/api/v1/order-drafts/7204558912004324769/cancel \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "The customer bought in store." }'

• The draft moves to cancelled and its link stops working.
• reason is required, with a maximum of 500 characters. The admin detail stores it as cancelReason; the draft notes are preserved.
• A converted draft can't be cancelled: cancel its order instead.

Errors

Next steps

• Checkout and payment
• Order lifecycle
• Order drafts