Payouts

Calculate payout details

Runs the payout engine for a specific creator and billing window, returning the finalized calculation payload, the default server-generated line items, the remainder still to pay after earlier partial payments, and an integrityToken. Use the returned calculation plus integrityToken as the basis for POST /payouts/initiate (purpose: "settle", the default) or POST /payouts/partial (purpose: "partial"). A calculation of a window that is still in progress is a to-date number and expires after 24 hours.

post/payouts/calculate

Request

  • Base URL: https://viral.app/api/v1
  • URL: https://viral.app/api/v1/payouts/calculate
  • 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 required
billingPeriodEndstring required
windowValidation'completed' | 'projection'
purpose'settle' | 'partial'

"settle" prices the payout that closes the billing window: POST /payouts/initiate, which for a window still in progress needs windowValidation: "projection" plus settleToday: true here and allowInProgress: true there. "partial" prices a payment on account for POST /payouts/partial, on a window still in progress only (a window that has ended answers 400): the window stays open, and fixed salary is prorated by the days elapsed so far. Either way the result lists the partial payments already made toward the window (settlement.partials), and a settle carries them as negative line items.

settleTodayboolean

Settle & end: price a window that is still in progress through today, as the final period of an assignment that ends today (POST /payouts/initiate with allowInProgress: true then ends it). The result's period.end is today and the integrityToken pins that period, so send period.end back as billingPeriodEnd. Needs windowValidation: "projection" and purpose: "settle". Without it, a projection is a preview of the whole window.

Example request

{
  "campaignId": "orgcamp_RwmraAffhMt9",
  "excludedVideos": [
    {
      "platform": "facebook"
    }
  ],
  "includedVideos": [
    {
      "platform": "facebook"
    }
  ]
}

Response

OK

customRatesboolean
integrityTokenstring required

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

Example response

{
  "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.