Payouts

Initiate a payout

Stores the finalized payout calculation, engine metadata, and caller-supplied invoice line items for a billing window, and SETTLES that window. Call POST /payouts/calculate first and pass the returned calculation payload plus integrityToken here. The window must be completed, unless you settle and end today: calculate with windowValidation: "projection" and settleToday: true, then send allowInProgress: true with the same billingPeriodStart and the calculation's period.end (today) as billingPeriodEnd — the payout then settles the running period cut to today, and the creator's campaign assignment ends today (a fixed salary is paid pro rata). To pay a completed window and end the assignment after it, send endAssignment: true (the running assignment's most recent completed period only). When partial payments were made toward the window (POST /payouts/partial), the calculation returns one negative "Already paid" line item per partial; send them back unchanged (a missing or altered one is a 409), every other line item stays yours to customize. payoutProvider="manual" (the default) records a payment made outside viral.app; payoutProvider="talentir" creates a Talentir payout that waits for approval by a member of your Talentir team in the dashboard.

post/payouts/initiate

Request

  • Base URL: https://viral.app/api/v1
  • URL: https://viral.app/api/v1/payouts/initiate
  • Auth: API key in header x-api-key

Request body

campaignIdstring required

Campaign ID with orgcamp_ prefix

creatorIdstring required

Organization creator ID with orgcre_ prefix

billingPeriodStartstring date-time required
billingPeriodEndstring date-time required
integrityTokenstring required

Required integrity token returned by POST /payouts/calculate for this exact calculation payload and billing window. Pass it unchanged.

referencestring

Optional payout reference for reconciliation, invoicing, or external bookkeeping.

notesstring

Optional internal payout notes visible to organization members.

payoutProvider'manual' | 'talentir'
allowInProgressboolean

Settle and end today. The running billing window is cut to today, this payout settles that cut period, and the creator's campaign assignment ends today (a fixed salary is paid pro rata). Requires a calculation made with purpose: "settle" and windowValidation: "projection", whose period.end is today — send that period here — and no older than 24 hours.

endAssignmentboolean

Pay and end, for a completed window: the creator's campaign assignment ends after this billing period (its last day becomes the period's end), in the same transaction as the payout. Only the running assignment's most recent completed period qualifies, and nothing may be paid or canceled after it — a partial payment toward the running period included. What the creator earned after the period is not paid. allowInProgress ends the assignment today on its own.

acknowledgeOpenViewsboolean

Pay a completed period whose views still count. Outside UTC a period ends at midnight in the campaign's time zone, but views are counted per UTC day, so the views of the UTC day the period ends on keep counting until that day is over (the calculation's settlement.viewsOpenUntil). Until then the payout is refused with VIEWS_STILL_OPEN unless you send true; views counted after the payout are not paid.

Example request

{
  "campaignId": "orgcamp_RwmraAffhMt9",
  "calculation": {
    "metrics": {
      "perVideo": {
        "items": [
          {
            "platform": "facebook"
          }
        ]
      },
      "perCategory": [
        {
          "items": [
            {
              "platform": "facebook"
            }
          ]
        }
      ],
      "manuallyExcludedVideos": [
        {
          "platform": "facebook"
        }
      ],
      "conditionMisses": [
        {
          "items": [
            {
              "platform": "facebook",
              "creative": {
                "by": {
                  "platform": "facebook"
                }
              }
            }
          ]
        }
      ],
      "carriedVideos": [
        {
          "items": [
            {
              "platform": "facebook"
            }
          ]
        }
      ],
      "mergedCopies": [
        {
          "items": [
            {
              "platform": "facebook",
              "into": {
                "platform": "facebook"
              }
            }
          ]
        }
      ]
    },
    "settlement": {
      "separatelyPaidVideos": [
        {
          "platform": "facebook"
        }
      ],
      "placedVideos": [
        {
          "platform": "facebook"
        }
      ],
      "includedVideos": [
        {
          "platform": "facebook"
        }
      ],
      "carriedVideos": [
        {
          "platform": "facebook"
        }
      ],
      "priorCarriedVideos": [
        {
          "platform": "facebook"
        }
      ],
      "timeZone": "UTC"
    },
    "engine": {
      "factTraces": [
        {
          "requirement": {
            "platformFilter": {
              "include": [
                "facebook"
              ],
              "exclude": [
                "facebook"
              ]
            }
          },
          "billingWindow": {
            "timeZone": "UTC"
          }
        }
      ],
      "engineEvents": [
        {
          "factTrace": {
            "requirement": {
              "platformFilter": {
                "include": [
                  "facebook"
                ],
                "exclude": [
                  "facebook"
                ]
              }
            },
            "billingWindow": {
              "timeZone": "UTC"
            }
          }
        }
      ],
      "accountSnapshot": {
        "accounts": [
          {
            "platform": "facebook",
            "platformAccountId": "7123456789012345678"
          }
        ]
      }
    }
  }
}

Response

OK

successunknown required
payoutIdstring required

Payout ID with orgpay_ prefix

providerPayoutIdstring nullable

Example response

{
  "payoutId": "orgpay_RwmraAffhMt9"
}

Changes

No recorded changes to this operation across all 1 revision of this API.