> ## 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.
# One-off charges
> One-off and non-recurring charges in the DVM.
## Overview
A one-off charge is a single payment tied to a specific event or action in the subscription lifecycle — rather than a recurring scheduled renewal. Once processed, the transaction is complete with no future billing obligations attached to it.
One-off charges serve a wide range of commercial scenarios. Anything where a consumer makes a payment not tied to a recurring schedule fits this model:
* **Balance top-up** — A consumer adds funds to their prepaid balance. The payment is processed and the credit is applied to their account straight away.
* **Ad-hoc purchase** — A customer buys a product or add-on with a single payment. The payment is processed, the purchase is confirmed, and the customer gets access right away.
* **Adjustment** — Sometimes you need to charge a customer for something outside their usual subscription. A one-time charge lets you do that quickly and simply, without affecting their existing service.
* **Partner-initiated charge** — Partners can create one-time charges for their customers through the platform, processed and tracked just like any other transaction.
* **Pro-rated upgrade** — When a consumer upgrades their product entitlement mid-cycle, the DVM automatically issues a pro-rated charge for the price difference covering the remaining days in the billing period.
The DVM issues one-off charges to your billing system via the same `POST /charges` endpoint used for renewal charges. The key difference is the `billType` value, which identifies the nature of the charge.
***
## When one-off charges are issued
When a consumer upgrades to a higher product tier mid-cycle, a pro-rated charge is issued immediately to collect the price difference for the remaining days in the current billing period. `billType: PRO_RATED_CHARGE`
A one-time payment for a specific product, service, or add-on outside of a subscription — such as a balance top-up, ad-hoc purchase, or partner-initiated charge. `billType: SINGLE_CHARGE`
The pro-rated upgrade charge is the only one-off charge currently issued automatically by the DVM. Single purchase charges are available for partner-initiated use cases.
At the next renewal following an upgrade, the recurring charge will reflect the new higher-tier price. See [Recurring Charges](/billing-and-charging/recurring-charges) for how this appears in the renewal request.
***
## Charge request examples
When a consumer upgrades their product entitlement to a higher tier mid-cycle, the DVM immediately issues a pro-rated charge for the price difference for the remaining days in the billing period.
In this example the consumer has upgraded to `NETFLIX_PREMIUM` on 15 February, part way through their February billing cycle. The pro-rated charge amount is the price delta for the remaining days.
This amount is itemised under `lineItems`:
* `OFFER_TIER_CHANGE_PRORATION =` the pro-rated price difference for the upgrade, covering the remaining days in the current billing period
```json theme={null}
{
"requestId": "b1d24b6c-2e01-4071-8d25-dca97b5b04b5",
"billEffectiveDate": "2026-02-15T11:16:45.000Z",
"billType": "PRO_RATED_CHARGE",
"billId": "160cb4e5-0cf5-451c-a72b-3ed41794f00a",
"chargeId": "19e3e3d4-6f8c-4cc9-bf18-6547a7bc977d",
"chargeAttempt": 0,
"isRetry": false,
"amount": 350,
"currency": "USD",
"consumer": {
"consumerIdentifier": "RFBNZ2MU3Y35OA5GNNNGETK6JTEVRYVB",
"billingIdentifier": "BWNMJXEDAO7HTK6Q4SBAOEJMPGURUB3K"
},
"resourceType": "CONSUMER_OFFER",
"consumerOffer": {
"consumerOfferId": "338d31e1-a289-40dd-beff-ab41c1fc5f51",
"offerId": "7560fca0-d8a9-4124-a172-924debec874e",
"entitlements": [
{
"entitlementId": "b0163d06-1fa3-4c9b-a298-29635ca7151d",
"contentProviderId": "NETFLIX",
"productId": "Netflix",
"productTierKey": "NETFLIX_PREMIUM"
}
]
},
"billingDetails": {
"planType": "SUBSCRIPTION",
"billingPeriod": {
"phaseType": "FULL_PRICE",
"duration": "P1M",
"startDate": "2026-02-01T01:00:00.000Z",
"endDate": "2026-03-01T00:59:59.999Z"
}
},
"lineItems": [
{
"lineItemType": "OFFER_TIER_CHANGE_PRORATION",
"quantity": 1,
"amount": 350,
"currency": "USD",
"entitlementId": "b0163d06-1fa3-4c9b-a298-29635ca7151d"
}
]
}
```
A single purchase charge is a one-time payment for a product or service outside of a subscription plan — such as a balance top-up, ad-hoc purchase, adjustment, or partner-initiated charge.
Unlike consumer offer charges, a single purchase does not include `consumerOffer` or `billingDetails` fields. The `resourceType` is `SINGLE_PURCHASE` and the `lineItems` use `lineItemType: SINGLE_CHARGE` with a human-readable `description`.
```json theme={null}
{
"requestId": "c3f92a11-7d45-4e8b-b012-1a2b3c4d5e6f",
"billEffectiveDate": "2026-03-10T09:00:00.000Z",
"billType": "SINGLE_CHARGE",
"billId": "d4e83b22-8e56-4f9c-c123-2b3c4d5e6f7a",
"chargeId": "e5f94c33-9f67-4g0d-d234-3c4d5e6f7a8b",
"chargeAttempt": 0,
"isRetry": false,
"amount": 1499,
"currency": "USD",
"consumer": {
"consumerIdentifier": "RFBNZ2MU3Y35OA5GNNNGETK6JTEVRYVB",
"billingIdentifier": "BWNMJXEDAO7HTK6Q4SBAOEJMPGURUB3K"
},
"resourceType": "SINGLE_PURCHASE",
"lineItems": [
{
"lineItemType": "SINGLE_CHARGE",
"quantity": 1,
"amount": 1499,
"currency": "USD",
"description": "Premium Pass"
}
]
}
```
***
## Key fields explained
Identifies the type of one-off charge. `PRO_RATED_CHARGE` is issued automatically by the DVM when a consumer upgrades mid-cycle. `SINGLE_CHARGE` is used for standalone one-time purchases.
Tells you what is being charged. `CONSUMER_OFFER` for pro-rated upgrade charges (tied to a subscription offer). `SINGLE_PURCHASE` for standalone one-time purchases not linked to an offer.
The total charge amount in **minor currency units** (e.g. `350` = $3.50 USD, `1499` = $14.99 USD).
The itemised breakdown of the charge. For pro-rated upgrade charges, `lineItemType` is `OFFER_TIER_CHANGE_PRORATION` and includes the `entitlementId` of the upgraded product. For single purchases, `lineItemType` is `SINGLE_CHARGE` and includes a human-readable `description` of the item.
Present on pro-rated upgrade charges only. Contains the `billingPeriod` the proration was calculated against — useful for reconciliation. Not included on single purchase charges.
`isRetry: true` indicates this is a retry of a previously failed charge. `chargeAttempt` gives the attempt number (`0` = first attempt, `1` = first retry, etc.). Use `billId` to deduplicate against prior attempts.
***
## How to respond
Your billing system must respond to every charge request with a `200` status and a JSON body indicating whether the charge was processed or declined.
### Approved
```json theme={null}
{
"requestId": "b1d24b6c-2e01-4071-8d25-dca97b5b04b5",
"responseCode": "APPROVED"
}
```
### Declined
```json theme={null}
{
"requestId": "b1d24b6c-2e01-4071-8d25-dca97b5b04b5",
"responseCode": "DECLINED",
"reason": "USER_INSUFFICIENT_CREDIT",
"reasonDescription": "Insufficient credit"
}
```
### Decline reason codes
| Reason code | Meaning | Bango will retry? |
| - | - | - |
| `DENIED` | General denial — no more specific reason available | ❌ No |
| `USER_INVALID` | Consumer identifier not recognised or account closed | ❌ No |
| `USER_BARRED` | Consumer is permanently barred from this payment method | ❌ No |
| `USER_SUSPENDED` | Consumer account is temporarily suspended | ✅ Yes |
| `USER_NOT_ENABLED` | Consumer not yet enabled for this payment method | ✅ Yes |
| `USER_INSUFFICIENT_CREDIT` | Consumer has insufficient funds or credit | ✅ Yes |
| `USER_SPEND_LIMIT_EXCEEDED` | Consumer has hit a spend limit (daily/weekly/monthly) | ✅ Yes |
| `ALREADY_IN_PROGRESS` | A charge with the same `chargeId` is already being processed | ⏳ Bango will wait before retrying |
Always return a `reason` when declining. Without it, Bango may treat the response as an error and apply retry logic regardless of the actual decline reason.