Get Orders

Retrieve a list of orders from your store.

Orders of every status are returned by default, newest first. Narrow the list with the optional filters below — for example status=completed to return only paid orders. All filters combine with AND.

Request

GET /orders

Query Parameters

Parameter	Type	Required	Default	Description
page	integer	No	1	Page number for pagination
status	string	No	—	Filter by order status. One of created, awaiting_payment, processing, completed, canceled, refunded.
created_from	string	No	—	Only orders created on or after this date (inclusive), YYYY-MM-DD.
created_to	string	No	—	Only orders created on or before this date (inclusive), YYYY-MM-DD.
customer	string	No	—	Filter by customer UUID.
product	string	No	—	Filter by primary product UUID. Order bumps are not matched.

Omitting a filter or passing it empty means "no filter on that field". Passing a non-empty but unparseable value — an unknown status, a malformed date, or a non-UUID customer / product — returns a 400 (see Bad Request).

Example Request

curl -X GET "https://cart.easy.tools/api/v1/orders?status=completed&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Success Response (200)

Returns a paginated list of orders.

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "amount": 4900,
      "currency": "pln",
      "quantity": 1,
      "product_name": "Premium Course",
      "customer_email": "buyer@example.com",
      "created_at": "2026-05-27T10:15:30+00:00"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "status": "awaiting_payment",
      "amount": 1999,
      "currency": "eur",
      "quantity": 2,
      "product_name": "Organic Tea Selection",
      "customer_email": null,
      "created_at": "2026-05-26T08:00:00+00:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5
  }
}

Response Fields

Field	Type	Nullable	Description
id	string	No	Unique identifier for the order (UUID)
status	string	Yes	Order status (see the status filter for possible values). Null for legacy orders without a status.
amount	integer	No	Order total in minor units (e.g. cents/grosze)
currency	string	No	Lowercase ISO currency code (e.g. "pln", "eur")
quantity	integer	No	Quantity of the primary product
product_name	string	No	Primary product name, cached at purchase time
customer_email	string	Yes	Customer email. Null when the customer account is missing (e.g. a deleted user).
created_at	string	No	When the order was created (ISO 8601 format)

To read line items, transactions, refunds, invoices, or full customer details for an order, call Get Order with the include parameter.

Error Responses

Bad Request (400)

Returned when a filter has a non-empty but unparseable value. The message names the offending field and the value received.

{
  "message": "Invalid value for 'status': 'actve'"
}

Unauthorized (401)

{
  "message": "Unauthenticated."
}