Search Orders

This endpoint combines free-text search (q) with the same set of structured filters exposed by the order list. In practice, GET /orders also accepts q, so both endpoints offer equivalent search functionality; use /orders/search when the main purpose of the query is a text search.

Use it when you need to:

  • Find an order from a partial piece of data (external ID, customer name, SKU) without building exact filters.
  • Power customer support with a single search bar.
  • Combine free text with date, channel, or status filters.

Endpoint

Searches orders combining free text with structured filters

qstring

Free-text search term. In practice, this is the purpose of this endpoint.

pagenumber

Page number.

limitnumber

Number of results per page.

orderStatusstring

Filters by exact order status. Alias: status.

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).

endDatestring

Maximum date of the range (ISO 8601).

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.

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",
      "origin": "manual",
      "channelId": "manual",
      "orderStatus": "accepted",
      "paymentStatus": "paid",
      "currency": "MXN",
      "totalAmount": 1986.26,
      "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" },
      "_links": {
        "prepare": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/prepare",
        "cancel": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/cancel"
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 3,
      "totalPages": 1,
      "hasMore": false
    }
  }
}

Required permission: orders:read

Tip

/orders/search and GET /orders with q resolve the same search. If your integration already lists orders with filters, it's simpler to add q to that same call than to maintain two separate code paths.

Examples

curl "https://api.fenicia.io/orders/search?q=maria%40example.com&orderStatus=accepted" \
  -H "Authorization: Bearer fkapi_your_api_key"

Errors

CodeStatusDescription
validation:invalid_pagination400page or limit has an invalid value.
validation:invalid_date_range400startDate/endDate form an invalid range.
validation:invalid_value400Some filter received a value with an incorrect format.
auth:invalid_token401The API key is invalid or has been revoked.
auth:permission_denied403The API key doesn't have the orders:read permission.

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

Next steps