---
title: "Get paid payout breakdown"
method: GET
path: "/payouts/{id}/breakdown"
tags: ["Payouts"]
---

# Get paid payout breakdown

`GET /payouts/{id}/breakdown`

## Request

- Base URL: `https://viral.app/api/v1`
- URL: `https://viral.app/api/v1/payouts/{id}/breakdown`
- Auth: API key in header `x-api-key`

Returns the persisted calculation summary snapshot and invoiced line items for a paid payout. `summary` and `engineTotal` may be null for records created before snapshots were stored. `invoiced` amounts are in major currency units.

## Path parameters

- `id` string, required: Payout ID with orgpay_ prefix

## Response `200`

OK

- object: Stored payout breakdown: the immutable engine calculation snapshot plus the invoiced line items
  - `id` string, required: Payout ID with orgpay_ prefix
  - `summary` object, nullable, required: Engine calculation summary recorded at payout time; null for records without a stored snapshot
    - `period` object, required
      - `index` integer, required
      - `label` string, required
      - `start` string, required
      - `end` string, required
    - `payouts` object, required
      - `total` object, required
        - `amount` number, required
        - `precision` integer, required
        - `currency` string, required
        - `value` number, required
      - `breakdown` object[], required
        - `label` string, required
        - `ruleIds` string[]
        - `ruleName` string, nullable, required
        - `payoutKind` 'flat' | 'rate', required
        - `payoutMode` 'allocation' | 'progressive'
        - `amount` number, required
        - `precision` integer, required
        - `currency` string, required
        - `value` number, required
        - `calculationDetails` object, nullable, required
          - `metricKey` string, required
          - `metricValue` number, required
          - `grain` 'aggregate' | 'per_video' | 'per_platform' | 'per_account'
          - `rawMetricValue` number
          - `metricStartValue` number
          - `metricEndValue` number
          - `eligibleVideoCount` integer
          - `minViewsRequired` integer
          - `conditioned` unknown
          - `creatives` 'once' | 'best' | 'sum': How this row's payouts treat the copies of one creative (the same video posted to several platforms): once, a base payout counts each creative once, on its winner (the copy with the most views); best, a CPM payout or bonus pays only the creative's winner; sum, the per_creative scope: the copies count as one, their views added up on one copy. Absent when the row pays every copy
          - `ratePerUnit` number
          - `perQuantity` integer
          - `mode` 'allocation' | 'progressive'
          - `payoutTiming` 'gains' | 'milestone'
          - `appliedTierIndex` integer
          - `tierBreakdown` union[]
            - union
              - …
          - `maxPayoutApplied` boolean
          - `performanceCapApplied` boolean
          - `baseCapApplied` boolean
          - `earlySettledTopTier` boolean
          - `carriedVideoCount` integer
          - `carriedAmount` number
          - `carriedWindows` object[]
            - `start` string, required
            - `end` string, required
            - `videoCount` integer, required
          - `carriedWaiting` unknown
        - `off` unknown
      - `performanceCap` object
        - `amount` number, required
        - `precision` integer, required
        - `currency` string, required
        - `value` number, required
        - `applied` boolean, required
      - `baseCap` object
        - `amount` number, required
        - `precision` integer, required
        - `currency` string, required
        - `value` number, required
        - `applied` boolean, required
    - `metrics` object, required
      - `facts` object[], required
        - `factName` string, required
        - `metric` 'views' | 'likes' | 'shares' | 'comments' | 'videoCount' | 'engagementRate', required
        - `label` string, required
        - `total` number, required
      - `perVideo` object, nullable, required
        - `metric` 'views' | 'likes' | 'shares' | 'comments' | 'videoCount' | 'engagementRate', required
        - `label` string, required
        - `items` object[], required
          - `id` string, nullable, required
          - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
          - `platformVideoId` string, required
          - `value` number, required
          - `title` string, nullable, required
          - `thumbnailUrl` string, nullable, required
          - `publishedAt` string, nullable, required
          - `accountUsername` string, nullable, required
          - `platformAccountId` string, nullable, required
          - `isCompetitor` boolean, required
          - `contentType` 'video' | 'slideshow', nullable, required: Filter by content types (video, slideshow)
          - `orgAccountId` string, nullable, required: Organization account ID with orgacc_ prefix. Not the same as platform account ID.
          - `payoutAmount` number, nullable, required
          - `payoutCurrency` string, nullable, required
          - `payoutValue` number, nullable, required
          - `creativeCopies` integer: A per-creative payout's row: this video carries its creative, this many copies in all (itself included). On a CPM payout or bonus its value adds up every copy's views; on a base payout it keeps its own views and the creative counts once. The other copies are listed in metrics.mergedCopies
      - `perCategory` object[], nullable, required
        - `category` string, required
        - `metric` 'views' | 'likes' | 'shares' | 'comments' | 'videoCount' | 'engagementRate', required
        - `metricKey` string, required
        - `metricLabel` string, required
        - `items` object[], required
          - `id` string, nullable, required
          - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
          - `platformVideoId` string, required
          - `value` number, required
          - `title` string, nullable, required
          - `thumbnailUrl` string, nullable, required
          - `publishedAt` string, nullable, required
          - `accountUsername` string, nullable, required
          - `platformAccountId` string, nullable, required
          - `isCompetitor` boolean, required
          - `contentType` 'video' | 'slideshow', nullable, required: Filter by content types (video, slideshow)
          - `orgAccountId` string, nullable, required: Organization account ID with orgacc_ prefix. Not the same as platform account ID.
          - `payoutAmount` number, nullable, required
          - `payoutCurrency` string, nullable, required
          - `payoutValue` number, nullable, required
          - `creativeCopies` integer: A per-creative payout's row: this video carries its creative, this many copies in all (itself included). On a CPM payout or bonus its value adds up every copy's views; on a base payout it keeps its own views and the creative counts once. The other copies are listed in metrics.mergedCopies
      - `viewBasis` 'total' | 'organic'
      - `manuallyExcludedVideos` object[]
        - `id` string, nullable, required
        - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
        - `platformVideoId` string, required
        - `value` number, required
        - `title` string, nullable, required
        - `thumbnailUrl` string, nullable, required
        - `publishedAt` string, nullable, required
        - `accountUsername` string, nullable, required
        - `platformAccountId` string, nullable, required
        - `isCompetitor` boolean, required
        - `contentType` 'video' | 'slideshow', nullable, required: Filter by content types (video, slideshow)
        - `orgAccountId` string, nullable, required: Organization account ID with orgacc_ prefix. Not the same as platform account ID.
        - `payoutAmount` number, nullable, required
        - `payoutCurrency` string, nullable, required
        - `payoutValue` number, nullable, required
        - `creativeCopies` integer: A per-creative payout's row: this video carries its creative, this many copies in all (itself included). On a CPM payout or bonus its value adds up every copy's views; on a base payout it keeps its own views and the creative counts once. The other copies are listed in metrics.mergedCopies
        - `ruleIds` string[]
      - `conditionMisses` object[]
        - `category` string, required
        - `ruleIds` string[], required
        - `scope` 'per_video' | 'aggregate', required
        - `items` object[], required
          - `id` string, nullable, required
          - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
          - `platformVideoId` string, required
          - `value` number, required
          - `title` string, nullable, required
          - `thumbnailUrl` string, nullable, required
          - `publishedAt` string, nullable, required
          - `accountUsername` string, nullable, required
          - `platformAccountId` string, nullable, required
          - `isCompetitor` boolean, required
          - `contentType` 'video' | 'slideshow', nullable, required: Filter by content types (video, slideshow)
          - `orgAccountId` string, nullable, required: Organization account ID with orgacc_ prefix. Not the same as platform account ID.
          - `payoutAmount` number, nullable, required
          - `payoutCurrency` string, nullable, required
          - `payoutValue` number, nullable, required
          - `creativeCopies` integer: A per-creative payout's row: this video carries its creative, this many copies in all (itself included). On a CPM payout or bonus its value adds up every copy's views; on a base payout it keeps its own views and the creative counts once. The other copies are listed in metrics.mergedCopies
          - `failed` union[], required
            - union
              - …
          - `wouldEarn` number, nullable
          - `creative` object: Set when a creative payout left this copy out (the group's creatives option): the reason, and the copy that earns instead. failed is empty then: the creative option, not a condition, left the copy out
            - `reason` 'not_best' | 'counted_before' | 'counted_with' | 'bought_out' | 'earlier_period' | 'creative_views', required: Why this copy earned nothing here. not_best: another copy of the creative has more views and is the one a winner-only CPM payout or bonus pays. counted_with: another copy (the winner) counts the creative once in this period. counted_before: the creative was already counted in an earlier period. bought_out: a copy of the creative was paid on its own (a video payout instead of the campaign's pay), which settles the creative for this payout. earlier_period: the creative was first posted in an earlier period and judged there (a per-creative base payout with a Video views condition). creative_views: the copies' combined views (views) fall outside that Video views condition
            - `views` number: This copy's views over the payout's time frame; for creative_views, the creative's combined views
            - `by` object, required: The copy that earns or counts instead: the creative's winner, the copy counted earlier or the bought-out copy; for earlier_period the copy posted in that earlier period, for creative_views the creative's leading copy
              - …
        - `omittedCount` integer, required
        - `failedGates` object[]
          - `condition` union, required
            - object
              - …
            - object
              - …
          - `total` number, required
        - `forfeit` object
          - `amount` number, required
          - `precision` integer, required
          - `currency` string, required
          - `value` number, required
        - `creatives` union: The group lists copies a creative payout did not pay (each item carries creative): the payout's option (once, best or sum, as on calculationDetails.creatives), or true on calculations from before it was recorded
          - unknown
          - 'once' | 'best' | 'sum'
      - `carriedVideos` object[]: Per base payout row, the earlier periods' videos it pays as carried (a missed total videos minimum with a carry), or that wait for a period that reaches the minimum
        - `category` string, required: The breakdown row's label
        - `ruleIds` string[], required
        - `status` 'paid' | 'waiting', required
        - `items` object[], required
          - `id` string, nullable, required
          - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
          - `platformVideoId` string, required
          - `value` number, required
          - `title` string, nullable, required
          - `thumbnailUrl` string, nullable, required
          - `publishedAt` string, nullable, required
          - `accountUsername` string, nullable, required
          - `platformAccountId` string, nullable, required
          - `isCompetitor` boolean, required
          - `contentType` 'video' | 'slideshow', nullable, required: Filter by content types (video, slideshow)
          - `orgAccountId` string, nullable, required: Organization account ID with orgacc_ prefix. Not the same as platform account ID.
          - `payoutAmount` number, nullable, required
          - `payoutCurrency` string, nullable, required
          - `payoutValue` number, nullable, required
          - `creativeCopies` integer: A per-creative payout's row: this video carries its creative, this many copies in all (itself included). On a CPM payout or bonus its value adds up every copy's views; on a base payout it keeps its own views and the creative counts once. The other copies are listed in metrics.mergedCopies
          - `carriedFrom` object, required: The missed period the video was posted in (YYYY-MM-DD)
            - `start` string, required
            - `end` string, required
        - `omittedCount` integer, required
      - `mergedCopies` object[]: Per breakdown row of a per-creative payout, the copies that counted with another copy of their creative (dialog and breakdown calculations only). Not misses: they are paid through that copy
        - `category` string, required: The breakdown row's label
        - `ruleIds` string[], required
        - `pay` 'once' | 'sum', required: once: a base payout counted the creative once, on the into copy (each copy keeps its own views). sum: a CPM payout or bonus added the copies' views up on the into copy
        - `items` object[], required
          - `id` string, nullable, required
          - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
          - `platformVideoId` string, required
          - `value` number, required
          - `title` string, nullable, required
          - `thumbnailUrl` string, nullable, required
          - `publishedAt` string, nullable, required
          - `accountUsername` string, nullable, required
          - `platformAccountId` string, nullable, required
          - `isCompetitor` boolean, required
          - `contentType` 'video' | 'slideshow', nullable, required: Filter by content types (video, slideshow)
          - `orgAccountId` string, nullable, required: Organization account ID with orgacc_ prefix. Not the same as platform account ID.
          - `payoutAmount` number, nullable, required
          - `payoutCurrency` string, nullable, required
          - `payoutValue` number, nullable, required
          - `creativeCopies` integer: A per-creative payout's row: this video carries its creative, this many copies in all (itself included). On a CPM payout or bonus its value adds up every copy's views; on a base payout it keeps its own views and the creative counts once. The other copies are listed in metrics.mergedCopies
          - `into` object, required: The copy the row lists, which this copy counted with
            - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
            - `platformVideoId` string, required
        - `omittedCount` integer, required
      - `conditionTagNames` object
      - `conditionForfeit` object
        - `amount` number, required
        - `precision` integer, required
        - `currency` string, required
        - `value` number, required
      - `videoGates` object[]
        - `ruleId` string, required
        - `required` integer, required
        - `count` integer, required
        - `met` boolean, required
    - `settlement` object
      - `purpose` 'settle' | 'partial', required
      - `calculatedAt` string, required
      - `inProgress` boolean, required
      - `fixedElapsedFactor` number, required
      - `partials` object[], required
        - `payoutId` string, required
        - `amount` integer, required
        - `coveredAmount` integer
        - `paidAt` string, required
      - `separatelyPaidVideos` object[], required
        - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
        - `platformVideoId` string, required
      - `placedVideos` object[]
        - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
        - `platformVideoId` string, required
      - `includedVideos` object[]
        - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
        - `platformVideoId` string, required
      - `carriedVideos` object[]
        - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
        - `platformVideoId` string, required
        - `periodStart` string, required
        - `periodEnd` string, required
        - `ruleId` string
      - `priorCarriedVideos` object[]
        - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required: Social media platform (facebook, instagram, tiktok, youtube, snapchat)
        - `platformVideoId` string, required
      - `carryStops` object[]
        - `ruleId` string, required
        - `periodStart` string, required
      - `timeZone` string: IANA time zone the campaign's periods and dates follow (a period ends at midnight in this zone). Views are still counted per UTC day.
      - `viewsOpenUntil` string
      - `closure` object
        - `kind` 'covered' | 'written_off', required
        - `overpaidAmount` integer, required
        - `writtenOffAmount` integer, required
    - `customRates` boolean
  - `engineTotal` object, nullable, required: Engine-calculated total before invoice customization (minor-unit amount plus major-unit value); null for records without a stored snapshot
    - `amount` number, required
    - `precision` integer, required
    - `currency` string, required
    - `value` number, required
  - `invoiced` object, required: The invoice as issued (amounts in major currency units)
    - `amount` number, required: Paid total in major currency units
    - `precision` integer, required
    - `currency` 'USD' | 'EUR' | 'CHF' | 'GBP' | 'CNY' | 'JPY' | 'KRW' | 'THB' | 'IDR' | 'VND' | 'RUB', required
    - `lineItems` object[], required
      - `title` string, required: Invoice line item title
      - `amount` number, required: Line item amount in major currency units
      - `kind` 'adjustment': Present on an adjustment line: a percentage of the payout's base.
      - `percent` number: The adjustment's percentage of the base
  - `customized` boolean, required: Whether the invoice was customized away from the calculated total (the server-owned "Already paid" deductions of earlier partial payments do not count)
  - `partialPayment` boolean, required: Whether this payout is a partial payment toward a billing window still in progress (the calculation is then what the window had earned so far)
  - `partialsDeducted` number, required: Earnings of earlier partial payments this invoice deducts ("Already paid" lines), in major currency units; 0 when none

## Other responses

- `400`: 400
- `401`: 401
- `402`: 402
- `404`: 404
- `408`: 408
- `429`: 429
- `500`: 500

---

[API](https://skmtc.dev/viral/apis/viral-app-api.md) · [All operations](https://skmtc.dev/viral/apis/viral-app-api/llms.txt) · [OpenAPI document](https://skmtc.dev/viral/apis/viral-app-api/revisions/31e97fa79ef1?raw)