---
title: "Get revenue waterfall"
method: POST
path: "/revenue_reports/waterfall"
tags: ["Revenue Reports"]
---

# Get revenue waterfall

`POST /revenue_reports/waterfall`

## Request

- Base URL: `https://us.api.flexprice.io/v1`
- URL: `https://us.api.flexprice.io/v1/revenue_reports/waterfall`
- Auth: API key in header `x-api-key`

Use when showing revenue per customer, contract or performance obligation and month: actual (posted), pending (earned, not yet posted) and scheduled (invoiced, not yet earned), with optional month-end deferred and unbilled balances. Covers at most 36 months.

## Request body

- WaterfallRequest
  - `as_of` string: report date: pending and scheduled split here; defaults to now
  - `contract_ids` string[]
  - `currency` string, required
  - `customer_ids` string[]
  - `details` boolean: month-end deferred and unbilled balances
  - `group_by` 'customer_id' | 'contract_id' | 'pob_id'
  - `limit` integer: rows per page; totals are never paged
  - `offset` integer
  - `period_end` string, date-time, required: YYYY-MM, at most 36 months from period_start
  - `period_start` string, date-time, required: YYYY-MM
  - `pob_ids` string[]

## Response `200`

OK

- WaterfallResponse
  - `items` WaterfallRow[]
    - `cells` WaterfallCell[]: one per requested period, in order
      - `deferred` string: details: closing deferred_revenue, ended months only
      - `period` string: YYYY-MM
      - `revenue` RevenueBreakdown
        - `actual` string
        - `pending` string
        - `scheduled` string
        - `total` string: actual + pending + scheduled
      - `unbilled` string: details: closing unbilled_receivable, ended months only
    - `contract_id` string
    - `customer_id` string
    - `pob_id` string
  - `pagination` TypesPaginationResponse
    - `limit` integer
    - `offset` integer
    - `total` integer
  - `totals` WaterfallCell[]: per period over all rows, never paged
    - `deferred` string: details: closing deferred_revenue, ended months only
    - `period` string: YYYY-MM
    - `revenue` RevenueBreakdown
      - `actual` string
      - `pending` string
      - `scheduled` string
      - `total` string: actual + pending + scheduled
    - `unbilled` string: details: closing unbilled_receivable, ended months only

## Other responses

- `400`: Invalid request
- `500`: Server error

## Changes

- **2026-10-29** `d3bef0889eec`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/flexprice/apis/flexprice-api/changes/revenue_reports/waterfall/post.md)

---

[API](https://skmtc.dev/flexprice/apis/flexprice-api.md) - [All operations](https://skmtc.dev/flexprice/apis/flexprice-api/llms.txt) - [OpenAPI document](https://skmtc.dev/flexprice/apis/flexprice-api/revisions/e1348d61034c?raw)