SoftSolzSoftSolz
HomeAPI GuideAPI ReferenceWidget Tester
Affiliates

Add a partner and issue their code

Add a partner to the programme. Only name is needed: when no commission fields are sent the partner earns the programme rate (10 percent when the programme has none), and when no code is sent one is made from the letters and numbers of the name. Answers 409 affiliate_exists when the code is already taken, 400 invalid_affiliate_code, invalid_percent, invalid_amount, invalid_email, name_too_long, invalid_cookie_days or invalid_recurring_months when a value is not valid, and 404 when contact_id or programme_id is not in this workspace.

POSThttps://app.softsolz.uk/api/v1/services/affiliates/affiliates

Recent Requests

Kept only in this browser
TimeStatusTook
Send a request with Try it to see it here.

Headers

Authorizationstringrequired

Bearer token: Bearer sk_live_... (or sk_test_... for sandbox). A login token will not work here.

Idempotency-Keystring

Optional idempotency key for safe retries.

Body Params

namestringrequired

Partner name, up to 200 characters (400 name_too_long beyond that).

emailstring | null

Partner email address. Used to stop a partner earning commission on their own purchases. Answers 400 invalid_email when it is not a valid address.

codestring

Referral code, 3 to 32 letters, numbers, dashes or underscores. Stored upper-cased and unique in the workspace.

commission_typestring

Pay a percentage of each sale or a fixed amount per sale.

commission_percentnumber

Percentage of each sale, above 0 and up to 100 (400 invalid_percent otherwise). Leave every commission field out to use the programme rate.

commission_amount_centsinteger

Fixed amount per sale in minor units. Needed when commission_type is amount.

currencystring

Currency the partner earns and is paid in (ISO 4217). Defaults to GBP.

contact_idstring | null

CRM contact to link the partner to. Must be a contact in this workspace.

programme_idstring | null

Partner programme to place the partner in. Its hold period, payout minimum and tiers then apply. Left out, the partner joins the workspace programme; send null to keep the partner outside it.

cookie_daysinteger | null

Days a referral link click keeps crediting this partner, 0 to 365 (400 invalid_cookie_days otherwise). Null uses the programme setting.

recurring_monthsinteger | null

Billing periods of a subscription that earn commission. null uses the programme setting, 0 means the first payment only, a positive number is that many periods, and -1 means every payment for life. Any other negative number answers 400 invalid_recurring_months.

notesstring | null

Private notes about the partner.

Response

Response Body

idstringPartner id.
contact_idstring | nullCRM contact this partner is linked to, or null.
namestringPartner name.
emailstring | nullPartner email address, lower-cased.
codestringReferral code, upper-cased. Customers and your systems quote it to credit a sale.
commission_typestringWhether the partner earns a percentage of each sale or a fixed amount per sale.
commission_percentnumber | nullPercentage of each sale, when commission_type is percent.
commission_amount_centsinteger | nullFixed amount per sale in minor units, when commission_type is amount.
currencystringCurrency the partner earns and is paid in (ISO 4217).
statusstringOnly active partners can earn new commission.
programme_idstring | nullPartner programme this partner belongs to, or null.
tier_idstring | nullTier the partner has reached in their programme, or null.
tier_namestring | nullName of the tier the partner has reached. Filled in on reads, null in the reply to a create or update.
cookie_daysinteger | nullHow many days a referral link click keeps crediting this partner. 0 is stored and returned as 0. Null uses the programme setting.
recurring_monthsinteger | nullHow many billing periods of a subscription earn commission. null uses the programme setting, 0 means the first payment only, a positive number is that many periods, and -1 means every payment for life.
uses_programme_ratebooleanTrue when the partner earns exactly the programme rate, false when they have their own rate. Filled in on reads.
portal_enabledbooleanWhether the partner has been invited to their own partner portal.
notesstring | nullPrivate notes about the partner.
lifetime_revenue_centsintegerTotal sales credited to this partner, in minor units.
lifetime_commission_centsintegerTotal commission credited to this partner, in minor units.
click_countintegerClicks on all of this partner referral links.
conversion_countintegerSales credited to this partner.
created_atstringWhen the partner was added.
updated_atstringWhen the partner was last changed.

Request

curl --request POST \
--url https://app.softsolz.uk/api/v1/services/affiliates/affiliates \
--header 'Authorization: Bearer sk_live_your_key' \
--header 'Content-Type: application/json' \
--data '{
"name": "Acme Media",
"email": "partners@acmemedia.example",
"code": "ACMEMEDIA",
"commission_type": "percent",
"commission_percent": 15,
"recurring_months": 12,
"notes": "Runs a newsletter for small agencies."
}'

Credentials

Sent as a Bearer token and used in the samples above and in Try it. Kept only in this browser tab until you close it. Use an sk_test_ key to stay in your sandbox.

Response · 201

{
"data": {
"id": "12",
"contact_id": null,
"name": "Acme Media",
"email": "partners@acmemedia.example",
"code": "ACMEMEDIA",
"commission_type": "percent",
"commission_percent": 15,
"commission_amount_cents": null,
"currency": "GBP",
"status": "active",
"programme_id": null,
"tier_id": null,
"tier_name": null,
"cookie_days": 60,
"recurring_months": 12,
"uses_programme_rate": true,
"portal_enabled": false,
"notes": "Runs a newsletter for small agencies.",
"lifetime_revenue_cents": 250000,
"lifetime_commission_cents": 37500,
"click_count": 148,
"conversion_count": 3,
"created_at": "2026-09-01T09:00:00.000Z",
"updated_at": "2026-09-14T16:20:00.000Z"
}
}