Skip to main content

​
Overview

The DVM™ supports immediate product tier changes for active Consumer Offers. When a consumer upgrades or downgrades their subscription, the DVM™ updates their Entitlement in real time — changing their product tier instantly without interrupting their subscription. Rather than canceling and recreating the subscription, the existing Entitlement is updated with a new productKey pointing to the new product tier. This preserves the consumer’s subscription history, lifecycle dates, and audit records throughout the change.
Both upgrades and downgrades take effect immediately in the DVM™. If you have licensed the Billing & Charging capability, the DVM™ will also automatically calculate and issue a pro-rated charge or refund at the point of change. See Billing & Charging below.

​
How it works

A product tier change is initiated via a single PATCH /v1/entitlement request, containing the existing entitlementId and the productKey of the new tier. Either a Reseller or a Content Provider can initiate the request. Once the DVM™ receives the request, the following happens automatically:
1

Entitlement is updated immediately

The consumer’s Entitlement is updated to the new product tier. Access to the new tier’s features is applied instantly — the consumer does not need to take any action.
2

Consumer Offer is updated

The new productKey is propagated to the associated Consumer Offer, keeping the Consumer Offer and Entitlement in sync.
3

Reseller is notified

A PRODUCT_UPDATE notification is sent to the Reseller confirming the product tier change on the Entitlement. See Notifications for the full payload.
4

Pro-rated charge or refund is issued (if Billing & Charging is enabled)

The DVM™ Billing & Charging service calculates the relevant charge or refund based on the tier price difference and the remaining days in the billing cycle, and sends it immediately to the Reseller’s billing system.
5

Next renewal reflects the new tier price

At the end of the billing cycle, the renewal charge is calculated at the new tier price — accounting for any tier changes that occurred during the period.

​
API request

The same endpoint and request body is used for both upgrades and downgrades. The only difference is whether the new productKey represents a higher or lower tier.

​
Upgrade flow

An upgrade moves the consumer to a higher-priced product tier — for example, Standard → Premium. What happens:
  1. The DVM™ receives the PATCH request
  2. The Entitlement is immediately updated to the higher tier — the consumer gains access to the upgraded features instantly
  3. The price difference (ΔP) between the old and new tier is calculated
  4. The remaining days in the billing cycle are determined
  5. A pro-rated charge is calculated and sent immediately to the Reseller’s billing system
  6. At the next renewal, the consumer is charged the full price of the new tier
Pro-rated upgrade charges are only issued if you have licensed the Billing & Charging capability.
Example: A consumer on a Standard plan (£9.99/mo) upgrades to Premium (£14.99/mo) on day 15 of a 30-day billing cycle.
  • ΔP = £5.00
  • Remaining days = 16 (the change day is included for upgrade charges)
  • Pro-rated charge = £5.00 × (16/30) = £2.67
At the next renewal, the consumer is charged the full Premium price of £14.99.

​
Downgrade flow

A downgrade moves the consumer to a lower-priced product tier — for example, Premium → Standard. What happens:
  1. The DVM™ receives the PATCH request
  2. The Entitlement is immediately updated to the lower tier — the consumer’s access is adjusted to the new tier instantly
  3. The price difference (ΔP) between the old and new tier is calculated
  4. The remaining days in the billing cycle are determined (starting from the day after the change)
  5. A pro-rated refund is calculated and sent immediately to the Reseller’s billing system
  6. At the next renewal, the consumer is charged the full price of the new tier
Pro-rated downgrade refunds are only issued if you have licensed the Billing & Charging capability.
Example: A consumer on a Premium plan (£14.99/mo) downgrades to Standard (£9.99/mo) on day 15 of a 30-day billing cycle.
  • ΔP = £5.00
  • Remaining days = 15 (the change day is not refunded — refund starts from the following day)
  • Pro-rated refund = £5.00 × (15/30) = £2.50
At the next renewal, the consumer is charged the full Standard price of £9.99.

​
Billing & Charging

The pro-rated billing behavior described below applies only if you have licensed the optional Billing & Charging capability. If you manage billing externally, the DVM™ will still update the Entitlement and notify you of the change — but charge and refund calculation is your responsibility.
When a tier change occurs mid-cycle, the DVM™ Billing & Charging service automatically calculates and issues the appropriate financial adjustment: Both upgrades and downgrades take effect immediately. The key difference in how the pro-ration is calculated is:
  • Upgrades — the change day is included in the remaining day count (the consumer is charged from today)
  • Downgrades — the change day is excluded (the refund starts from the following day)
For a full explanation of how pro-ration amounts are calculated — including worked examples, the formula, and the day-counting rules — see Pro-ration.

​
Common use cases

  • Moving a consumer between product tiers based on their preference (e.g. Standard → Premium)
  • Allowing consumers to self-manage their tier directly via a Content Provider portal
  • Correcting a consumer’s product tier as part of a support action
  • Managing bulk tier migrations as part of a commercial offer change

​
What’s next?

Pro-ration

Learn how the DVM™ calculates pro-rated charges and refunds when a consumer changes product tier mid-cycle.

Notifications

See the PRODUCT_UPDATE notification payload sent to your system when a tier change completes.

Billing & Charging Notifications

See the PRO_RATED_CHARGE_SUCCEEDED and PRO_RATED_REFUND_SUCCEEDED notifications sent when billing adjustments are processed.