Payouts

Calculate a video payout

Prices specific videos of a creator at terms of their own, outside any billing window — for deals that differ per video. terms come from a campaign (source: "campaign"; a campaign without creators works as a rate card), are sent inline in the campaign spec's payouts vocabulary (source: "inline"), or are a fixed amount (source: "fixed"). Rule-based terms must price single videos: base payout per video, per-video CPM and per-video bonuses. Every video must sit on one of the creator's own tracked accounts. The payout buys views from the videos' publish day through yesterday, the last complete day; a repeat payout continues the day after the last one. When the creator is assigned to a campaign that would pay the same videos, campaignRelation is required: "instead_of" takes the videos out of every later campaign calculation for the creator, "on_top" is a bonus. Returns the signed context and calculation, default lineItems, notices, and the integrityToken for POST /payouts/videos/initiate; the calculation expires after 24 hours. A request that cannot be priced is a 400 VIDEO_PAYOUT_INVALID whose data.issues name the path and the reason.

post/payouts/videos/calculate

Request

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

Request body

creatorIdstring required

Organization creator ID with orgcre_ prefix

campaignRelation'instead_of' | 'on_top'

REQUIRED whenever one of the creator's campaign assignments overlaps the paid period — otherwise that campaign would pay the same views again. "instead_of": the videos are paid at these terms INSTEAD of the campaign's, and every later calculation of the creator's campaigns leaves them out. "on_top": a bonus; the campaign still pays the videos normally. To pay videos early at the campaign's OWN terms, use POST /payouts/partial with includedVideos.

periodStartstring date

First UTC day the payout buys views for. Defaults to the videos' publish date, or for a repeat payout to the day after the last one. For "instead_of" it is derived (the day after what was already paid) and cannot be moved earlier.

periodEndstring date

Last UTC day the payout buys views for. Defaults to yesterday, the last complete day; today or later is refused, because the rest of a half-finished day could never be paid afterwards.

Example request

{
  "videos": [
    {
      "platform": "facebook"
    }
  ],
  "terms": {
    "campaignId": "orgcamp_RwmraAffhMt9"
  }
}

Response

OK

noticesstring[] required
integrityTokenstring required

Integrity token returned alongside the calculation. Pass it unchanged to POST /payouts/initiate together with the calculation payload.

Example response

{
  "context": {
    "videos": [
      {
        "platform": "facebook"
      }
    ],
    "coveringCampaignId": "orgcamp_RwmraAffhMt9",
    "termsCampaignId": "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"
          }
        ]
      }
    }
  }
}

Changes

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