List rewards
/v1/projects/{project}/referral-rewards in the Referral Program API.
curl "https://api.subscriby.net/v1/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/referral-rewards?affiliate_id=0b1c2d3e-4f50-4617-8a9b-0c1d2e3f4a5b&status=approved" \ -H "Authorization: Bearer sbt_..."Pages the ledger, newest first: one row per settled payment per side of a referral. affiliate_id, status (pending, approved, paid, applied, reversed) and beneficiary (referrer, friend) narrow it. A reversal is a row of its own with a negative amount and reverses_reward_id naming the reward it cancels. The ledger is read-only: rewards are written when a payment settles, made payable by the hold, paid by a recorded payout and reversed by a refund.
Requires ability
The token must hold this ability, or the call is refused with 403.
Run the same action from an agent, behind the same ability.
Authorization
bearerToken A personal access token minted on the dashboard under Settings, then Tokens, sent as Authorization: Bearer sbt_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team.
In: header
Path Parameters
The project, resolved by the route binder.
uuidQuery Parameters
Keep only the rewards one affiliate's referrals earned.
uuidKeep only rewards in this state: pending (inside the hold, or days waiting on the balance), approved (payable), paid (recorded in a payout), applied (days banked on a membership) or reversed (taken back by a refund).
Value in
- "pending"
- "approved"
- "paid"
- "reversed"
- "applied"
Keep only the rewards of one side: referrer or friend.
Value in
- "referrer"
- "friend"
The 1-based page to return. A page past the last answers an empty data array with meta.total still filled, so a loop can stop without guessing.
1 <= value1Rows per page, 1 to 100. A higher value clamps to the cap silently. Defaults to 25.
1 <= value <= 10025The column to order by. Defaults to created_at; a column the endpoint does not offer falls back to the default rather than failing.
"created_at"asc or desc. Defaults to desc.
"desc"Value in
- "asc"
- "desc"
Legacy alias of per_page, kept for clients that predate it. per_page wins when both are sent.
1 <= value <= 100Responses
200OKapplication/json
The page.
401UnauthorizedAUTHENTICATION_REQUIREDapplication/json
The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).
403ForbiddenTOKEN_MISSING_ABILITYapplication/json
The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers FORBIDDEN, TEAM_TIER_REQUIRED or CONNECTOR_TIER_REQUIRED with the same status, and says so in its own description.
404Not foundRESOURCE_NOT_FOUNDapplication/json
An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred.
422Validation failedVALIDATION_FAILEDapplication/json
The payload broke a rule, and error.fields maps each offending key to its messages. A refusal from the domain, such as a plan that cannot go on sale or a member who cannot be removed, uses the same code with error.message saying why and no fields.
429Too many requestsRATE_LIMITEDapplication/json
The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.
How is this guide?
Last updated on