Get Products

Retrieve a list of products from your store.

Only draft and published products are returned, newest first; archived products never appear. Narrow the list with the optional filters below — for example status=draft to return only unpublished products, or query=coffee to search by name or description. All filters combine with AND.

Request

GET /products

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 or name. Prefix with - for descending.
status	string	No	—	Filter by publication status. One of draft or published.
created_from	string	No	—	Only products created on or after this date (inclusive), YYYY-MM-DD.
created_to	string	No	—	Only products created on or before this date (inclusive), YYYY-MM-DD.
query	string	No	—	Search term. Partial, case-insensitive match on product name or description.

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, an out-of-range per_page, or an unknown sort field — returns a 400 (see Bad Request). The query term is matched loosely and never returns a 400.

Ordering: Products 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 and read pagination.total.

Example Request

curl -X GET "https://cart.easy.tools/api/v1/products?status=published&query=coffee" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Success Response (200)

Returns a paginated list of products.

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "published",
      "name": "Premium Coffee Beans",
      "description": "High-quality arabica coffee beans from Colombia",
      "image_url": "https://example.com/images/coffee-beans.jpg",
      "checkout_url": "https://cart.easy.tools/checkout/550e8400-e29b-41d4-a716-446655440000",
      "currency": "usd"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "status": "draft",
      "name": "Organic Tea Selection",
      "description": null,
      "image_url": null,
      "checkout_url": "https://cart.easy.tools/checkout/550e8400-e29b-41d4-a716-446655440001",
      "currency": "eur"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "per_page": 10,
    "total": 45
  }
}

Response Fields

Field	Type	Nullable	Description
id	string	No	Unique identifier for the product (UUID)
status	string	No	Product status (e.g., "published" or "draft")
name	string	No	Product name
description	string	Yes	Product description
image_url	string	Yes	URL to the product image
checkout_url	string	No	Direct checkout URL for the product
currency	string	No	ISO currency code (e.g., "usd", "eur")

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 products, across all pages

Error Responses

Bad Request (400)

Returned when status is not a valid value, a date is malformed, per_page is out of range, or sort names an unknown field. The message names the offending parameter and the value received.

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

Unauthorized (401)

{
  "message": "Unauthenticated."
}