Payouts via the API

The payouts API covers the same four queues as the Payouts page: upcoming, due, canceled and paid. It also covers every way money gets recorded:

• a billing window that a campaign's rules produced, paid in full once it is due, or early while it still runs: part of it now with the rest following, or all of it today together with the creator's assignment
• specific videos at terms of their own, for deals that differ per creator or per video
• 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.

Before you start

• Base URL and auth: every route below lives under https://viral.app/api/v1 and takes the x-api-key header. Bodies and responses are JSON.
• Who can do what: initiating, canceling, reinstating, annotating and creating payouts need a key of an owner, admin or member. The queues, the calculation and the manual payout preflight also work for a viewer's key. Writes land in the workspace's activity log under the key's owner.
• Ids carry their type: orgpay_ payouts, orgcamp_ campaigns, orgcre_ creators. Billing windows are ISO timestamps with an offset, such as 2026-09-01T00:00:00.000Z.
• Amounts: what you send (a manual payout's amount, line items) is in major units, so 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.

Read the payout queues

On upcoming and due rows, payoutAmount is what the window still has to pay. Once partial payments were made toward it, partialsPaid reports their count, the amount they paid, the coveredAmount of earnings they covered (their amount without adjustments, what payoutAmount deducts) and the window's calculatedAmount before it was subtracted.

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"

Pay a due billing window

A due row names its window: campaignId, creatorId, billingPeriodStart and billingPeriodEnd. Paying it takes two calls.

1. Calculate the window with POST /payouts/calculate.
2. Initiate the payout with POST /payouts/initiate, handing the calculation back.

The examples use jq to pass JSON from one call to the next.

1. Calculate

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, or with ruleIds out of those rules only (each breakdown row lists the ruleIds it sums); the API reference describes it.

2. Initiate

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.

A line item may also be an adjustment: { "title": "Withholding", "amount": -12.5, "kind": "adjustment", "percent": -12.5 } deducts a percentage of the payout's base, and a positive percent adds one. The base is the earnings the payout covers: the positive lines that are not adjustments themselves, minus its "Already paid" deductions (earnings an earlier partial payment covered, and adjusted, already). On a partial payment the base is exactly the earnings it covers: all of its lines except adjustments, negative ones included (never below 0), since a negative line there only leaves that much to the final payout. Send the amount that percentage comes to, rounded to the currency's minor unit; anything else answers 400. Adjustments are stored with the payout and shown with their percentage wherever the invoice is, and they move what the creator receives. The same lines work on partial payments and video payouts below; an adjustment on a partial payment sticks, because the final payout deducts the earnings the partial covered, not what it paid.

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.

To pay the window and end the creator's campaign assignment after it, add "endAssignment": true. The assignment's last day becomes the window's end, in the same transaction as the payout; a Talentir payout the provider rejects puts the end back. Only the running assignment's most recent completed window qualifies (canPayAndEnd on the due row), anything else answers 400. A payment toward the running period, a partial payment included, answers 409 PAYOUT_CONFLICT: it would be left without a period. What the creator earned after the window is not paid.

Cancel or reinstate a window

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.

Pay a creator early

A billing window is normally paid once it has ended and turns up in the due queue. While it is still running, there are two ways to pay the creator early: a partial payment, which leaves the window open, and settling it today, which closes the window and ends the assignment.

A partial payment pays a creator part of a running window, for a creator who wants money a week into a monthly period, say. The window stays open and keeps earning. Its final payout deducts the earnings every partial payment covered, so the creator is paid the window's calculation exactly once, with each partial's adjustments applied to the earnings it covered.

Partial payments are for windows still in progress. A window that has already ended is paid in full: calculating it with "purpose": "partial" answers 400, and paying it through POST /payouts/partial answers 422 PARTIAL_PAYOUT_REFUSED.

1. Calculate with "purpose": "partial", sending the window as the upcoming queue has it. The calculation prices what the window has earned so far; a fixed salary counts by the days elapsed, today included.
2. Pay with POST /payouts/partial, under a payout id you minted (how to mint one).

CALCULATION=$(jq -n --argjson window "$WINDOW" '$window + { purpose: "partial" }' |
  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 @-)

jq -n --argjson window "$WINDOW" --argjson calc "$CALCULATION" --arg id "$PAYOUT_ID" '$window + {
    id: $id,
    calculation: $calc,
    integrityToken: $calc.integrityToken,
    lineItems: [{ title: "Partial payment for September", amount: 300 }],
    payoutProvider: "talentir"
  }' |
  curl -s -X POST https://viral.app/api/v1/payouts/partial \
    -H "x-api-key: $VIRAL_APP_API_KEY" \
    -H "content-type: application/json" \
    -d @-

The calculation's remainder.value is the most the line items may cover, adjustments not counted: what the window has earned so far, minus what the partial payments already made covered (settlement.partials, each with the amount it paid and the coveredAmount of earnings it covered). More answers 422 PARTIAL_PAYOUT_REFUSED. Paying everything earned so far is fine, a positive adjustment on top included; the window keeps running and the rest follows with its final payout.

The calculation's own lineItems add up to exactly that remainder: the earnings so far, and one negative "Already paid — …" line per earlier partial payment. You can send them instead of a line of your own, and adjust the earnings lines. The "Already paid" lines are optional on a partial payment, but if you send any, send all of them exactly as they came. The id follows the retry rule, and here the details include the lineItems: they decide what the partial covers.

Add includedVideos to the calculation to pay specific videos early at the campaign's own terms: only those videos are priced. A fixed salary is left out, because it belongs to the window rather than to a video, and a campaign with no per-video terms answers 400 and says so. Every other rule runs on the selected videos as if they were the whole window, so campaign-wide tiers and a performance cap evaluate on that subset alone.

When the window is paid in full later, its calculation lists the partial payments as negative "Already paid — …" line items, each deducting the earnings that partial covered. Send those lines back exactly as they came; a payout without them answers 409. A window whose partial payments already cover its final calculation needs no last call: it closes on its own three days after it ends. A settlement whose line items net to zero after those deductions (an adjusted partial that covered everything, say) closes the window the same way, as a mark-as-paid; through Talentir there is nothing to send.

A calculation of a window still in progress, for a partial payment or a settle & end, expires after 24 hours. A completed window's does not. Any calculation goes out of date as soon as another payment lands on the same window or its videos. Both cases answer 409 PAYOUT_CALCULATION_OUTDATED: calculate again.

Settle a billing window early

To pay a running window today and end the creator's assignment with it (a creator who leaves mid-period, say), settle and end: the running window is cut to today, the payout settles that shortened period, and the assignment ends today, all in one transaction. A fixed salary is paid pro rata, by today's share of the cycle's days. Partial payments already made toward the window move onto the shortened period and are deducted as usual.

1. Calculate with "windowValidation": "projection" and "settleToday": true (and the default "purpose": "settle"), sending the running window as the upcoming queue has it. The server prices it through today and answers with period.end set to today; the integrityToken pins that period. Without settleToday, a projection is a preview of the whole window and its token signs the dates you sent.
2. Initiate with "allowInProgress": true, the same billingPeriodStart and the calculation's period.end as billingPeriodEnd. A period that does not end today is refused with 400: calculate again.

CALCULATION=$(jq -n --argjson window "$WINDOW" '$window + { windowValidation: "projection", settleToday: true }' |
  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 @-)

jq -n --argjson window "$WINDOW" --argjson calc "$CALCULATION" '$window + {
    billingPeriodEnd: $calc.period.end,
    calculation: $calc,
    integrityToken: $calc.integrityToken,
    lineItems: $calc.lineItems,
    allowInProgress: true
  }' |
  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 @-

Once the shortened period is paid, the end is final: the assignment can no longer be reactivated and its end date cannot move (409 FINAL_PERIOD_SETTLED on unassign and switch). To end an assignment today without paying it right away, use endBasis: "today" on those routes instead. The shortened period then turns up in the due queue tomorrow.

Pay specific videos

A video payout pays chosen videos of a creator at terms of their own, outside any billing window. It takes two calls, like a window.

1. Calculate

CALCULATION=$(curl -s -X POST https://viral.app/api/v1/payouts/videos/calculate \
  -H "x-api-key: $VIRAL_APP_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "creatorId": "orgcre_4TnXq8LwPz2A",
    "videos": [{ "platform": "tiktok", "platformVideoId": "7412345678901234567" }],
    "terms": { "source": "campaign", "campaignId": "orgcamp_Hk2mRateCard" },
    "campaignRelation": "instead_of"
  }')

terms decides the price:

Rule-based terms have to price single videos: a base payout per video, per-video CPM and per-video bonuses. A fixed salary, a performance cap, and all-content, per-platform, per-account or engagement-rate rules answer 400 VIDEO_PAYOUT_INVALID, whose data.issues name each path and reason. Every video has to sit on one of the creator's own tracked accounts.

campaignRelation is required whenever one of the creator's campaign assignments overlaps the paid days, because that campaign would otherwise pay the same views again:

• "instead_of": the videos are paid at these terms instead of the campaign's. Every later calculation of the creator's campaigns leaves them out.
• "on_top": a bonus. The campaign keeps paying the videos as usual.

The payout buys views from the videos' publish day through yesterday, the last complete day. A repeat payout for the same videos continues the day after the last one. periodStart and periodEnd narrow the days; today or later is refused. The response carries the signed context (videos, relation, period, terms), the calculation (null for fixed terms), default lineItems, notices worth reading, and the integrityToken.

2. Initiate

jq -n --argjson calc "$CALCULATION" --arg id "$PAYOUT_ID" '{
    id: $id,
    creatorId: "orgcre_4TnXq8LwPz2A",
    context: $calc.context,
    calculation: $calc.calculation,
    integrityToken: $calc.integrityToken,
    lineItems: $calc.lineItems,
    payoutProvider: "talentir"
  }' |
  curl -s -X POST https://viral.app/api/v1/payouts/videos/initiate \
    -H "x-api-key: $VIRAL_APP_API_KEY" \
    -H "content-type: application/json" \
    -d @-

The id is the idempotency key, with the same retry rule as a manual payout; here the details also include the videos, the relation, the period, the terms and the lineItems. For rule-based terms the lineItems can be adjusted like a window's. For fixed terms the lines other than adjustments have to add up to the fixed amount; an adjustment line still moves the total. The spend counts toward the campaign whose terms priced the videos, else toward the campaign it relates to.

Create a manual payout

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.

1. Run the preflight

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
}

2. Mint the payout id

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)"

3. Create the payout

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": "…" }

What happens next

• "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 Awaiting Approval 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.

Retry safely

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.

Errors

What stays in the dashboard

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. A partial payment or a video payout can be canceled there only while nothing was calculated on top of it; afterwards, reissue it instead. Use the Paid tab for them.

The dashboard offers the same early payments as the API: "Pay Early" on an upcoming row opens the choice between a partial payment and settling the window today. A due row is paid in full only.