Payouts

Create a partial payout

Pays a creator PART of a billing window that is still in progress and leaves the window open: the rest follows with the window's settling payout (POST /payouts/initiate), whose calculation deducts every partial payment as a negative "Already paid" line item. A window that has ended is paid in full instead (a partial payment toward it answers 422). Call POST /payouts/calculate with purpose: "partial" first — it prices what the window has earned so far, fixed salary prorated by the days elapsed, today included — and pass the returned calculation plus integrityToken here with your lineItems. Their total may not exceed the calculation's remainder. Add includedVideos to the calculation to pay specific videos of the running window early. Mint the id yourself (orgpay_ plus 12 alphanumeric characters); it is the idempotency key, so a retry with the same id and the same details returns the original payout instead of paying twice, and the same id with different details is a 409. payoutProvider="manual" (the default) records a payment you already made elsewhere; payoutProvider="talentir" creates a Talentir payout that waits for approval by a member of your Talentir team in the dashboard — this route never approves one.

post/payouts/partial

Request

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

Request body

idstring required

Payout id minted by the caller (orgpay_ plus 12 alphanumeric characters) — the idempotency key. Re-send the same id to retry: the same details return the original payout, different details are a 409.

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

Integrity token returned by POST /payouts/calculate with purpose: "partial" 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'

"manual" records a payment made outside viral.app; "talentir" creates a Talentir payout that waits for approval in the dashboard.

Example request

{
  "id": "orgpay_RwmraAffhMt9",
  "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.