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

# Charge reports

<Note>
  Charge & Refund reporting is available as part of Digital Vending Machine's optional Billing & Charging capability. [Contact us](sales@bango.com) to find out more about Billing and Charging.
</Note>

When you use the Charges and Refunds APIs, every billing event we process on your behalf is recorded.

Each month you receive a structured record of every charge and refund we have processed for your consumers: what was billed, when, for which product, and whether it succeeded.

You can use them to:

* *Reconcile revenue* against your own systems, using your own reference numbers
* *Match refunds to the charges they reverse*, without stitching API calls together
* *Understand billing patterns* across your consumer base: first bills versus renewals, promotional pricing versus full price

## The two reports

| Report | What it's for | Frequency |
| :- | :- | :- |
| **Charge Detail Report** | Every transaction event, itemised. One row per line item, so bundled offers appear as a row per component. | Monthly |
| **CHarge Summary Report** | Aggregated view for a high-level picture of billing activity across the period. | Monthly |

Both cover charges and refunds.

## Charge Detail Report

The most granular view. One row per line item means a bundle charge covering three content providers produces three rows, each carrying the shared transaction details plus its own amount.

By default the report contains successful charges and refunds.

### Field reference

**Identifying your consumer**

| Field | Description |
| :- | :- |
| `consumerIdentifier` | Your own customer ID, as supplied to us |
| `billingIdentifier` | The billing identifier associated with the consumer. Initially this matches your `consumerIdentifier`. |

**Identifying the transaction**

| Field | Description |
| :- | :- |
| `transactionId` | Unique ID for this charge or refund event |
| `billId` | Groups all attempts for the same bill. If a renewal is retried, every attempt shares this value. |
| `partnerTransactionID` | Your own reference number for the transaction, for correlation with your records |
| `attempt` | Which attempt this row represents. `0` is the first attempt, `1` the first retry, and so on. |
| `status` | Outcome of the transaction |

**When it happened**

| Field | Description |
| :- | :- |
| `billEffectiveDate` | The date and time the bill took effect |
| `billingPeriodStart` | Start of the service period this transaction covers |
| `billingPeriodEnd` | End of the service period this transaction covers |

**What kind of transaction it was**

| Field | Description |
| :- | :- |
| `billType` | The billing event type. Values include `FIRST_BILL`, `RENEWAL`, `PRO_RATED_CHARGE`, `SINGLE_CHARGE`, `PRO_RATED_REFUND`, `SINGLE_REFUND`, `FULL_REFUND`. |
| `planType` | The commercial model: `SUBSCRIPTION`, `FIXED_TERM`, `TRANSACTION`, or `REDEMPTION` |
| `phaseType` | Where the consumer was in the pricing lifecycle: `FREE`, `DISCOUNT`, or `FULL_PRICE` |

**What was billed for**

| Field | Description |
| :- | :- |
| `productId` | Identifier for the product |
| `contentProviderIds` | The content provider or providers involved |
| `productTierKey` | The specific tier purchased, for example `NETFLIX_PREMIUM` |

**How much**

| Field | Description |
| :- | :- |
| `amount` | The transaction amount, in standard currency units — `19.99`, not `1999` |
| `currency` | ISO 4217 currency code |

## Charge Summary Reports

An aggregated monthly view for reporting and trend analysis rather than line-by-line reconciliation.

An example of the report:

| namespace\_name | partner\_name | transaction\_type | bill\_type | billing\_plan\_type | billing\_phase\_type | currency | transaction\_count | total\_amount | unique\_consumers |
| :- | :- | :- | :- | :- | :- | :- | :- | :- | :- |
| CUSTOMER\_1 | Customer\_1 | CHARGE | FIRST\_BILL | SUBSCRIPTION | FULL\_PRICE | USD | 91 | 150109 | 91 |
| CUSTOMER\_1 | Customer\_1 | CHARGE | PRO\_RATED\_CHARGE | SUBSCRIPTION | FULL\_PRICE | USD | 65 | 56276 | 38 |
| CUSTOMER\_1 | Customer\_1 | CHARGE | RENEWAL | SUBSCRIPTION | FULL\_PRICE | USD | 92 | 165308 | 92 |
| CUSTOMER\_1 | Customer\_1 | REFUND | PRO\_RATED\_REFUND | SUBSCRIPTION | FULL\_PRICE | USD | 34 | 49670 | 33 |

## Reading the reports

Amounts are in standard currency units. A charge of nineteen dollars ninety-nine appears as `19.99`. Always read `amount` together with `currency`.

Retries share a `billId`. If a renewal charge fails and is retried, each attempt is a separate row with the same `billId` and an incrementing `attempt` value. To count billing events rather than billing attempts, group by `billId`.

Line items repeat the transaction details. In the Detail Report, header information such as `transactionId` and `billEffectiveDate` is repeated on each line item row. De-duplicate on `transactionId` if you need one row per transaction.

## Related reports

<CardGroup cols={2}>
  <Card title="Billing plan report" icon="receipt" href="/billing-charging-reports/billing-plan-report">
    Report format for billing plans managed during a reporting period.
  </Card>

  <Card title="Forecast report" icon="chart-line-up" href="/billing-charging-reports/billing-forecast-report">
    Report format for future invoices due in the next month.
  </Card>
</CardGroup>