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
per_page	integer	No	10	Items per page (min: 1, max: 100).
sort	string	No	-created_at	Sort order: created_at. Prefix with - for descending.
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.
query	string	No	—	Search term. Matched as an exact email when it is a valid email address, otherwise as a partial, case-insensitive match on the product name or customer name.

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, a non-UUID customer / product, an out-of-range per_page, or an unknown sort field — returns a 400 (see Bad Request). The query search term is free-text and is always accepted.

Ordering: Orders default to created_at descending (newest first) unless sort is supplied.

Counting matches: every response includes the filtered total in pagination.total. To get only a count, request per_page=1 with your filters and read pagination.total.

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,
    "per_page": 10,
    "total": 42
  }
}

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.

Pagination Object

Field	Type	Description
current_page	integer	Current page number
total_pages	integer	Total number of pages
per_page	integer	Effective page size (echoes the per_page request parameter)
total	integer	Total number of orders matching the applied filters, across all pages

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."
}