Read the payout queues, pay a due billing window, and create manual payouts from your own tools or an agent.
The payouts API covers the same four queues as the Payouts page — upcoming, due, canceled and paid — plus the two ways money gets recorded: paying a due billing window that a campaign's rules produced, and a manual payout of an amount no rule produced, such as a one-off bonus or a correction.
The API reference has every field and API and automation covers keys and access; this page explains how the pieces fit.
Calculate what a campaign's rules produced for a finished billing window, then initiate the payout.
Pay a creator any amount outside campaign rules, such as a bonus or a correction, with an id that makes retries safe.
https://viral.app/api/v1 and takes the x-api-key header. Bodies and responses are JSON.orgpay_ payouts, orgcamp_ campaigns, orgcre_ creators. Billing windows are ISO timestamps with an offset, such as 2026-09-01T00:00:00.000Z.amount, line items — is in major units (150.5 is 150.50). Paid payouts also read back in major units. Due and upcoming rows report payoutAmount in minor units together with payoutPrecision.The four queues take campaignIds and creatorIds filters. On upcoming, due and paid, mode=totals returns per-currency sums instead of rows. Array filters are written creatorIds[0]=…, so pass -g to curl, which otherwise reads the brackets as a URL pattern.
curl -g "https://viral.app/api/v1/payouts/due?creatorIds[0]=orgcre_4TnXq8LwPz2A" \
-H "x-api-key: $VIRAL_APP_API_KEY"
A due row names its window: campaignId, creatorId, billingPeriodStart and billingPeriodEnd. Paying it takes two calls.
POST /payouts/calculate.POST /payouts/initiate, handing the calculation back.The examples use jq to pass JSON from one call to the next.
Send the four window fields exactly as the due row has them.
WINDOW=$(curl -g -s "https://viral.app/api/v1/payouts/due?creatorIds[0]=orgcre_4TnXq8LwPz2A" \
-H "x-api-key: $VIRAL_APP_API_KEY" |
jq '.data[0] | {campaignId, creatorId, billingPeriodStart, billingPeriodEnd}')
CALCULATION=$(curl -s -X POST https://viral.app/api/v1/payouts/calculate \
-H "x-api-key: $VIRAL_APP_API_KEY" \
-H "content-type: application/json" \
-d "$WINDOW")
The response is the calculation itself, with two fields on top: lineItems, the default invoice lines in major units, and integrityToken, which pins the calculation to this window. excludedVideos leaves videos out of the calculation; the API reference describes it.
Send the window again, the whole calculate response as calculation, its integrityToken, and the lineItems to invoice: the defaults, or your own when the amount needs adjusting. Do not edit the calculation, or the token no longer matches.
jq -n --argjson window "$WINDOW" --argjson calc "$CALCULATION" '$window + {
calculation: $calc,
integrityToken: $calc.integrityToken,
lineItems: $calc.lineItems,
payoutProvider: "talentir"
}' |
curl -s -X POST https://viral.app/api/v1/payouts/initiate \
-H "x-api-key: $VIRAL_APP_API_KEY" \
-H "content-type: application/json" \
-d @-
{ "success": true, "payoutId": "orgpay_RwmraAffhMt9", "providerPayoutId": "…" }
payoutProvider decides what the payout is. "manual", the default, records a payment you made outside viral.app. "talentir" creates a Talentir payout that waits for approval in the dashboard, as described in Approve payouts.
If the campaign's payout rules change between the two calls, initiate answers 409 CAMPAIGN_RULES_CHANGED — calculate again. A window that is already paid or canceled answers 409 PAYOUT_CONFLICT.
POST /payouts/cancel takes a due window out of the queue (the same four fields, optional reasonNote), and POST /payouts/cancel/reinstate puts it back. PATCH /payouts/{id} edits a recorded payout's reference and notes, nothing else.
A manual payout belongs to no billing window. It is paid in addition to whatever the creator's campaign produces and never settles a due window.
curl "https://viral.app/api/v1/payouts/manual/context?creatorId=orgcre_4TnXq8LwPz2A" \
-H "x-api-key: $VIRAL_APP_API_KEY"
{
"creator": {
"userId": "user_8dKq2mVxYb1N",
"name": "Anna Kowalski",
"email": "anna@example.com",
"image": null
},
"activeAssignment": {
"campaignId": "orgcamp_RwmraAffhMt9",
"campaignName": "US Creators",
"currency": "USD"
},
"hasDuePayouts": true,
"isMarketplaceCreator": false
}
You choose the payout's id: orgpay_ followed by 12 letters or digits. It is the idempotency key, so mint it once per payment and store it before you send the request.
PAYOUT_ID="orgpay_$(LC_ALL=C tr -dc 'A-Za-z0-9' </dev/urandom | head -c 12)"
curl -X POST https://viral.app/api/v1/payouts/manual \
-H "x-api-key: $VIRAL_APP_API_KEY" \
-H "content-type: application/json" \
-d '{
"id": "'"$PAYOUT_ID"'",
"creatorId": "orgcre_4TnXq8LwPz2A",
"campaignId": "orgcamp_RwmraAffhMt9",
"amount": 150.5,
"currency": "USD",
"description": "Bonus for the September launch video",
"reference": "INV-2026-0918",
"payoutProvider": "talentir"
}'
{ "success": true, "payoutId": "orgpay_XZIRbEsLkuc9", "providerPayoutId": "…" }
"manual": the payout is recorded as paid at once. The creator sees "Payout sent" in their chat with your team and receives the payout email."talentir": the payout waits in the Paid tab until a member of your Talentir team approves it there, as described in Approve payouts. The creator hears nothing until then; after approval they get the claim email and "Payout ready to claim" in the chat. providerPayoutId is the Talentir payout's id.Send the same request again whenever a response got lost. The same id with the same creator, amount, currency, campaign and provider returns the original result and pays nothing twice. The same id with different details answers 409 PAYOUT_ID_CONFLICT — mint a new id for a new payment.
Approving Talentir payouts, reissuing an expired one, canceling a payout that awaits approval, and copying or re-sending a claim link are dashboard actions and not part of the API. Use the Paid tab for them.