Skip to main content

Create Partner

Create a published partner in your store.

name and ref are required. ref is a lowercase slug, unique among published partners of this store. Omit commission_percent or cookie_valid_days, or send null, to inherit the store defaults. Send commission_percent, not commission.

Request​

POST /partners

Request Body​

ParameterTypeRequiredDescription
namestringYesPartner name. 1–255 characters.
refstringYesCheckout ?ref= slug. Lowercase letters, digits, and hyphens (^[a-z0-9-]+$), up to 49 characters. Unique among published partners of this store.
emailstringNoLinked account email, or null. Must already belong to an existing account. See Email.
cookie_valid_daysintegerNoCookie-length override, 1–3650, or null to inherit the store default.
commission_percentintegerNoCommission override, integer 1–100. 20 means 20%. null inherits the store default.

Unknown keys return 422. 20 means 20% — not 0.2.

Example Request​

curl -X POST "https://cart.easy.tools/api/v1/partners" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada",
    "ref": "ada",
    "email": "ada@example.com",
    "commission_percent": 15
  }'

Response​

Success Response (201)​

Returns the created partner. stats is null. Omitted cookie_valid_days is stored as null (inherit).

{
  "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",
  "stats": null
}

See the Partner object.

Error Responses​

Validation Error (422 Unprocessable Entity)​

Every 422 is a top-level message plus an errors object. That includes a missing name or ref, a ref that is not a slug or is longer than 49 characters, a ref already used by a published partner, an email that is not an existing account, an email that already has a published partner, the store referrer's email, commission_percent outside 1–100, cookie_valid_days outside 1–3650, and any unknown key.

commission is not a field. Send commission_percent.

{
  "message": "The given data was invalid.",
  "errors": {
    "commission": [
      "The commission field is not allowed."
    ]
  }
}

The store referrer's email is an email field error, and the partner is not saved. The same shape is used when the account already has a published partner in this store.

{
  "message": "Email \"referrer@example.com\" belongs to the store referrer",
  "errors": {
    "email": [
      "Email \"referrer@example.com\" belongs to the store referrer"
    ]
  }
}

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