Partners

The Partners API lets you list, create, and update affiliate partners for your store, and read one partner's results in a single currency.

Overview

The Partners API provides endpoints to:

• List partners
• Retrieve a partner
• Create a partner
• Update a partner

A partner is a person who earns commission when a buyer checks out with their ref. Append ?ref= and that slug to a product checkout URL — for example https://cart.easy.tools/checkout/0632bef5-c308-42cd-9cba-89a7a4f722bb?ref=ada.

Purchase rows for every partner are a separate list — see Partner Transactions. Store-wide affiliate revenue, which is sale amount and not commission, is partners_revenue.

Endpoints

Method	Path	Description
GET	/partners	Paginated list of published partners. See Get Partners.
POST	/partners	Create a partner. See Create Partner.
GET	/partners/{id}	One partner. See Get Partner.
PATCH	/partners/{id}	Sparse update. See Update Partner.

{id} is the partner id (a UUID).

The list and the detail read return published partners. Archived partners and the store referrer are omitted from the list and return 404 on get and update. There is no archive endpoint.

Commission and cookie

commission_percent and cookie_valid_days on a partner are overrides. null means the partner inherits the store defaults on GET /store → partners. 20 means 20%.

Those store values are always integers, never null. Until the store saves its own, they are 7 days and 20%. See Partners.

Email

email is optional. When you send it, it must already belong to an existing account. No account is created and no invitation is sent. That account can be linked to only one published partner in the store.

The store referrer's email returns 422 and is not saved.

On update, email can be set only while it is null. A different address, or null, once an email is set returns 422. Sending the same email changes nothing. Omit the key to leave it unchanged.

Partner Object

Get Partners returns this object without stats. Get Partner, Create Partner, and Update Partner include 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. Lowercase letters, digits, and hyphens. Up to 49 characters on create and update.
cookie_valid_days	integer	Yes	Cookie-length override, in days. 1–3650 when set. Null inherits the store default.
commission_percent	integer	Yes	Commission override. 20 means 20%. Integer 1–100 when set. Null inherits the store default.
is_auto_created	boolean	No	True when checkout created this partner from a ref that was not already a partner. Read-only.
created_at	string	No	When the partner was created (ISO 8601).
updated_at	string	No	When the partner was last updated (ISO 8601).
stats	object	Yes	Detail only. Null unless include=stats. Null means the section was not requested, not that the totals are zero. See Stats Object.

Stats Object

Returned on Get Partner when include=stats. One currency, chosen with currency. Omitted dates mean all time.

sales_count counts sale rows only. amount and commission_amount add refund rows in, then stop at 0. amount for a fully refunded sale is 0. commission_amount for a fully refunded 1999 at 15% is 1, because the refund commission is 299. The signed refund rows themselves are on Get Partner Transactions.

conversion_rate_percent is a float. 0.24 means 0.24%. It is sales_count / visits_count * 100, rounded to two decimal places, then capped at 100. One visit with three sales is 100, not 300. It is null when visits_count is 0.

Field	Type	Nullable	Description
visits_count	integer	No	Unique checkout visits in this currency. Minimum 0.
sales_count	integer	No	Sale rows. Refund rows are not counted. Minimum 0.
amount	integer	No	Sale amount in minor units (e.g. cents). Refunds included, then clamped at 0.
commission_amount	integer	No	Commission in minor units (e.g. cents). Refunds included, then clamped at 0.
conversion_rate_percent	number	Yes	Float percentage. 0.24 means 0.24%. Null when visits_count is 0.
currency	string	No	Lowercase ISO-4217 code this breakdown is scoped to (e.g. usd).