List Orders

This endpoint returns a paginated list of your tenant's orders. It supports a wide range of filters (status, channel, dates, customer, shipping, tags) and a free-text search via q.

Use it when you need to:

Display a table or board of orders in your application.
Sync new or modified orders to an external system (combining startDate/endDate).
Filter orders by channel, status, or delivery status before batch-processing them.
Get quick counts by status group or individual status without pulling the full records.

Endpoint

Lists the authenticated tenant's orders, with filters and pagination

pagenumber

Page number.

limitnumber

Number of results per page.

orderStatusstring

Filters by exact order status. Alias: status. See the real states in State Transitions.

statusGroupstring

Filters by visual status group: pending, preparing, completed, cancelled, problematic, all.

channelIdsstring

One or more sales channel IDs. Alias: channelId.

salesChannelstring

Filters by channel type (e.g. shopify, amazon, manual). Alias: origin.

salesChannelsstring

Variant that accepts multiple channel types. Alias: origins.

locationstring

Filters by the order's location/branch.

startDatestring

Minimum date of the range (ISO 8601), based on the order's creation date.

endDatestring

Maximum date of the range (ISO 8601), based on the order's creation date.

paymentStatusstring

Filters by payment status.

tagsstring

Filters by tag(s) assigned to the order.

deliveryStatusstring

Filters by delivery status.

hasShipmentboolean

Filters orders that do (or don't) have an associated shipment.

fulfillmentModestring

Filters by fulfillment mode.

deliveryCarrierstring

Filters by delivery carrier.

customerIdstring

Filters the orders of a specific customer.

qstring

Free-text search. Same mechanism exposed by GET /orders/search.

extendstring

Controls the inclusion of additional related data in the response.

metafieldsstring

Filters by custom metafields. Receives a serialized JSON object.

200

{
  "data": [
    {
      "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
      "externalId": "FEN-10042",
      "handle": "fen-10042",
      "locationId": "65f2a0b1c4d5e6f7a8b9c0aa",
      "origin": "manual",
      "channelId": "manual",
      "orderStatus": "accepted",
      "paymentStatus": "paid",
      "currency": "MXN",
      "totalAmount": 1986.26,
      "subtotal": 1798.50,
      "tax": 287.76,
      "orderCreated": "2026-04-11T14:23:11.000Z",
      "items": [
        {
          "sku": "CAM-ROJO-M",
          "title": "Camisa Roja Talla M",
          "quantity": 2,
          "totalAmount": 998.00
        }
      ],
      "customerInfo": { "name": "María González" },
      "customerId": "65f3a1b2c4d5e6f7a8b9c0d2",
      "_links": {
        "prepare": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/prepare",
        "cancel": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/cancel"
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 143,
      "totalPages": 8,
      "hasMore": true
    }
  }
}

Required permission: orders:read

Real status groups

statusGroup only accepts pending, preparing, completed, cancelled, problematic, or all. It is a visual layer distinct from the fine-grained state machine used by transitions — see State Transitions.

Tip

orderStatus/status, channelIds/channelId, salesChannel/origin, and salesChannels/origins are alias pairs: use whichever name you prefer, both resolve to the same filter.

Examples

curl "https://api.fenicia.io/orders?statusGroup=preparing&limit=20&page=1" \
  -H "Authorization: Bearer fkapi_your_api_key"

Order counts

Three endpoints return counts without pulling the full records. They accept the same set of filters as the list endpoint (orderStatus, statusGroup, channelIds, salesChannel, startDate, endDate, etc.); they don't apply page/limit since they don't paginate results.

Total count

Counts the orders that match the given filters

200

{ "data": { "count": 143 } }

Required permission: orders:read

Count by status group

Counts orders grouped by visual status group

200

{
  "data": {
    "pending": 12,
    "preparing": 34,
    "completed": 89,
    "cancelled": 6,
    "problematic": 2
  }
}

Required permission: orders:read

all is not an independently countable group: it represents the absence of a group filter, not a category with its own count.

Count by individual status

Counts orders grouped by individual state machine status

200

{
  "data": {
    "pending": 12,
    "accepted": 20,
    "processing": 14,
    "preparing": 34,
    "packaging": 8,
    "fulfilled": 40,
    "delivered": 49,
    "cancelled": 6,
    "returned": 3
  }
}

Required permission: orders:read

The possible keys are the individual states of the state machine (see State Transitions); the example shows a representative subset, not the full 23 states.

Errors

Code	Status	Description
`validation:invalid_pagination`	400	`page` or `limit` has an invalid value.
`validation:invalid_date_range`	400	`startDate`/`endDate` form an invalid range.
`validation:invalid_value`	400	Some filter received a value with an incorrect format.
`auth:invalid_token`	401	The API key is invalid or has been revoked.
`auth:permission_denied`	403	The API key doesn't have the `orders:read` permission.

See the full error catalog for the rest of the possible codes.

Tenant isolation

The list only includes orders from your own tenant. There is no way to query another tenant's orders from this endpoint.