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

# Upgrade or downgrade an offer

> Upgrade your consumer's product or subscription in the DVM.

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

<Info>
  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](#billing--charging) below.
</Info>

***

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Consumer Offer is updated">
    The new `productKey` is propagated to the associated Consumer Offer, keeping the Consumer Offer and Entitlement in sync.
  </Step>

  <Step title="Reseller is notified">
    A `PRODUCT_UPDATE` notification is sent to the Reseller confirming the product tier change on the Entitlement. See [Notifications](/offer-management/notifications) for the full payload.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

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

```text theme={null}
PATCH /v1/entitlement
```

```json theme={null}
{
  "entitlementId": "a212856a-4fd5-490b-a79c-f6dc950c2497",
  "productKey": "MUSIC_PREMIUM"
}
```

| Field | Description |
| - | - |
| `entitlementId` | The unique identifier of the Entitlement to be updated |
| `productKey` | The `productKey` of the new product tier — must be a valid tier configured on the Offer |

***

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

<Note>
  Pro-rated upgrade charges are only issued if you have licensed the Billing & Charging capability.
</Note>

**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

<Note>
  Pro-rated downgrade refunds are only issued if you have licensed the Billing & Charging capability.
</Note>

**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

<Info>
  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.
</Info>

When a tier change occurs mid-cycle, the DVM™ Billing & Charging service automatically calculates and issues the appropriate financial adjustment:

| Scenario | Billing action |
| - | - |
| Upgrade (Standard → Premium) | Immediate pro-rated **charge** for the remaining days at the higher tier price |
| Downgrade (Premium → Standard) | Immediate pro-rated **refund** for the unused days at the higher tier price |

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](/billing-and-charging/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?

<Card title="Pro-ration" icon="scale-balanced" href="/billing-and-charging/pro-ration" cta="Understand pro-ration" arrow="true">
  Learn how the DVM™ calculates pro-rated charges and refunds when a consumer changes product tier mid-cycle.
</Card>

<Card title="Notifications" icon="bell" href="/offer-management/notifications" cta="View notifications" arrow="true">
  See the `PRODUCT_UPDATE` notification payload sent to your system when a tier change completes.
</Card>

<Card title="Billing & Charging Notifications" icon="credit-card" href="/billing-and-charging/notifications" cta="View billing notifications" arrow="true">
  See the `PRO_RATED_CHARGE_SUCCEEDED` and `PRO_RATED_REFUND_SUCCEEDED` notifications sent when billing adjustments are processed.
</Card>