One-off charges

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

Pro-rated Upgrade Charge

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

Single Purchase

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 for how this appears in the renewal request.

Charge request examples

Pro-rated Upgrade Charge

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

{
  "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"
    }
  ]
}

Single Purchase

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.

{
  "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

string

required

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.

string

required

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.

integer

required

The total charge amount in minor currency units (e.g. 350 =

3.50 USD, `1499` =

14.99 USD).

array

required

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.

object

Present on pro-rated upgrade charges only. Contains the billingPeriod the proration was calculated against — useful for reconciliation. Not included on single purchase charges.

boolean / integer

required

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

{
  "requestId": "b1d24b6c-2e01-4071-8d25-dca97b5b04b5",
  "responseCode": "APPROVED"
}

Declined

{
  "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.

Welcome

Getting started

Partner management

Migrating to DVM

Offer management

Entitlement management

Billing & Charging

Notifications

Correlation and reconciliation

Dashboard and reporting

Partner care

Overview

When one-off charges are issued

Pro-rated Upgrade Charge

Single Purchase

Charge request examples

Key fields explained

How to respond

Approved

Declined

Decline reason codes

​Overview

​When one-off charges are issued

Pro-rated Upgrade Charge

Single Purchase

​Charge request examples

​Key fields explained

​How to respond

​Approved

​Declined

​Decline reason codes

Overview

When one-off charges are issued

Charge request examples

Key fields explained

How to respond

Approved

Declined

Decline reason codes