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

# Billing lifecycle notifications

> Billing lifecycle notifications sent by the DVM to help Resellers keep consumers informed about key subscription events.

## Overview

When you use the DVM's Billing & Charging capability, the DVM automatically sends billing lifecycle notifications to your system at key points in a consumer's subscription journey. These notifications are designed to help you proactively communicate with your consumers — informing them of upcoming charges, confirming successful payments, and alerting them when a charge has failed.

<Tip>
  Billing & Charging notifications are part of the optional **Billing & Charging capability**. They are separate from the standard DVM offer lifecycle notifications (provisioning, activation, cancellation) covered in the [Notifications](/notifications/overview) section.
</Tip>

***

## Notification types

There are six billing lifecycle notifications issued by the DVM:

<CardGroup cols={2}>
  <Card title="Upcoming Phase Change" icon="arrow-right-arrow-left">
    Sent in advance of a billing phase change — for example, a consumer transitioning from a free trial to a paid subscription. Gives Resellers time to notify consumers before they are first charged. `notificationReason: UPCOMING_PHASE_CHANGE`
  </Card>

  <Card title="Upcoming Renewal" icon="clock">
    Sent in advance of a scheduled renewal charge. Allows Resellers to remind consumers their subscription is about to renew and what they will be charged. `notificationReason: UPCOMING_RENEWAL`
  </Card>

  <Card title="Charge Succeeded" icon="circle-check">
    Sent after a charge has been successfully accepted by the Reseller's billing system. Confirms to the Reseller that the charge was collected and the subscription continues. `notificationReason: CHARGE_SUCCEEDED`
  </Card>

  <Card title="Charge Failed" icon="circle-xmark">
    Sent after a charge has failed following the full retry period. Signals that the DVM was unable to collect the charge and the Reseller may need to take action. `notificationReason: CHARGE_FAILED`
  </Card>

  <Card title="Refund Succeeded" icon="rotate-left">
    Sent after a pro-rated refund — issued on a mid-cycle downgrade or immediate cancellation — has been successfully processed by the Reseller's billing system. `notificationReason: REFUND_SUCCEEDED`
  </Card>

  <Card title="Refund Failed" icon="circle-xmark">
    Sent after a pro-rated refund has failed. Signals that the refund could not be processed and the Reseller may need to take action. `notificationReason: REFUND_FAILED`
  </Card>
</CardGroup>

***

## Default timing

Each notification has a default send window configured during onboarding. These can be adjusted based on your requirements.

| Notification | Default timing |
| - | - |
| `UPCOMING_PHASE_CHANGE` | 6 days before the phase change |
| `UPCOMING_RENEWAL` | 4 days before the renewal charge |
| `CHARGE_SUCCEEDED` | Sent immediately after charge accepted |
| `CHARGE_FAILED` | Sent after the full retry period has elapsed |
| `REFUND_SUCCEEDED` | Sent immediately after refund processed |
| `REFUND_FAILED` | Sent after the refund attempt has failed |

***

## Notification examples

<AccordionGroup>
  <Accordion title="Upcoming Phase Change">
    Sent ahead of a billing phase change — typically when a consumer is about to move from a free or discounted phase into full-price billing. The `upcomingPhase` object describes the phase they are moving into, and the `charge` object shows the amount they will be billed and when.

    This notification gives you advance notice to communicate the upcoming charge to your consumer before it is collected.

    ```json theme={null}
    {
      "notificationReason": "UPCOMING_PHASE_CHANGE",
      "consumerIdentifier": "bob@reseller.com",
      "billingPlan": {
        "billingPlanId": "a783c985-d3bd-4725-9b8e-a81152bb690d",
        "offer": {
          "offerId": "ce124847-08c4-4e0e-b917-9d5ef1240a69",
          "offerName": "Disney/Hulu - 6 months free",
          "consumerOfferId": "95bade98-3687-45b5-88b3-75d7b4283926"
        }
      },
      "upcomingPhase": {
        "sequence": 1,
        "duration": "EVERGREEN",
        "startTs": "2025-07-01T12:34:41.834Z"
      },
      "charge": {
        "status": "UPCOMING_CHARGE",
        "phaseSequence": 1,
        "currency": "USD",
        "amount": 1399,
        "assetScale": 2,
        "displayAmount": 13.99,
        "chargeTs": "2025-07-01T12:34:41.834Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="Upcoming Renewal">
    Sent ahead of a scheduled renewal charge, giving you advance notice to remind the consumer their subscription is about to renew and what they will be charged. The `charge` object contains the upcoming charge amount and the scheduled charge timestamp.

    ```json theme={null}
    {
      "notificationReason": "UPCOMING_RENEWAL",
      "consumerIdentifier": "bob@reseller.com",
      "billingPlan": {
        "billingPlanId": "a783c985-d3bd-4725-9b8e-a81152bb690d",
        "offer": {
          "offerId": "ce124847-08c4-4e0e-b917-9d5ef1240a69",
          "offerName": "Music Bundle - 6 months free",
          "consumerOfferId": "95bade98-3687-45b5-88b3-75d7b4283926"
        }
      },
      "charge": {
        "status": "UPCOMING_CHARGE",
        "phaseSequence": 1,
        "currency": "USD",
        "amount": 1399,
        "assetScale": 2,
        "displayAmount": 13.99,
        "chargeTs": "2025-07-01T12:34:41.834Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="Charge Succeeded">
    Sent after the  charge has been accepted by your billing system. The `charge.status` is `PAID`, confirming the payment was collected successfully. Use this notification to confirm to your consumer that their subscription has renewed.

    ```json theme={null}
    {
      "notificationReason": "CHARGE_SUCCEEDED",
      "consumerIdentifier": "bob@reseller.com",
      "billingPlan": {
        "billingPlanId": "a783c985-d3bd-4725-9b8e-a81152bb690d",
        "offer": {
          "offerId": "ce124847-08c4-4e0e-b917-9d5ef1240a69",
          "offerName": "Disney/Hulu - 6 months free",
          "consumerOfferId": "95bade98-3687-45b5-88b3-75d7b4283926"
        }
      },
      "charge": {
        "status": "PAID",
        "phaseSequence": 1,
        "currency": "USD",
        "amount": 1399,
        "assetScale": 2,
        "displayAmount": 13.99,
        "chargeTs": "2025-07-01T12:34:41.834Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="Charge Failed">
    Sent after the  charge has failed following the full retry period. The `charge.status` is `FAILED` and a `failureCode` is included, indicating why the charge could not be collected. Use this notification to alert your consumer and take any necessary action — such as prompting them to update their payment details.

    ```json theme={null}
    {
      "notificationReason": "CHARGE_FAILED",
      "consumerIdentifier": "bob@reseller.com",
      "failureCode": "USER_INSUFFICIENT_CREDIT",
      "billingPlan": {
        "billingPlanId": "a783c985-d3bd-4725-9b8e-a81152bb690d",
        "offer": {
          "offerId": "a02ba3fe-8cc2-4672-afd3-2cc511cc572f",
          "offerName": "Disney/Hulu - 6 months free",
          "consumerOfferId": "95bade98-3687-45b5-88b3-75d7b4283926"
        }
      },
      "charge": {
        "status": "FAILED",
        "phaseSequence": 1,
        "currency": "USD",
        "amount": 1399,
        "assetScale": 2,
        "displayAmount": 13.99,
        "chargeTs": "2025-07-01T12:34:41.834Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="Refund Succeeded">
    Sent after a refund has been successfully processed by your billing system. This notification is triggered when a consumer downgrades their product entitlement or immediately cancels their subscription mid-cycle, and the refund for the unused days in the billing period has been accepted. The `charge.status` is `PAID`.

    ```json theme={null}
    {
      "notificationReason": "REFUND_SUCCEEDED",
      "consumerIdentifier": "bob@reseller.com",
      "billingPlan": {
        "billingPlanId": "a783c985-d3bd-4725-9b8e-a81152bb690d",
        "offer": {
          "offerId": "ce124847-08c4-4e0e-b917-9d5ef1240a69",
          "offerName": "Disney/Hulu - 6 months free",
          "consumerOfferId": "95bade98-3687-45b5-88b3-75d7b4283926"
        }
      },
      "charge": {
        "status": "PAID",
        "phaseSequence": 1,
        "currency": "USD",
        "amount": 700,
        "assetScale": 2,
        "displayAmount": 7.00,
        "chargeTs": "2025-07-18T14:00:00.000Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="Refund Failed">
    Sent after a refund has failed. This notification is triggered when the DVM was unable to process a refund following a mid-cycle downgrade or cancellation. The `charge.status` is `FAILED` and a `failureCode` is included. Use this notification to investigate the failure and take any necessary action to ensure the consumer receives their refund.

    ```json theme={null}
    {
      "notificationReason": "REFUND_FAILED",
      "consumerIdentifier": "bob@reseller.com",
      "failureCode": "REFUND_PERIOD_EXPIRED",
      "billingPlan": {
        "billingPlanId": "a783c985-d3bd-4725-9b8e-a81152bb690d",
        "offer": {
          "offerId": "ce124847-08c4-4e0e-b917-9d5ef1240a69",
          "offerName": "Disney/Hulu - 6 months free",
          "consumerOfferId": "95bade98-3687-45b5-88b3-75d7b4283926"
        }
      },
      "charge": {
        "status": "FAILED",
        "phaseSequence": 1,
        "currency": "USD",
        "amount": 700,
        "assetScale": 2,
        "displayAmount": 7.00,
        "chargeTs": "2025-07-18T14:00:00.000Z"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Key fields explained

<ResponseField name="notificationReason" type="string" required>
  Identifies the type of billing notification. One of `UPCOMING_PHASE_CHANGE`, `UPCOMING_RENEWAL`, `CHARGE_SUCCEEDED`, `CHARGE_FAILED`, `REFUND_SUCCEEDED`, or `REFUND_FAILED`.
</ResponseField>

<ResponseField name="consumerIdentifier" type="string" required>
  The identifier of the consumer this notification relates to, as registered in the DVM.
</ResponseField>

<ResponseField name="billingPlan.billingPlanId" type="string" required>
  The unique identifier of the billing plan associated with this notification. Use this to locate the relevant subscription in your system.
</ResponseField>

<ResponseField name="billingPlan.offer" type="object" required>
  Contains the `offerId`, `offerName`, and `consumerOfferId` — identifying the specific offer and consumer subscription this notification relates to.
</ResponseField>

<ResponseField name="upcomingPhase" type="object">
  Present on `UPCOMING_PHASE_CHANGE` notifications only. Describes the phase the consumer is moving into, including the `sequence`, `duration`, and `startTs` of the new phase.
</ResponseField>

<ResponseField name="charge.status" type="string" required>
  The current status of the charge associated with this notification. `UPCOMING_CHARGE` for pre-event notifications, `PAID` for successful renewals, `FAILED` for failed renewals.
</ResponseField>

<ResponseField name="charge.displayAmount" type="number" required>
  The charge amount in standard currency units (e.g. `13.99`). Use this when displaying the charge amount to consumers. The raw `amount` field is in minor units scaled by `assetScale`.
</ResponseField>

<ResponseField name="charge.chargeTs" type="string" required>
  ISO 8601 timestamp of when the charge is scheduled (for upcoming notifications) or when it was due (for outcome notifications).
</ResponseField>

<ResponseField name="failureCode" type="string">
  Present on`CHARGE_FAILED`, and`REFUND_FAILED` notifications. Indicates why the charge or refund failed. Possible values include `USER_INSUFFICIENT_CREDIT`, `USER_SUSPENDED`, `USER_BARRED`, `USER_SPEND_LIMIT_EXCEEDED`, `REFUND_PERIOD_EXPIRED`, and others. See [Recurring Charges](/billing-and-charging/recurring-charges) for the full list of decline reason codes.
</ResponseField>

***

## What to do with these notifications

These notifications are the building blocks for keeping your consumers informed throughout their subscription lifecycle. Here are the recommended actions for each:

| Notification | Suggested Reseller action |
| - | - |
| `UPCOMING_PHASE_CHANGE` | Notify the consumer their trial or discount is ending and they will be charged the full price from the stated date |
| `UPCOMING_RENEWAL` | Send a renewal reminder to the consumer confirming what they will be charged and when |
| `CHARGE_SUCCEEDED` | Send a payment confirmation to the consumer confirming their subscription has renewed |
| `CHARGE_FAILED` | Alert the consumer that their payment failed and prompt them to resolve the issue (e.g. update payment details) to avoid service interruption |
| `REFUND_SUCCEEDED` | Confirm to the consumer that their refund has been processed following their downgrade or cancellation |
| `REFUND_FAILED` | Investigate the refund failure and take action to ensure the consumer receives their refund |