affiliates

Stable. Describes behaviour that is built and covered by tests in this repository.

GET `/v1/affiliates/program` #

The partner program of this environment

One program per environment, so the sandbox and live have their own. 404 with the key affiliate.program.not_set before one is set.

Responses

Status	Meaning	Body
`200`	OK	AffiliateProgram
`404`	Error envelope	Error

Example response

{
  "status": "draft",
  "commission_kind": "percent_bps",
  "commission_value": "string",
  "currency": "string",
  "commission_term": "first_invoices",
  "commission_term_value": 1,
  "attribution_window_days": 30,
  "hold_days": 0,
  "min_payout_minor": "string",
  "referred_coupon_code": "string",
  "daily_click_cap": 1000,
  "landing_url": "string",
  "auto_approve": false,
  "create_time": "2026-11-03T10:15:00Z",
  "update_time": "2026-11-03T10:15:00Z"
}

curl

curl -X GET https://YOUR-API-ADDRESS/v1/affiliates/program \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

PUT `/v1/affiliates/program` #

Set the rules of the partner program

Replaces the program. A change applies to commissions earned from then on, never to those already earned. A commission is a share of the net, pre-tax amount of a paid invoice (percent_bps) or a fixed amount in one currency (fixed, earned only on invoices in that currency).

Request body

Field	Type	Description
`status`	`draft` \| `active` \| `paused`	paused and draft earn nothing and turn the links off
`commission_kind` required	`percent_bps` \| `fixed`
`commission_value` required	string	Basis points of the net, pre-tax amount paid (1000 is 10 %), or minor units of currency for fixed
`currency`	string	Only for fixed; a percentage follows the currency of each invoice
`commission_term`	`first_invoices` \| `months` \| `lifetime`
`commission_term_value`	integer	N invoices or N months; absent for lifetime
`attribution_window_days`	integer
`hold_days`	integer	How long a commission waits (the refund window) before it can be paid
`min_payout_minor`	string · int64
`referred_coupon_code`	string	Coupon a referred customer gets on their next checkout
`daily_click_cap`	integer
`landing_url`	string	Where /r/<code> sends the visitor; empty shows a plain page. A public http(s) address: a host name (not an IP address, localhost or a name without a dot), no user name or password
`auto_approve`	boolean	A partner who applies is active at once
`create_time`	string · date-time
`update_time`	string · date-time

Example

{
  "commission_kind": "percent_bps",
  "commission_value": "string"
}

Responses

Status	Meaning	Body
`200`	OK	AffiliateProgram
`400`	Error envelope	Error
`404`	Error envelope	Error

Example response

{
  "status": "draft",
  "commission_kind": "percent_bps",
  "commission_value": "string",
  "currency": "string",
  "commission_term": "first_invoices",
  "commission_term_value": 1,
  "attribution_window_days": 30,
  "hold_days": 0,
  "min_payout_minor": "string",
  "referred_coupon_code": "string",
  "daily_click_cap": 1000,
  "landing_url": "string",
  "auto_approve": false,
  "create_time": "2026-11-03T10:15:00Z",
  "update_time": "2026-11-03T10:15:00Z"
}

curl

curl -X PUT https://YOUR-API-ADDRESS/v1/affiliates/program \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"commission_kind":"percent_bps","commission_value":"string"}'

GET `/v1/affiliates` #

Partners, newest first

Parameters

Name	In	Type	Description
`status`	query	`pending` \| `active` \| `suspended`
`search`	query	string	Part of the code, e-mail address or name
`page_size`	query	integer
`page_token`	query	string

Responses

Status	Meaning	Body
`200`	OK	ListAffiliatesResponse
`400`	Error envelope	Error

Example response

{
  "affiliates": [
    {
      "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "code": "string",
      "email": "string",
      "name": "string",
      "status": "pending",
      "payout_method": "manual",
      "payout_details": "string",
      "source": "owner",
      "signed_in": false,
      "clicks": "string",
      "referrals": "string",
      "approve_time": "2026-11-03T10:15:00Z",
      "create_time": "2026-11-03T10:15:00Z",
      "link": "string"
    }
  ],
  "next_page_token": "string",
  "total": 1
}

curl

curl -X GET https://YOUR-API-ADDRESS/v1/affiliates \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

POST `/v1/affiliates` #

Add a partner

The code (3 to 32 letters, numbers, - or _) is unique across the whole platform because the public link /r/ carries no tenant; leave it out for a random one. A partner you add is active unless you ask for pending.



Request body
Field Type Description
email required string · email 
name string 
code string 
payout_method manual | bank_transfer 
payout_details string 
pending boolean 
Example
{
  "email": "string"
}
Responses
Status Meaning Body
201 Created Affiliate
400 Error envelope Error
409 Error envelope Error
Example response
{
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "code": "string",
  "email": "string",
  "name": "string",
  "status": "pending",
  "payout_method": "manual",
  "payout_details": "string",
  "source": "owner",
  "signed_in": false,
  "clicks": "string",
  "referrals": "string",
  "approve_time": "2026-11-03T10:15:00Z",
  "create_time": "2026-11-03T10:15:00Z",
  "link": "string"
}
curl
curl -X POST https://YOUR-API-ADDRESS/v1/affiliates \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"string"}'

Field	Type	Description
`email` required	string · email
`name`	string
`code`	string
`payout_method`	`manual` \| `bank_transfer`
`payout_details`	string
`pending`	boolean

Status	Meaning	Body
`201`	Created	Affiliate
`400`	Error envelope	Error
`409`	Error envelope	Error


GET /v1/affiliates/referrals #
The customers partners brought, newest first
The customer's e-mail address is masked (j***@example.com).

Parameters
Name In Type Description
affiliate_id query string · uuid Only this partner's
page_size query integer 
page_token query string 

Responses
Status Meaning Body
200 OK ListAffiliateReferralsResponse
400 Error envelope Error
Example response
{
  "referrals": [
    {
      "affiliate_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "affiliate_code": "string",
      "customer_external_id": "string",
      "customer_email_masked": "string",
      "source": "link",
      "attribute_time": "2026-11-03T10:15:00Z"
    }
  ],
  "next_page_token": "string",
  "total": 1
}
curl
curl -X GET https://YOUR-API-ADDRESS/v1/affiliates/referrals \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

Name	In	Type	Description
`affiliate_id`	query	string · uuid	Only this partner's
`page_size`	query	integer
`page_token`	query	string

Status	Meaning	Body
`200`	OK	ListAffiliateReferralsResponse
`400`	Error envelope	Error


GET /v1/affiliates/commissions #
Commissions and the reversal rows that net against them, newest first
One commission per paid invoice of a customer a partner brought, in the invoice's currency, on the net, pre-tax amount paid. It is pending for the program's hold (the refund window), then approved, then paid by a payout. A refund, void or credit note takes it back (reversed_minor); one already paid is netted by a negative row of kind reversal that the next payout takes.

Parameters
Name In Type Description
affiliate_id query string · uuid 
status query pending | approved | paid | reversed 
kind query commission | reversal 
invoice_id query string · uuid 
payout_id query string · uuid 
from query string · date-time Earned at or after
to query string · date-time Earned before
page_size query integer 
page_token query string 

Responses
Status Meaning Body
200 OK ListAffiliateCommissionsResponse
400 Error envelope Error
Example response
{
  "commissions": [
    {
      "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "affiliate_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "affiliate_code": "string",
      "customer_external_id": "string",
      "kind": "commission",
      "invoice_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "invoice_number": "string",
      "currency": "string",
      "invoice_total_minor": "string",
      "net_minor": "string",
      "amount_minor": "string",
      "reversed_minor": "string",
      "status": "pending",
      "parent_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "earn_time": "2026-11-03T10:15:00Z",
      "approve_after_time": "2026-11-03T10:15:00Z",
      "approve_time": "2026-11-03T10:15:00Z",
      "pay_time": "2026-11-03T10:15:00Z",
      "payout_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e"
    }
  ],
  "next_page_token": "string",
  "total": 1
}
curl
curl -X GET https://YOUR-API-ADDRESS/v1/affiliates/commissions \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

Name	In	Type	Description
`affiliate_id`	query	string · uuid
`status`	query	`pending` \| `approved` \| `paid` \| `reversed`
`kind`	query	`commission` \| `reversal`
`invoice_id`	query	string · uuid
`payout_id`	query	string · uuid
`from`	query	string · date-time	Earned at or after
`to`	query	string · date-time	Earned before
`page_size`	query	integer
`page_token`	query	string

Status	Meaning	Body
`200`	OK	ListAffiliateCommissionsResponse
`400`	Error envelope	Error


POST /v1/affiliates/commissions/reverse #
Take a commission back for a chargeback, or by hand
Refunds, voids and credit notes reverse on their own. The same (invoice, reason, reference) takes back once. A commission that was paid is netted from the partner's next payout.


Request body
Field Type Description
invoice_id required string · uuid 
reason required chargeback | manual 
reference string Names this reversal; required for manual
amount_minor string · int64 How much to take back; 0 or absent is all that is left
note string 
Example
{
  "invoice_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "reason": "chargeback"
}
Responses
Status Meaning Body
200 OK ReverseAffiliateCommissionResponse
400 Error envelope Error
404 Error envelope Error
Example response
{
  "reversed_minor": "string",
  "commission": {
    "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
    "affiliate_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
    "affiliate_code": "string",
    "customer_external_id": "string",
    "kind": "commission",
    "invoice_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
    "invoice_number": "string",
    "currency": "string",
    "invoice_total_minor": "string",
    "net_minor": "string",
    "amount_minor": "string",
    "reversed_minor": "string",
    "status": "pending",
    "parent_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
    "earn_time": "2026-11-03T10:15:00Z",
    "approve_after_time": "2026-11-03T10:15:00Z",
    "approve_time": "2026-11-03T10:15:00Z",
    "pay_time": "2026-11-03T10:15:00Z",
    "payout_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e"
  }
}
curl
curl -X POST https://YOUR-API-ADDRESS/v1/affiliates/commissions/reverse \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice_id":"0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e","reason":"chargeback"}'

Field	Type	Description
`invoice_id` required	string · uuid
`reason` required	`chargeback` \| `manual`
`reference`	string	Names this reversal; required for manual
`amount_minor`	string · int64	How much to take back; 0 or absent is all that is left
`note`	string

Status	Meaning	Body
`200`	OK	ReverseAffiliateCommissionResponse
`400`	Error envelope	Error
`404`	Error envelope	Error


GET /v1/affiliates/balances #
What each partner has, per currency
pending (in the hold), approved (available for a payout, net of reversals), paid (paid out, net of what was netted) and reversed (taken back in all). Currencies are never added together.

Parameters
Name In Type Description
affiliate_id query string · uuid 

Responses
Status Meaning Body
200 OK GetAffiliateBalancesResponse
400 Error envelope Error
Example response
{
  "balances": [
    {
      "affiliate_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "currency": "string",
      "pending_minor": "string",
      "approved_minor": "string",
      "paid_minor": "string",
      "reversed_minor": "string"
    }
  ]
}
curl
curl -X GET https://YOUR-API-ADDRESS/v1/affiliates/balances \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

Name	In	Type	Description
`affiliate_id`	query	string · uuid

Status	Meaning	Body
`200`	OK	GetAffiliateBalancesResponse
`400`	Error envelope	Error


GET /v1/affiliates/funnel #
Clicks, referred customers, paying customers and commissions over a period

Parameters
Name In Type Description
from query string · date First day, UTC; default 30 days before to
to query string · date Last day, UTC; default today
affiliate_id query string · uuid 

Responses
Status Meaning Body
200 OK AffiliateFunnel
400 Error envelope Error
Example response
{
  "from_date": "string",
  "to_date": "string",
  "clicks": "string",
  "referrals": "string",
  "paying_customers": "string",
  "commissions": [
    {
      "currency": "string",
      "earned_minor": "string",
      "reversed_minor": "string"
    }
  ]
}
curl
curl -X GET https://YOUR-API-ADDRESS/v1/affiliates/funnel \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

Name	In	Type	Description
`from`	query	string · date	First day, UTC; default 30 days before to
`to`	query	string · date	Last day, UTC; default today
`affiliate_id`	query	string · uuid

Status	Meaning	Body
`200`	OK	AffiliateFunnel
`400`	Error envelope	Error


GET /v1/affiliates/payouts #
Payouts to partners, newest first
A payout is the approved commissions of one partner in one currency (no conversion), with the negative rows that net earlier payments taken back. An open payout is worth what its commissions are worth now.

Parameters
Name In Type Description
affiliate_id query string · uuid 
status query open | paid | cancelled 
page_size query integer 
page_token query string 

Responses
Status Meaning Body
200 OK ListAffiliatePayoutsResponse
400 Error envelope Error
Example response
{
  "payouts": [
    {
      "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "affiliate_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "affiliate_code": "string",
      "currency": "string",
      "total_minor": "string",
      "commission_count": 1,
      "method": "manual",
      "payout_details": "string",
      "reference": "string",
      "status": "open",
      "fake": false,
      "create_time": "2026-11-03T10:15:00Z",
      "pay_time": "2026-11-03T10:15:00Z",
      "cancel_time": "2026-11-03T10:15:00Z"
    }
  ],
  "next_page_token": "string",
  "total": 1
}
curl
curl -X GET https://YOUR-API-ADDRESS/v1/affiliates/payouts \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

Name	In	Type
`affiliate_id`	query	string · uuid
`status`	query	`open` \| `paid` \| `cancelled`
`page_size`	query	integer
`page_token`	query	string

Status	Meaning	Body
`200`	OK	ListAffiliatePayoutsResponse
`400`	Error envelope	Error


POST /v1/affiliates/payouts #
Batch the approved commissions into open payouts
For one partner or for every active partner, one payout per currency. A batch below the program's minimum payout, or not above zero, is skipped and reported; what is approved later joins a payout that is still open. A suspended partner is not paid; their balance is kept. A live environment that is not active pays nobody (affiliate.payout.tenant_not_active).


Request body
Field Type Description
affiliate_id string · uuid 
currency string 
Example
{}
Responses
Status Meaning Body
201 Created CreateAffiliatePayoutsResponse
400 Error envelope Error
404 Error envelope Error
409 Error envelope Error
Example response
{
  "payouts": [
    {
      "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "affiliate_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "affiliate_code": "string",
      "currency": "string",
      "total_minor": "string",
      "commission_count": 1,
      "method": "manual",
      "payout_details": "string",
      "reference": "string",
      "status": "open",
      "fake": false,
      "create_time": "2026-11-03T10:15:00Z",
      "pay_time": "2026-11-03T10:15:00Z",
      "cancel_time": "2026-11-03T10:15:00Z"
    }
  ],
  "skipped": [
    {
      "affiliate_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "currency": "string",
      "total_minor": "string",
      "reason": "below_minimum"
    }
  ]
}
curl
curl -X POST https://YOUR-API-ADDRESS/v1/affiliates/payouts \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Field	Type	Description
`affiliate_id`	string · uuid
`currency`	string

Status	Meaning	Body
`201`	Created	CreateAffiliatePayoutsResponse
`400`	Error envelope	Error
`404`	Error envelope	Error
`409`	Error envelope	Error


POST /v1/affiliates/payouts/{id}/pay #
Record that you paid a payout, and post it
Payrudder moves no money: pay by hand or bank transfer, then say so. The commissions become paid and the journal gets the commission expense against the payable, and the payable against cash, balanced in the payout's currency. Doing it again changes nothing. In the sandbox the payout is fake and its postings say so.

Parameters
Name In Type Description
id required path string · uuid 
Request body
Field Type Description
reference string Your note, e.g. the bank transfer reference
Example
{}
Responses
Status Meaning Body
200 OK AffiliatePayout
404 Error envelope Error
409 Error envelope Error
Example response
{
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "affiliate_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "affiliate_code": "string",
  "currency": "string",
  "total_minor": "string",
  "commission_count": 1,
  "method": "manual",
  "payout_details": "string",
  "reference": "string",
  "status": "open",
  "fake": false,
  "create_time": "2026-11-03T10:15:00Z",
  "pay_time": "2026-11-03T10:15:00Z",
  "cancel_time": "2026-11-03T10:15:00Z"
}
curl
curl -X POST https://YOUR-API-ADDRESS/v1/affiliates/payouts/<id>/pay \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Name	In	Type	Description
`id` required	path	string · uuid

Field	Type	Description
`reference`	string	Your note, e.g. the bank transfer reference

Status	Meaning	Body
`200`	OK	AffiliatePayout
`404`	Error envelope	Error
`409`	Error envelope	Error


POST /v1/affiliates/payouts/{id}/cancel #
Drop an open payout
Its commissions go back to being payable in another payout.

Parameters
Name In Type Description
id required path string · uuid 

Responses
Status Meaning Body
200 OK AffiliatePayout
404 Error envelope Error
409 Error envelope Error
Example response
{
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "affiliate_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "affiliate_code": "string",
  "currency": "string",
  "total_minor": "string",
  "commission_count": 1,
  "method": "manual",
  "payout_details": "string",
  "reference": "string",
  "status": "open",
  "fake": false,
  "create_time": "2026-11-03T10:15:00Z",
  "pay_time": "2026-11-03T10:15:00Z",
  "cancel_time": "2026-11-03T10:15:00Z"
}
curl
curl -X POST https://YOUR-API-ADDRESS/v1/affiliates/payouts/<id>/cancel \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

Name	In	Type	Description
`id` required	path	string · uuid

Status	Meaning	Body
`200`	OK	AffiliatePayout
`404`	Error envelope	Error
`409`	Error envelope	Error


GET /v1/affiliates/journal #
The postings of paid payouts, with debit and credit totals per currency
totals cover the whole filter, not only the page. The books balance when debits equal credits in every currency; the database refuses to commit postings that do not.

Parameters
Name In Type Description
payout_id query string · uuid 
currency query string 
from query string · date-time 
to query string · date-time 
page_size query integer 
page_token query string 

Responses
Status Meaning Body
200 OK ListAffiliateJournalResponse
400 Error envelope Error
Example response
{
  "entries": [
    {
      "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "payout_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "affiliate_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "post_time": "2026-11-03T10:15:00Z",
      "currency": "string",
      "account": "commission_expense",
      "debit_minor": "string",
      "credit_minor": "string",
      "memo": "string",
      "fake": false
    }
  ],
  "totals": [
    {
      "currency": "string",
      "debit_minor": "string",
      "credit_minor": "string"
    }
  ],
  "next_page_token": "string",
  "total": 1
}
curl
curl -X GET https://YOUR-API-ADDRESS/v1/affiliates/journal \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

Name	In	Type
`payout_id`	query	string · uuid
`currency`	query	string
`from`	query	string · date-time
`to`	query	string · date-time
`page_size`	query	integer
`page_token`	query	string

Status	Meaning	Body
`200`	OK	ListAffiliateJournalResponse
`400`	Error envelope	Error


GET /v1/affiliates/journal.csv #
The same postings as a CSV file, with a total line per currency

Parameters
Name In Type Description
payout_id query string · uuid 
currency query string 
from query string · date-time 
to query string · date-time 

Responses
Status Meaning Body
200 OK 
400 Error envelope Error

curl
curl -X GET https://YOUR-API-ADDRESS/v1/affiliates/journal.csv \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

Name	In	Type
`payout_id`	query	string · uuid
`currency`	query	string
`from`	query	string · date-time
`to`	query	string · date-time

Status	Meaning	Body
`200`	OK
`400`	Error envelope	Error


GET /v1/affiliates/{id} #
One partner with their click and referral counts

Parameters
Name In Type Description
id required path string · uuid 

Responses
Status Meaning Body
200 OK Affiliate
404 Error envelope Error
Example response
{
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "code": "string",
  "email": "string",
  "name": "string",
  "status": "pending",
  "payout_method": "manual",
  "payout_details": "string",
  "source": "owner",
  "signed_in": false,
  "clicks": "string",
  "referrals": "string",
  "approve_time": "2026-11-03T10:15:00Z",
  "create_time": "2026-11-03T10:15:00Z",
  "link": "string"
}
curl
curl -X GET https://YOUR-API-ADDRESS/v1/affiliates/<id> \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

Name	In	Type	Description
`id` required	path	string · uuid

Status	Meaning	Body
`200`	OK	Affiliate
`404`	Error envelope	Error


PATCH /v1/affiliates/{id} #
Change a partner's name, payout details or status
status active approves a pending partner or reinstates a suspended one; suspended stops new attributions and commissions but keeps what was approved. Nothing returns to pending.

Parameters
Name In Type Description
id required path string · uuid 
Request body
Field Type Description
name string 
payout_method manual | bank_transfer 
payout_details string 
status active | suspended 
Example
{}
Responses
Status Meaning Body
200 OK Affiliate
400 Error envelope Error
404 Error envelope Error
Example response
{
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "code": "string",
  "email": "string",
  "name": "string",
  "status": "pending",
  "payout_method": "manual",
  "payout_details": "string",
  "source": "owner",
  "signed_in": false,
  "clicks": "string",
  "referrals": "string",
  "approve_time": "2026-11-03T10:15:00Z",
  "create_time": "2026-11-03T10:15:00Z",
  "link": "string"
}
curl
curl -X PATCH https://YOUR-API-ADDRESS/v1/affiliates/<id> \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Name	In	Type	Description
`id` required	path	string · uuid

Field	Type	Description
`name`	string
`payout_method`	`manual` \| `bank_transfer`
`payout_details`	string
`status`	`active` \| `suspended`

Status	Meaning	Body
`200`	OK	Affiliate
`400`	Error envelope	Error
`404`	Error envelope	Error


PUT /v1/affiliates/{id}/promotion-code #
Make a promotion code the partner's
A customer who redeems the code at a checkout is attributed to the partner, as if they had followed the link.

Parameters
Name In Type Description
id required path string · uuid 
Request body
Field Type Description
promotion_code required string 
Example
{
  "promotion_code": "string"
}
Responses
Status Meaning Body
200 OK Affiliate
404 Error envelope Error
Example response
{
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "code": "string",
  "email": "string",
  "name": "string",
  "status": "pending",
  "payout_method": "manual",
  "payout_details": "string",
  "source": "owner",
  "signed_in": false,
  "clicks": "string",
  "referrals": "string",
  "approve_time": "2026-11-03T10:15:00Z",
  "create_time": "2026-11-03T10:15:00Z",
  "link": "string"
}
curl
curl -X PUT https://YOUR-API-ADDRESS/v1/affiliates/<id>/promotion-code \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"promotion_code":"string"}'

Name	In	Type	Description
`id` required	path	string · uuid

Field	Type	Description
`promotion_code` required	string

Status	Meaning	Body
`200`	OK	Affiliate
`404`	Error envelope	Error


Models
Affiliate
Field Type Description
id required string · uuid 
code required string 
email required string 
name required string 
status required pending | active | suspended 
payout_method required manual | bank_transfer 
payout_details required string 
source required owner | application 
signed_in required boolean The partner has signed in and claimed this affiliate
clicks required string · int64 
referrals required string · int64 
approve_time required string · date-time 
create_time required string · date-time 
link required string The partner's public referral link, https://<gateway>/r/<code>
AffiliateBalance
Field Type Description
affiliate_id required string · uuid 
currency required string 
pending_minor required string · int64 
approved_minor required string · int64 
paid_minor required string · int64 
reversed_minor required string · int64 
AffiliateCommission
Field Type Description
id required string · uuid 
affiliate_id required string · uuid 
affiliate_code required string 
customer_external_id required string 
kind required commission | reversal 
invoice_id required string · uuid 
invoice_number required string 
currency required string 
invoice_total_minor required string · int64 What the invoice came to, tax included
net_minor required string · int64 The base: the net, pre-tax amount actually paid
amount_minor required string · int64 The commission; negative on a reversal row
reversed_minor required string How much of the commission has been taken back, format: int64
status required pending | approved | paid | reversed 
parent_id required string · uuid 
earn_time required string · date-time 
approve_after_time required string · date-time 
approve_time required string · date-time 
pay_time required string · date-time 
payout_id required string · uuid 
AffiliateFunnel
Field Type Description
from_date required string · date 
to_date required string · date 
clicks required string · int64 
referrals required string Customers attributed in the period, format: int64
paying_customers required string Customers with a commission earned in the period, format: int64
commissions required array of object 
AffiliateJournalEntry
Field Type Description
id required string · uuid 
payout_id required string · uuid 
affiliate_id required string · uuid 
post_time required string · date-time 
currency required string 
account required commission_expense | commissions_payable | cash 
debit_minor required string · int64 
credit_minor required string · int64 
memo required string 
fake required boolean 
AffiliatePayout
Field Type Description
id required string · uuid 
affiliate_id required string · uuid 
affiliate_code required string 
currency required string 
total_minor required string · int64 Open: what its commissions are worth now. Paid: what was paid
commission_count required integer 
method required manual | bank_transfer 
payout_details required string 
reference required string 
status required open | paid | cancelled 
fake required boolean A payout of a sandbox environment: nothing was or will be paid
create_time required string · date-time 
pay_time required string · date-time 
cancel_time required string · date-time 
AffiliateProgram
Field Type Description
status required draft | active | paused paused and draft earn nothing and turn the links off
commission_kind required percent_bps | fixed 
commission_value required string · int64 Basis points of the net, pre-tax amount paid (1000 is 10 %), or minor units of currency for fixed
currency required string Only for fixed; a percentage follows the currency of each invoice
commission_term required first_invoices | months | lifetime 
commission_term_value required integer N invoices or N months; absent for lifetime
attribution_window_days required integer 
hold_days required integer How long a commission waits (the refund window) before it can be paid
min_payout_minor required string · int64 
referred_coupon_code required string Coupon a referred customer gets on their next checkout
daily_click_cap required integer 
landing_url required string Where /r/<code> sends the visitor; empty shows a plain page. A public http(s) address: a host name (not an IP address, localhost or a name without a dot), no user name or password
auto_approve required boolean A partner who applies is active at once
create_time required string · date-time 
update_time required string · date-time 
AffiliateProgramInput
Field Type Description
status draft | active | paused paused and draft earn nothing and turn the links off
commission_kind required percent_bps | fixed 
commission_value required string Basis points of the net, pre-tax amount paid (1000 is 10 %), or minor units of currency for fixed
currency string Only for fixed; a percentage follows the currency of each invoice
commission_term first_invoices | months | lifetime 
commission_term_value integer N invoices or N months; absent for lifetime
attribution_window_days integer 
hold_days integer How long a commission waits (the refund window) before it can be paid
min_payout_minor string · int64 
referred_coupon_code string Coupon a referred customer gets on their next checkout
daily_click_cap integer 
landing_url string Where /r/<code> sends the visitor; empty shows a plain page. A public http(s) address: a host name (not an IP address, localhost or a name without a dot), no user name or password
auto_approve boolean A partner who applies is active at once
create_time string · date-time 
update_time string · date-time 
AffiliateReferral
Field Type Description
affiliate_id required string · uuid 
affiliate_code required string 
customer_external_id required string 
customer_email_masked required string 
source required link | code | api 
attribute_time required string · date-time 
CreateAffiliatePayoutsRequest
Field Type Description
affiliate_id string · uuid 
currency string 
CreateAffiliatePayoutsResponse
Field Type Description
payouts required array of AffiliatePayout 
skipped required array of CreateAffiliatePayoutsSkipped 
CreateAffiliatePayoutsSkipped
Field Type Description
affiliate_id required string · uuid 
currency required string 
total_minor required string · int64 
reason required below_minimum | not_positive 
CreateAffiliateRequest
Field Type Description
email required string · email 
name string 
code string 
payout_method manual | bank_transfer 
payout_details string 
pending boolean 
Error
Field Type Description
error required object 
GetAffiliateBalancesResponse
Field Type Description
balances required array of AffiliateBalance 
LinkAffiliatePromotionCodeRequest
Field Type Description
promotion_code required string 
ListAffiliateCommissionsResponse
Field Type Description
commissions required array of AffiliateCommission 
next_page_token required string 
total required integer 
ListAffiliateJournalResponse
Field Type Description
entries required array of AffiliateJournalEntry 
totals required array of ListAffiliateJournalTotal 
next_page_token required string 
total required integer 
ListAffiliateJournalTotal
Field Type Description
currency required string 
debit_minor required string · int64 
credit_minor required string · int64 
ListAffiliatePayoutsResponse
Field Type Description
payouts required array of AffiliatePayout 
next_page_token required string 
total required integer 
ListAffiliateReferralsResponse
Field Type Description
referrals required array of AffiliateReferral 
next_page_token required string 
total required integer 
ListAffiliatesResponse
Field Type Description
affiliates required array of Affiliate 
next_page_token required string 
total required integer 
MarkAffiliatePayoutPaidRequest
Field Type Description
reference string Your note, e.g. the bank transfer reference
ReverseAffiliateCommissionRequest
Field Type Description
invoice_id required string · uuid 
reason required chargeback | manual 
reference string Names this reversal; required for manual
amount_minor string · int64 How much to take back; 0 or absent is all that is left
note string 
ReverseAffiliateCommissionResponse
Field Type Description
reversed_minor required string · int64 How much this call took back; 0 on a repeat
commission required any 
UpdateAffiliateRequest
Field Type Description
name string 
payout_method manual | bank_transfer 
payout_details string 
status active | suspended

Field	Type	Description
`id` required	string · uuid
`code` required	string
`email` required	string
`name` required	string
`status` required	`pending` \| `active` \| `suspended`
`payout_method` required	`manual` \| `bank_transfer`
`payout_details` required	string
`source` required	`owner` \| `application`
`signed_in` required	boolean	The partner has signed in and claimed this affiliate
`clicks` required	string · int64
`referrals` required	string · int64
`approve_time` required	string · date-time
`create_time` required	string · date-time
`link` required	string	The partner's public referral link, https://<gateway>/r/<code>

Field	Type	Description
`affiliate_id` required	string · uuid
`currency` required	string
`pending_minor` required	string · int64
`approved_minor` required	string · int64
`paid_minor` required	string · int64
`reversed_minor` required	string · int64

Field	Type	Description
`from_date` required	string · date
`to_date` required	string · date
`clicks` required	string · int64
`referrals` required	string	Customers attributed in the period, format: int64
`paying_customers` required	string	Customers with a commission earned in the period, format: int64
`commissions` required	array of object

Field	Type	Description
`id` required	string · uuid
`payout_id` required	string · uuid
`affiliate_id` required	string · uuid
`post_time` required	string · date-time
`currency` required	string
`account` required	`commission_expense` \| `commissions_payable` \| `cash`
`debit_minor` required	string · int64
`credit_minor` required	string · int64
`memo` required	string
`fake` required	boolean

Field	Type	Description
`affiliate_id` required	string · uuid
`affiliate_code` required	string
`customer_external_id` required	string
`customer_email_masked` required	string
`source` required	`link` \| `code` \| `api`
`attribute_time` required	string · date-time

Field	Type	Description
`payouts` required	array of AffiliatePayout
`skipped` required	array of CreateAffiliatePayoutsSkipped

Field	Type	Description
`commissions` required	array of AffiliateCommission
`next_page_token` required	string
`total` required	integer

Field	Type	Description
`entries` required	array of AffiliateJournalEntry
`totals` required	array of ListAffiliateJournalTotal
`next_page_token` required	string
`total` required	integer

Field	Type	Description
`referrals` required	array of AffiliateReferral
`next_page_token` required	string
`total` required	integer

Field	Type	Description
`affiliates` required	array of Affiliate
`next_page_token` required	string
`total` required	integer

Field	Type	Description
`reversed_minor` required	string · int64	How much this call took back; 0 on a repeat
`commission` required	any

affiliates

GET /v1/affiliates/program #

Responses

PUT /v1/affiliates/program #

Request body

Responses

GET /v1/affiliates #

Parameters

Responses

POST /v1/affiliates #

Request body

Responses

GET /v1/affiliates/referrals #

Parameters

Responses

GET /v1/affiliates/commissions #

Parameters

Responses

POST /v1/affiliates/commissions/reverse #

Request body

Responses

GET /v1/affiliates/balances #

Parameters

Responses

GET /v1/affiliates/funnel #

Parameters

Responses

GET /v1/affiliates/payouts #

Parameters

Responses

POST /v1/affiliates/payouts #

Request body

Responses

POST /v1/affiliates/payouts/{id}/pay #

Parameters

Request body

Responses

POST /v1/affiliates/payouts/{id}/cancel #

Parameters

Responses

GET /v1/affiliates/journal #

Parameters

Responses

GET /v1/affiliates/journal.csv #

Parameters

Responses

GET /v1/affiliates/{id} #

Parameters

Responses

PATCH /v1/affiliates/{id} #

Parameters

Request body

Responses

PUT /v1/affiliates/{id}/promotion-code #

Parameters

Request body

Responses

Models

Affiliate

AffiliateBalance

AffiliateCommission

AffiliateFunnel

AffiliateJournalEntry

AffiliatePayout

AffiliateProgram

AffiliateProgramInput

AffiliateReferral

CreateAffiliatePayoutsRequest

CreateAffiliatePayoutsResponse

CreateAffiliatePayoutsSkipped

CreateAffiliateRequest

Error

GetAffiliateBalancesResponse

LinkAffiliatePromotionCodeRequest

ListAffiliateCommissionsResponse

ListAffiliateJournalResponse

ListAffiliateJournalTotal

ListAffiliatePayoutsResponse

ListAffiliateReferralsResponse

ListAffiliatesResponse

GET `/v1/affiliates/program` #

PUT `/v1/affiliates/program` #

GET `/v1/affiliates` #

POST `/v1/affiliates` #

GET `/v1/affiliates/referrals` #

GET `/v1/affiliates/commissions` #

POST `/v1/affiliates/commissions/reverse` #

GET `/v1/affiliates/balances` #

GET `/v1/affiliates/funnel` #

GET `/v1/affiliates/payouts` #

POST `/v1/affiliates/payouts` #

POST `/v1/affiliates/payouts/{id}/pay` #

POST `/v1/affiliates/payouts/{id}/cancel` #

GET `/v1/affiliates/journal` #

GET `/v1/affiliates/journal.csv` #

GET `/v1/affiliates/{id}` #

PATCH `/v1/affiliates/{id}` #

PUT `/v1/affiliates/{id}/promotion-code` #