> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bango.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing plan report

> Report format for billing plans managed during a reporting period.

# Billing plan report

<Note>
  This report is currently marked as coming soon.
</Note>

The billing plan report provides a detailed view of billing plans managed during the reporting period.

Use this report to link a billing plan to a consumer, offer, or consumer offer. The report also includes information about current and future plan phases, previous invoices, and next invoices.

<Note>
  If you need to understand what was charged during the reporting period, use the charge report rather than the billing plan report.
</Note>

## How records appear

A billing plan appears once in the report.

If the billing plan moved through multiple statuses during the reporting period, or renewed more frequently than the reporting period, the report still contains one row using the latest data available at the end of the reporting period.

## Included billing plans

The report includes:

* Billing plans created during the reporting period
* Billing plans active during the reporting period
* Billing plans paused during the reporting period
* Billing plans that ended during the reporting period

## Excluded billing plans

The report does not include billing plans that ended before the start of the reporting period.

## Report format

| Column name | Format | Description | Example |
| - | -: | - | - |
| `consumerIdentifier` | string | Unique identifier for your consumer | `AC-345/JF7A` |
| `consumerOfferId` | uuid | Unique identifier for the consumer bundle | `dd8e206a-fb89-4ed1-9115-af38466d6003` |
| `offerId` | uuid | Unique identifier for the offer associated with the consumer bundle | `088bdb2b-742f-4a4a-b0c3-bd0589b49a6c` |
| `offerName` | string | Human-readable offer name | `Bango Music Premium - 6 months free` |
| `billingPlanId` | uuid | Unique identifier for the billing plan associated with the consumer bundle | `5264c710-52a8-4668-bbfc-12eeeb515f9c` |
| `planType` | string enum | Offer type based on the associated plan information | `SUBSCRIPTION` |
| `billingTrigger` | string enum | Trigger that starts the billing lifecycle | `CONSUMER_OFFER_FULLY_ACTIVATED` |
| `billingPlanStatus` | string enum | Billing plan status at the end of the reporting period | `ACTIVE` |
| `billingPlanSubStatus` | string enum | Optional transient sub-status used to indicate upcoming state changes | |
| `createdTs` | ISO-8601 to milliseconds | Date and time the billing plan was created | `2024-12-21T14:23:21.986Z` |
| `startedTs` | ISO-8601 to milliseconds | Date and time the billing plan lifecycle started | `2024-12-22T17:53:21.013Z` |
| `endingTs` | ISO-8601 to milliseconds | Date and time the billing plan was flagged as ending | |
| `endedTs` | ISO-8601 to milliseconds | Date and time the billing plan was terminated | |
| `currentPhase` | integer | Current billing plan phase. `0` is the first phase. | `0` |
| `currentPhaseType` | string enum | Type of the current billing phase | `FREE` |
| `nextPhaseType` | string enum | Type of the next phase. Empty when there is no next phase. | `FULL_PRICE` |
| `nextPhaseTs` | ISO-8601 to milliseconds | Date and time the billing plan moves to the next phase, where applicable | `2025-06-22T17:53:21.013Z` |
| `currency` | ISO-4217 | Alphabetic three-letter currency code | `USD` |
| `lastInvoiceTs` | ISO-8601 to milliseconds | Date and time the last invoice was issued | `2025-04-22T17:53:21.013Z` |
| `lastInvoiceId` | uuid | Unique identifier for the last invoice | `4096f6f0-121f-4b44-81a5-c5598e67daf3` |
| `lastInvoiceDisplayAmount` | number | Invoiceable amount, shown to the maximum decimals for the currency | `0.00` |
| `lastInvoiceStatus` | string enum | Status of the last invoice | `PAID` |
| `lastInvoiceSubStatus` | string enum | Optional sub-status of the last invoice | |
| `nextInvoiceTs` | ISO-8601 to milliseconds | Date and time the next invoice is due | `2025-05-22T17:53:21.013Z` |
| `nextInvoiceId` | uuid | Unique identifier for the next invoice | `4096f6f0-121f-4b44-81a5-c5598e67daf3` |
| `nextInvoiceDisplayAmount` | number | Invoiceable amount, shown to the maximum decimals for the currency | `17.99` |
| `nextInvoiceStatus` | string enum | Status of the next invoice | `CALCULATED` |

## Enum values

### `planType`

| Value | Support |
| - | - |
| `SUBSCRIPTION` | Supported |
| `REDEMPTION` | Future supported option |
| `FIXED_TERM` | Future supported option |
| `TRANSACTION` | Future supported option |

### `billingTrigger`

| Value |
| - |
| `CONSUMER_OFFER_FULLY_CREATED` |
| `CONSUMER_OFFER_FULLY_ACTIVATED` |

<Note>
  The list of billing triggers is expected to grow over time.
</Note>

### `billingPlanStatus`

| Value |
| - |
| `REQUESTED` |
| `CREATED` |
| `ACTIVE` |
| `PAUSED` |
| `ENDED` |

### `billingPlanSubStatus`

| Value | Applies to |
| - | - |
| `PAUSING` | `CREATED` and `ACTIVE` |
| `ENDING` | `CREATED`, `ACTIVE`, and `PAUSED` |

### Phase types

| Value |
| - |
| `FREE` |
| `DISCOUNT` |
| `FULL_PRICE` |

### `lastInvoiceStatus`

| Value |
| - |
| `ISSUED` |
| `PAID` |
| `NOT_PAID` |
| `REFUNDED` |
| `RESCINDED` |

<Note>
  Earlier invoice statuses such as `INITIALIZED` and `CALCULATED` are not expected to appear for a historical invoice in this report.
</Note>

### `lastInvoiceSubStatus`

| Value | Notes |
| - | - |
| `PENDING_CALCULATE` | Only applies to `INITIALIZED` invoices |
| `PARTIALLY_PAID` | Invoice was partially paid |
| `PAYMENT_NOT_REQUIRED` | Payment was not required, for example where a zero charge was suppressed |
| `NO_PAYMENT_METHOD` | No payment method was available |

### `nextInvoiceStatus`

| Value | Notes |
| - | - |
| `CALCULATED` | Expected value for the next invoice status column |

<Note>
  Other invoice statuses may exist, but are not expected in `nextInvoiceStatus` for this report.
</Note>

## Example header

```csv theme={null}
consumerIdentifier,consumerOfferId,offerId,offerName,billingPlanId,planType,billingTrigger,billingPlanStatus,billingPlanSubStatus,createdTs,startedTs,endingTs,endedTs,currentPhase,currentPhaseType,nextPhaseType,nextPhaseTs,currency,lastInvoiceTs,lastInvoiceId,lastInvoiceDisplayAmount,lastInvoiceStatus,lastInvoiceSubStatus,nextInvoiceTs,nextInvoiceId,nextInvoiceDisplayAmount,nextInvoiceStatus
```

## Related reports

<CardGroup cols={2}>
  <Card title="Forecast report" icon="chart-line-up" href="/billing-charging-reports/billing-forecast-report">
    Future invoices due in the next month.
  </Card>

  <Card title="Billing & charging reports" icon="receipt" href="/billing-charging-reports">
    Overview of billing and charging report options.
  </Card>
</CardGroup>