Order lifecycle

An order goes from new to closed. Each step has its Admin API operation and its webhook event.

Statuses and events

status is the step the order is in. Each step has its own operation and webhook event.

partialDelivered, partialReturned, and partialCancelled appear when a change affects only some items. pendingToConfirm means an online store payment is still pending.

state sums up the order in four values:

status spells it cancelled and state spells it canceled.

Each event arrives with an OrderWebhookModel body. It has state and fulfillmentStatus, without status: to know the exact step, read the order.

Requirements

• An Admin token with the api_admin scope. See ERP integration.
• The order:read and order:update permissions. To invoice, also invoice:create.
• Node.js, or Python with requests, for the examples.

List orders

Filter by status to see the orders in one step. Repeat the parameter to ask for several: status=inProgress&status=invoiced.

curl "https://api.ecomiq.pe/api/v1/orders?status=confirmed&limit=20" \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

{
  "data": [
    {
      "id": "7204558912004325301",
      "orderNumber": "ORD-2026-0001",
      "firstName": "Andrea",
      "lastName": "Ramos",
      "status": "confirmed",
      "state": "open",
      "fulfillmentStatus": "unfulfilled",
      "currencyCode": "PEN",
      "total": 178,
      "orderDate": "2026-10-04T14:58:03Z"
    }
  ],
  "hasNextPage": false,
  "nextCursor": null,
  "totalCount": 1
}

Orders come newest first. You can also filter by state, dateFrom, dateTo, customerId, tags, or search. If hasNextPage is true, send nextCursor as cursor; see Pagination.

Read an order

Get the order to see its status, its dates, and its items.

curl https://api.ecomiq.pe/api/v1/orders/7204558912004325301 \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

{
  "id": "7204558912004325301",
  "orderNumber": "ORD-2026-0001",
  "status": "confirmed",
  "state": "open",
  "fulfillmentStatus": "unfulfilled",
  "confirmedAt": "2026-10-04T15:02:11Z",
  "currencyCode": "PEN",
  "total": 178,
  "items": [
    {
      "id": "7204558912004325302",
      "title": "Polo de algodón",
      "quantity": 2,
      "orderItemStatus": "confirmed"
    }
  ]
}

Each step keeps its date: confirmedAt, inProgressAt, invoicedAt, pickupAt, inTransitAt, completedAt, cancelledAt, closedAt, and invalidAt. completedAt marks delivery.

Confirm the order

Online store orders confirm themselves once the full payment is captured. Until then they stay in pendingToConfirm. If the payment fails or is cancelled, they move to invalid.

Confirm other orders with POST /v1/orders/{orderId}/confirm. The operation has no body.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325301/confirm \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

{
  "id": "7204558912004325301",
  "orderNumber": "ORD-2026-0001",
  "status": "confirmed",
  "state": "open",
  "confirmedAt": "2026-10-04T15:02:11Z"
}

If the order was already confirmed, the API returns 200 without sending another event.

Move the order forward

Each operation returns the updated order. Send every field in the table; any you don't have go as null, except trackingNumber in ready-to-pickup.

• Confirm online store orders, orders from a draft, and orders created with POST /v1/orders/batch first.
• You can skip steps, for instance from confirmed to inTransit. You cannot go back to an earlier step.
• If the order has prices awaiting approval, approve them with Approve order price.
• A change that isn't allowed returns 409.

This request marks the order in transit and emails Andrea.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325301/in-transit \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumber": "PE48213977",
    "trackingLink": "https://mitienda.pe/seguimiento/PE48213977",
    "carrierName": "Courier Lima",
    "notifyCustomer": true,
    "notificationChannels": ["email"]
  }'

{
  "id": "7204558912004325301",
  "orderNumber": "ORD-2026-0001",
  "status": "inTransit",
  "state": "open",
  "fulfillmentStatus": "shipped",
  "inTransitAt": "2026-10-05T10:15:40Z"
}

notifyCustomer defaults to true. In notificationChannels, pick email, whatsApp, or both. If you use fulfillment orders, their changes also move the order and send these events.

To move many orders at once, use Update order status in bulk. With up to 100 ids it returns 200 with a result per order. With filters it returns 202 with an operation.

Cancel the order

Cancel with POST /v1/orders/{orderId}/cancel until the order is delivered. Send cancelReason and cancelReasonType, or null for either.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325301/cancel \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cancelReason": "Nos quedamos sin stock del Polo de algodón.",
    "cancelReasonType": "sin-stock"
  }'

{
  "id": "7204558912004325301",
  "orderNumber": "ORD-2026-0001",
  "status": "cancelled",
  "state": "canceled",
  "fulfillmentStatus": "canceled",
  "cancelReason": "Nos quedamos sin stock del Polo de algodón.",
  "cancelledAt": "2026-10-04T17:40:09Z"
}

cancelReason appears in the cancellation notice to the customer. Cancelling also cancels the order's fulfillment orders. If it was already cancelled, the API answers 200 without sending another event.

To cancel and refund in one step, use Cancel order with refund. It only works before the order ships.

Return or close

Closing has no body.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325301/close \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

{
  "id": "7204558912004325301",
  "orderNumber": "ORD-2026-0001",
  "status": "closed",
  "state": "closed",
  "closedAt": "2026-10-12T09:00:00Z"
}

If a refund is pending, closing returns 409. A closed or invalid order no longer changes status.

Next steps