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.
https://app.softsolz.uk/api/v1/services/affiliates/affiliatesRecent Requests
Kept only in this browserHeaders
AuthorizationstringrequiredBearer token: Bearer sk_live_... (or sk_test_... for sandbox). A login token will not work here.
Idempotency-KeystringOptional idempotency key for safe retries.
Body Params
namestringrequiredPartner name, up to 200 characters (400 name_too_long beyond that).
emailstring | nullPartner email address. Used to stop a partner earning commission on their own purchases. Answers 400 invalid_email when it is not a valid address.
codestringReferral code, 3 to 32 letters, numbers, dashes or underscores. Stored upper-cased and unique in the workspace.
commission_typestringPay a percentage of each sale or a fixed amount per sale.
commission_percentnumberPercentage 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_centsintegerFixed amount per sale in minor units. Needed when commission_type is amount.
currencystringCurrency the partner earns and is paid in (ISO 4217). Defaults to GBP.
contact_idstring | nullCRM contact to link the partner to. Must be a contact in this workspace.
programme_idstring | nullPartner 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 | nullDays a referral link click keeps crediting this partner, 0 to 365 (400 invalid_cookie_days otherwise). Null uses the programme setting.
recurring_monthsinteger | nullBilling 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 | nullPrivate 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" }}