Skip to main content

​
Overview

A Renewal charge is a payment that repeats on a set schedule — monthly, annually, or otherwise. It’s linked to an ongoing subscription offer rather than a one-time purchase. When you create a Subscription Offer in the DVM, you define a billing plan that determines the subscription duration and how frequently it renews. The DVM uses this plan to drive all charge activity for that offer automatically — from the first charge when a consumer is provisioned, through every subsequent renewal for the lifetime of the subscription. Behind the scenes, the platform manages the full complexity of subscription billing, from renewals and plan changes to cancellations and payment retries. Charges stay accurate, billing stays on track, and consumers keep uninterrupted access to their services.

​
When renewal charges are issued

There are four charge scenarios your billing system will receive for a Subscription Offer:

First Bill

Issued when a consumer is first provisioned with an Offer and the billing plan starts.This is the consumer’s initial charge and marks the beginning of their subscription billing lifecycle.billType: FIRST_BILL

Renewal

Issued automatically at the end of each billing period, in line with the renewal frequency defined in the Offer plan.The consumer is charged the full subscription amount for the next period. billType: RENEWAL

Renewal after Upgrade

When a consumer has upgraded to a higher product tier mid-cycle, future renewal charge reflects the new, higher price.The charge lineItems will include both the original offer amount and an OFFER_ENTITLEMENT_TIER_DELTA reflecting the price difference. billType: RENEWAL

Renewal after Downgrade

When a consumer has downgraded to a lower product tier mid-cycle, future renewal charge reflects the new, lower price.The chargelineItems will include the original offer amount and a negative OFFER_ENTITLEMENT_TIER_DELTA for the price reduction. billType: RENEWAL
Mid-cycle upgrades also trigger an immediate pro-rated charge (billType: PRO_RATED_CHARGE) to collect the price difference for the remaining days in the current billing period. See Pro-ration for full details.

​
Charge request examples

Each scenario results in a POST /charges request to your billing system. Below are examples of what each looks like.
Sent when a consumer is first provisioned. The billType is FIRST_BILL and isRetry is false.
Sent at the end of each billing period. Identical structure to First Bill but with billType: RENEWAL and updated billingPeriod dates reflecting the new cycle.
When a consumer has upgraded their offer to a higher tier product, when the subscription renews, the total renewal charge amount includes the additional charge amount for the Upgrade. In this example the total renewal charge after the upgrade is $26.99.This total amount is itemised under lineItems:
  • OFFER = $19.99, which is the original Offer price amount
  • OFFER_ENTITLEMENT_TIER_DELTA = $7.00, which is the additional price for the upgrade
When a consumer has downgraded their offer to a lower tier product, when the subscription renews, the total renewal charge amount reflects the price reduction for the Downgrade. In this example the total renewal charge after the downgrade is $8.99.This total amount is itemised under lineItems:
  • OFFER = $19.99, which is the original Offer price amount
  • OFFER_ENTITLEMENT_TIER_DELTA = -$11.00, which is the price reduction for the downgrade

​
Key fields explained

These are the most important fields to understand across all charge request types:
​
string
required
Identifies what triggered the charge. One of FIRST_BILL (initial provisioning charge), RENEWAL (scheduled recurring charge), or PRO_RATED_CHARGE (mid-cycle upgrade charge).
​
string
required
A unique identifier for the bill. If a charge fails and is retried, all retry attempts share the same billId — only the chargeId changes. Use this for reconciliation.
​
string
required
A unique identifier for this specific charge transaction. Each attempt — including retries — gets its own chargeId. Echo this back in your response.
​
boolean / integer
required
isRetry: true means this is a retry of a previously failed charge. chargeAttempt tells you which attempt this is (0 = first attempt, 1 = first retry, etc.). Use billId to deduplicate against any prior attempt.
​
integer
required
The total charge amount in minor currency units (e.g. 1999 = $19.99 USD). For renewals after a tier change, this is the new net total, not the base price.
​
array
required
The itemised breakdown of the charge. A standard renewal has a single OFFER line item. Renewals after a tier change include an additional OFFER_ENTITLEMENT_TIER_DELTA line item — positive for upgrades, negative for downgrades. The entitlementId on this line item tells you which product entitlement changed.
​
object
required
The period this charge covers, including startDate, endDate, duration (ISO 8601 format, e.g. P1M for monthly), and phaseType (FREE, DISCOUNT, or FULL_PRICE). Useful for matching charges to subscription periods in your records.

​
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

​
Declined

​
Decline reason codes

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.

​
How we deal with failure

  • Restarts — Scheduled charges continue even if the service is temporarily unavailable. Once back online, processing resumes automatically with no missed payments.
  • Retries — If a charge is declined with a retryable reason code, Bango will automatically retry using a Fibonacci backoff schedule for up to 24 hours. See Billing Retry Schedule for full details.
  • External dependencies — Temporary delays in connected systems won’t cause scheduled charges to be missed.

​
Key takeaways

Revenue is protected

Retry logic and persistent scheduling mean that transient failures do not become lost revenue. The platform keeps trying until a charge succeeds or the plan is explicitly closed.

Accurate invoices

Every charge produces an invoice that reflects exactly what was charged and why. Pro-rated adjustments and tier changes are itemised clearly in lineItems, giving consumers and care teams a precise record to refer to.

Scales without limit

High volumes of renewals don’t affect the experience for other customers. Charges continue to be processed as expected.

Partners and teams stay informed

Key events in the recurring charge lifecycle — invoice issued, payment taken, payment failed, plan changed — are surfaced as real-time notifications. Resellers, operations, and customer-facing teams can all be kept in the loop automatically.