Credit a sale to a partner code
Credit a sale to the partner who owns the code. The commission is worked out from the best rate that applies (a product rate, the partner tier, the partner own rate, then the programme) and is held as pending for the refund window before it can be paid. Crediting the same sale and period twice saves nothing and answers the existing commission with already_recorded true. Answers 400 affiliate_not_found for an unknown code, 400 invalid_amount for a negative sale_amount_cents, 400 contact_not_found when contact_id is not a contact in this workspace, 409 affiliate_inactive for a paused or closed partner, and 409 self_referral when the buyer is the partner (the attempt is flagged for review in the dashboard).
https://app.softsolz.uk/api/v1/services/affiliates/affiliates/commissionsRecent 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
codestringrequiredReferral code of the partner to credit (any letter case).
subject_typestringrequiredWhat kind of sale this is.
subject_idstringrequiredYour reference for the sale, such as an invoice id or order number. One commission is kept per partner, sale and period.
sale_amount_centsintegerrequiredSale value in minor units (pence or cents).
subject_referencestringOptional human reference shown next to the sale, such as an invoice number from your own system.
sale_currencystringCurrency of the sale (ISO 4217). Defaults to the partner currency. Commission is paid in the partner currency with no conversion.
period_indexintegerBilling period of a recurring sale: 0 for the first payment, 1 for the second and so on. Periods beyond the partner recurring allowance answer recorded false. The allowance is the partner recurring_months, or the programme setting when that is null: 0 is the first payment only, a positive number is that many periods, -1 is every payment.
contact_idstringBuyer, used to block self-referral and shown on the commission. The CRM contact id (a UUID). It is the contact_id returned when you convert a lead with the My Leads API, the contact_id on a quote, or the id of the contact on the Contacts page of the dashboard.
product_idsarray of stringsCatalog product ids in the sale, so a product commission rate can apply.
Response
Response Body
idstringCommission id.affiliate_idstringPartner who earned it.affiliate_namestring | nullPartner name.contact_idstring | nullCRM contact who made the purchase, or null.subject_typestringWhat kind of sale this is.subject_idstringYour reference for the sale (an invoice id, order number and so on).subject_referencestring | nullThe reference you sent with the sale (subject_reference), otherwise the quote or invoice number when the sale is a SoftSolz quote or invoice, otherwise null.subject_link_validbooleanTrue when the sale matches a real quote or invoice in this workspace, so it can be linked to. False for a reference that is only text.subject_record_idstring | nullId of the matching quote or invoice when subject_link_valid is true, or null.sale_amount_centsintegerSale value in minor units.commission_centsintegerCommission earned, in minor units of the partner currency.currencystringCurrency the commission is paid in (the partner currency).sale_currencystringCurrency the sale was made in.period_indexintegerBilling period of a recurring sale. 0 is the first sale.rate_snapshotobject | nullThe commission rate that applied when the sale was credited.statusstringWhere the commission is in its life: pending, approved, paid, rejected or reversed.hold_untilstring | nullCommission cannot be paid before this time (the refund window), or null.reversed_atstring | nullWhen the commission was clawed back, or null.reversal_reasonstring | nullWhy the commission was clawed back, or null.payout_item_idstring | nullPayout line this commission is being paid on, or null.approved_atstring | nullWhen the commission was approved, or null.paid_atstring | nullWhen the commission was paid, or null.created_atstringWhen the sale was credited.already_recordedbooleanPresent and true when this sale was already credited, so nothing new was saved.recordedbooleanPresent and false when nothing was saved for this recurring period.reasonstringWhy nothing was saved: the partner earns on no more recurring periods.Request
curl --request POST \ --url https://app.softsolz.uk/api/v1/services/affiliates/affiliates/commissions \ --header 'Authorization: Bearer sk_live_your_key' \ --header 'Content-Type: application/json' \ --data '{ "code": "ACMEMEDIA", "subject_type": "invoice", "subject_id": "INV-1042", "sale_amount_cents": 250000, "sale_currency": "GBP"}'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": "305", "affiliate_id": "12", "affiliate_name": "Acme Media", "contact_id": null, "subject_type": "invoice", "subject_id": "INV-1042", "subject_reference": "Paper invoice 7", "subject_link_valid": false, "subject_record_id": null, "sale_amount_cents": 250000, "commission_cents": 37500, "currency": "GBP", "sale_currency": "GBP", "period_index": 0, "rate_snapshot": { "commission_type": "percent", "commission_percent": "15.000", "commission_amount_cents": null, "from": "affiliate", "tier_id": null }, "status": "pending", "hold_until": "2026-10-31T10:15:00.000Z", "reversed_at": null, "reversal_reason": null, "payout_item_id": null, "approved_at": null, "paid_at": null, "created_at": "2026-10-01T10:15:00.000Z", "already_recorded": true, "recorded": false, "reason": "recurring_exhausted" }}