Get Partners

Retrieve a paginated list of published partners from your store.

Archived partners and the store referrer are omitted. The list is identity only — no currency, and no per-row earnings. Narrow it with the optional filters below. All filters combine with AND.

Request

GET /partners

Query Parameters

Parameter	Type	Required	Default	Description
page	integer	No	1	Page number for pagination.
per_page	integer	No	25	Items per page (min: 1, max: 100). The default is 25, not 10.
sort	string	No	name	Sort field: name, created_at, or ref. Prefix with - for descending.
query	string	No	—	Partial match on name or ref.
created_from	string	No	—	Only partners created on or after this date (inclusive), YYYY-MM-DD. No date window when omitted.
created_to	string	No	—	Only partners created on or before this date (inclusive), YYYY-MM-DD. No date window when omitted.

Omitting a filter or passing it empty means no filter on that field. A present but unparseable value returns 400 (see Bad Request). That includes a malformed date, an out-of-range per_page, or an unknown sort field. The query search term is free text and is always accepted.

There is no currency and no include on this endpoint. Earnings for one partner are on Get Partner with include=stats.

Ordering: Partners default to name ascending 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/partners?per_page=25" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Success Response (200)

Returns a paginated list of partners. cookie_valid_days: null means the partner inherits the store default.

{
  "items": [
    {
      "id": "7c2e9a14-3b6f-4d81-9e25-0c8a1f4b6d30",
      "name": "Ada",
      "email": "ada@example.com",
      "ref": "ada",
      "cookie_valid_days": null,
      "commission_percent": 15,
      "is_auto_created": false,
      "created_at": "2026-05-27T10:15:30+00:00",
      "updated_at": "2026-05-27T10:15:30+00:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "per_page": 25,
    "total": 1
  }
}

Response Fields

The list item is the Partner object without stats.

Field	Type	Nullable	Description
id	string	No	Partner UUID.
name	string	No	Partner name.
email	string	Yes	Linked account email. Null when no account is linked.
ref	string	Yes	Checkout ?ref= slug.
cookie_valid_days	integer	Yes	Cookie-length override, in days. Null inherits the store default.
commission_percent	integer	Yes	Commission override. 15 means 15%. Null inherits the store default.
is_auto_created	boolean	No	True when checkout created this partner from an unknown ref.
created_at	string	No	When the partner was created (ISO 8601).
updated_at	string	No	When the partner was last updated (ISO 8601).

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; defaults to 25).
total	integer	Total number of partners 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 'sort': 'email'"
}

Unauthorized Error (401)

{
  "message": "Unauthenticated."
}

Forbidden Error (403)

Returned when your API key has not been granted access to the requested store.

{
  "message": "You do not have API access to the requested store."
}

Rate Limit Error (429 Too Many Requests)

Returned when you exceed the rate limit. The Retry-After response header gives the number of seconds to wait.

{
  "message": "Too many requests. Please retry after 60 seconds."
}