Order management

Every morning, a store in Lima reviews yesterday's orders with the Admin API: it finds the unpaid ones, tags the urgent ones, and archives the delivered ones.

Requirements

• An Admin token in ECOMIQ_TOKEN. See Quickstart.
• The order:read permission to find, read, and export, and order:update for everything else.
• Node.js 18 or Python with requests, for the examples.

Find orders

GET /v1/orders filters by status, date, tag, and text. This example returns yesterday's orders that still have a balance to collect.

curl "https://api.ecomiq.pe/api/v1/orders?task=toCollect&dateFrom=2026-10-05T05:00:00Z&dateTo=2026-10-06T04:59:59Z&limit=50" \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

{
  "data": [
    {
      "id": "7204558912004325301",
      "orderNumber": "ORD-2026-0142",
      "firstName": "Andrea",
      "lastName": "Ramos",
      "status": "new",
      "state": "open",
      "currencyCode": "PEN",
      "total": 178,
      "paymentAt": null,
      "tags": null,
      "assignee": null,
      "archivedOn": null,
      "orderDate": "2026-10-05T19:42:10Z"
    }
  ],
  "hasNextPage": false,
  "nextCursor": null,
  "totalCount": 1
}

The next steps reuse ADMIN, headers, and HEADERS.

• Repeat a parameter to send several values: status=new&status=confirmed.
• Without archived, the list includes archived orders. task leaves out archived, canceled, and invalid orders.
• Sort with sortBy (orderDate, orderNumber, total, or updatedOn) and sortDirection. The default is newest first. See Pagination.

Read an order

With include=trackings, the response adds the order timeline, newest first.

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

{
  "id": "7204558912004325301",
  "orderNumber": "ORD-2026-0142",
  "status": "new",
  "state": "open",
  "email": "andrea.ramos@example.com",
  "total": 178,
  "notes": null,
  "tags": null,
  "assignee": null,
  "archivedOn": null,
  "updatedOn": "2026-10-05T19:42:10.512344Z",
  "financialSummary": {
    "paidAmount": 0,
    "refundedAmount": 0,
    "balanceDue": 178,
    "refundableAmount": 0
  },
  "trackings": [
    {
      "type": "new",
      "title": "Order Created",
      "content": "Order created successfully.",
      "createdOn": "2026-10-05T19:42:10Z"
    }
  ]
}

Keep updatedOn: you need it to change the note.

Add a note and an assignee

PATCH /v1/orders/{orderId}/notes changes the internal note and the team member in charge of the order. It returns 204.

curl -X PATCH https://api.ecomiq.pe/api/v1/orders/7204558912004325301/notes \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Leave it at the front desk. The customer works during the day.",
    "assignedMemberId": "7204558912004320011",
    "expectedUpdatedOn": "2026-10-05T19:42:10.512344Z"
  }'

• The call replaces both fields. assignedMemberId: null removes the assignee; to keep it, send the current assignee.memberId.
• The assignee must be an active member of the store.
• Send updatedOn exactly as you read it, without parsing it as a date. If the order changed, the API returns 409: read it again and retry.

Comment on the order

The note is a single text. Comments add up in the timeline, with your user and the time.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325301/comments \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Called Andrea: she pays today by bank transfer." }'

It returns 204. The comment shows up in trackings with type: "note". It takes up to 2,000 characters, attachmentUrls, and up to 20 mentionedMemberIds to alert your team.

Tag orders

PATCH /v1/orders/{orderId}/tags replaces every tag. Read tags, add yours, and send the full list.

curl -X PATCH https://api.ecomiq.pe/api/v1/orders/7204558912004325301/tags \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tags": "urgent,gift" }'

• Separate tags with commas and no spaces. The whole text takes up to 500 characters. Empty or null clears them.
• Then filter with tags=urgent. The filter ignores case.
• A seller token can't tag or comment: the API returns 403.

Send a payment reminder

POST /v1/orders/{orderId}/payment-reminder emails the customer the balance due.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325301/payment-reminder \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "reminder-ORD-2026-0142-1",
    "dueDate": "2026-10-08"
  }'

• It returns 202. If you repeat the idempotencyKey, the customer gets a single email. Use up to 50 characters.
• dueDate is optional and shows in the email.
• The order needs an email and a balance due. It can't be canceled or invalid.

Cancel an order

If the customer didn't pay, cancel the order. notifyCustomer: false skips the cancellation email.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325301/cancel \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cancelReason": "We did not receive the payment.",
    "cancelReasonType": "unpaid",
    "notifyCustomer": false
  }'

It returns 200 with the order. Statuses and events are in Order lifecycle.

• Authorized payments that weren't captured are released, unless the same payment covers another active order.
• Canceling doesn't return money already captured. Check financialSummary.refundableAmount and refund it with Returns and refunds.
• To cancel and refund in one step before shipping, use Cancel order with refund. It also needs payment:create.

Archive orders

Archiving takes the order out of your daily list. It doesn't change its status or its payments.

curl -X PUT https://api.ecomiq.pe/api/v1/orders/7204558912004325301/archive \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

• It returns 204. Send "archived": false to restore it.
• To find delivered orders still in view, search with status=delivered&archived=false.
• Canceling an order archives it too. With orderProcessing.autoArchiveDeliveredOrders in the store settings, delivered and paid orders are archived automatically.

Update in bulk

POST /v1/orders/batch/status moves several orders to the same status. This example cancels three unpaid orders.

curl -X POST https://api.ecomiq.pe/api/v1/orders/batch/status \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetStatus": "cancelled",
    "ids": ["7204558912004325301", "7204558912004325302", "7204558912004325303"],
    "cancelReason": "No payment received within 48 hours.",
    "cancelReasonType": "unpaid"
  }'

{
  "results": [
    {
      "index": 0,
      "id": "7204558912004325301",
      "status": "updated",
      "errors": []
    },
    {
      "index": 1,
      "id": "7204558912004325302",
      "status": "updated",
      "errors": []
    },
    {
      "index": 2,
      "id": "7204558912004325303",
      "status": "failed",
      "errors": [
        {
          "field": "id",
          "code": "Orders.NotFound",
          "message": "Order not found."
        }
      ]
    }
  ]
}

Each order is processed on its own. Check the status of every result.

• Send ids (up to 100) or filters, not both. With filters, the API returns 202 with an operation; follow it with Get operation.
• An empty filters selects every order in the store. Narrow it with statuses, tags, dateFrom, dateTo, or orderIds.
• targetStatus accepts confirmed, inProgress, invoiced, readyToPickUp (with trackingNumber), inTransit, delivered, cancelled, returned, closed, and invalid. A bulk cancel always notifies the customer.

Export orders

POST /v1/orders/exports builds a file with the orders you pick. It returns 202 with an operation.

curl -X POST https://api.ecomiq.pe/api/v1/orders/exports \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "statuses": ["delivered"],
    "dateFrom": "2026-09-01T05:00:00Z",
    "dateTo": "2026-10-01T04:59:59Z"
  }'

{
  "id": "7204558912004325410",
  "status": "pending",
  "resource": "orders",
  "format": "csv",
  "createdOn": "2026-10-06T13:05:00Z"
}

• Filters go in the body, in plural: statuses, states, fulfillmentStatuses, tags, orderIds, and orderNumbers.
• format accepts csv, xlsx, or jsonl. The default is xlsx.
• Poll GET /v1/operations/{id}. Once status is completed, resultUrl points to the file.

Errors

Next steps

• Order lifecycle: confirm, ship, and deliver.
• Returns and refunds: give back captured money.
• Orders: every operation.