---
title: "List upcoming creator payouts"
method: GET
path: "/payouts/upcoming"
tags: ["Payouts"]
---

# List upcoming creator payouts

`GET /payouts/upcoming`

## Request

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

Returns billing periods that have started but are not yet finished. Uses campaign anchors and creator assignments to identify the current in-progress cycle for each assignment.

## Query parameters

- `page` number: Page number (1-based index)
- `perPage` number: Number of items per page (1-100)
- `sortCol` string: Sort column
- `sortDir` 'asc' | 'desc': Sort direction
- `campaignIds` string[]
- `creatorIds` string[]
- `includeEmpty` boolean: Include zero-amount payouts in the results. They are excluded by default.
- `mode` 'data' | 'count' | 'totals'
- `referenceDate` string, date-time

## Response `200`

OK

- object
  - `page` integer, required
  - `perPage` integer, required
  - `total` integer, required
  - `data` object[], required
    - `id` string, required
    - `campaignId` string, required: Campaign ID with orgcamp_ prefix
    - `campaignName` string, required
    - `creatorId` string, required: Organization creator ID with orgcre_ prefix
    - `creatorUserId` string, required
    - `creatorName` string, nullable, required
    - `creatorEmail` string, required
    - `creatorImage` string, nullable, required
    - `accounts` object[]
      - `id` string, required
      - `platform` 'facebook' | 'instagram' | 'tiktok' | 'youtube' | 'snapchat', required
      - `platformAccountId` string, required
      - `isCompetitor` boolean
      - `username` string, nullable, required
      - `displayName` string, nullable
      - `analyticsDataRefreshedAt` string, nullable
    - `isMarketplaceCreator` boolean
    - `campaignStatus` 'upcoming' | 'active' | 'closing' | 'ended': Campaign lifecycle status derived from validity window. upcoming: validFrom in the future; active: started with no end date; closing: started and has an end date in the present/future; ended: end date is in the past.
    - `campaignValidFrom` string, nullable
    - `campaignValidUntil` string, nullable
    - `billingPeriodStart` string, date-time, required
    - `billingPeriodEnd` string, date-time, required
    - `interval` 'day' | 'week' | 'month', required
    - `intervalCount` integer, required
    - `billingAnchor` 'fixed' | 'rolling', required
    - `timeZone` string, required: 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.
    - `currency` 'USD' | 'EUR' | 'CHF' | 'GBP' | 'CNY' | 'JPY' | 'KRW' | 'THB' | 'IDR' | 'VND' | 'RUB', required
    - `endedEarly` boolean
    - `startedMidPeriod` boolean
    - `manualPaidInPeriod` object, nullable
      - `amount` integer, required
      - `precision` integer, required
      - `currency` 'USD' | 'EUR' | 'CHF' | 'GBP' | 'CNY' | 'JPY' | 'KRW' | 'THB' | 'IDR' | 'VND' | 'RUB', required
      - `count` integer, required
      - `lastPaidAt` string, required
    - `startsAt` string, date-time: The exact instant the period starts: midnight of its first day in the campaign's time zone, with that zone's offset.
    - `endsAt` string, date-time: The exact instant the period ends (exclusive): midnight after its last day in the campaign's time zone.
    - `payoutAmount` integer, nullable, required
    - `payoutPrecision` integer, nullable, required
    - `payoutCurrency` 'USD' | 'EUR' | 'CHF' | 'GBP' | 'CNY' | 'JPY' | 'KRW' | 'THB' | 'IDR' | 'VND' | 'RUB', nullable, required
    - `partialsPaid` object, nullable
      - `count` integer, required
      - `amount` integer, required
      - `coveredAmount` integer, required
      - `calculatedAmount` integer, required
  - `totalsByCurrency` object[]
    - `currency` string, required
    - `amount` number, required

## 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)