Orders API

The Orders API covers the complete lifecycle of an order: listing and searching it, creating it, retrieving it, updating it, transitioning it between states, preparing and shipping it, managing returns and attachments, recovering abandoned carts, and auditing/exporting its history.

This article is the entry point to the domain. Read it before any other article in this section: it defines the response envelope, which governs the shape of absolutely every response in this API.

Base URL and authentication

https://api.fenicia.io

There is no version prefix (/v1) in the URL. All endpoints in this domain hang off the /orders base path.

Every request requires an API key sent as a Bearer token:

Authorization: Bearer fkapi_your_api_key

The response envelope (read this carefully)

Every response from the Orders API follows one of these three shapes. There are no exceptions within this domain except the one explicitly documented in Exception: abandoned carts below.

Success — single resource

{
  "data": {
    "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
    "externalId": "FEN-10042",
    "orderStatus": "accepted",
    "total": 1986.26,
    "_links": {
      "prepare": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/prepare",
      "cancel": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/cancel"
    }
  }
}

The meta field is optional in single-resource responses (it can carry additional links outside the resource, though _links typically lives inside data, as in the example above).

Success — paginated list

{
  "data": [
    { "_id": "65f3a1b2c4d5e6f7a8b9c0d1", "externalId": "FEN-10042", "orderStatus": "accepted" },
    { "_id": "65f3a1b2c4d5e6f7a8b9c0d2", "externalId": "FEN-10043", "orderStatus": "pending" }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 143,
      "totalPages": 8,
      "hasMore": true
    }
  }
}

meta.pagination is required on every list response. meta.links is optional and, when present, carries navigation links for the collection itself — don't confuse it with the _links object on each individual resource.

Error

{
  "error": {
    "code": "orders:not_found",
    "message": "Order not found",
    "details": {
      "field": "orderId",
      "value": "65f3a1b2c4d5e6f7a8b9c0d1"
    }
  }
}

The error always comes wrapped in an error object — code/message never appear as top-level properties. code always follows the namespace:snake_case format (e.g. orders:not_found, returns:already_approved). The complete catalog of codes, grouped by namespace, is in the Error Catalog.

HATEOAS links (_links)

Order and return resources include an _links object inside data with the actions valid for the resource's current state. The possible actions are: accept, reject, cancel, prepare, fulfill, returns. A well-built client doesn't need to hardcode which transition is valid in which state — it simply checks whether the link is present in the response.

Pagination

List endpoints accept page and limit as query params and return meta.pagination with page, limit, total, totalPages, and hasMore. The exact defaults and limits for each endpoint are documented in its own article (see List orders).

Common list filters

Most list endpoints (GET /orders, /orders/search, the count endpoints, /orders/export) share the same filter normalizer. The most commonly used:

The exhaustive list, with types and examples, lives in List orders.

State machine (summary)

An order moves through a directed state graph — not a simple linear flow. The terminal states (with no outgoing transitions) are cancelled, rejected, and returned; the rest have one or more valid transitions depending on the channel, the fulfillment mode, and whether the order ships in one or multiple parts.

To visually group orders (for example on a board), the API exposes a reduced set of status groups, distinct from the individual states in the transition state machine:

Don't hardcode the transition graph in your application: use _links on each response to know which action is valid at any given moment, and consult State Transitions for the full state machine, including the cancellation reason taxonomy.

Exception: abandoned carts

{
  "data": {
    "data": [
      { "id": "cart_8f2a1", "status": "abandoned", "totalValue": 1245.00 }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 34,
      "totalPages": 2,
      "hasMore": true
    }
  }
}

Additionally, the legacy path /abandoned-carts/* (without the /orders prefix) still works but is deprecated as of 2026-06-01. The canonical, recommended route is /orders/abandoned-carts/*. Full detail in Abandoned Carts.

Quick example

curl https://api.fenicia.io/orders?limit=5 \
  -H "Authorization: Bearer $FENICIA_API_KEY"

Section map

Next steps

• List orders
• Create an order
• Error catalog