Billing lifecycle notifications

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.

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

Notification types

There are six billing lifecycle notifications issued by the DVM:

Upcoming Phase Change

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

Upcoming Renewal

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

Charge Succeeded

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

Charge Failed

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

Refund Succeeded

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

Refund Failed

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

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

Key fields explained

string

required

Identifies the type of billing notification. One of UPCOMING_PHASE_CHANGE, UPCOMING_RENEWAL, CHARGE_SUCCEEDED, CHARGE_FAILED, REFUND_SUCCEEDED, or REFUND_FAILED.

string

required

The identifier of the consumer this notification relates to, as registered in the DVM.

string

required

The unique identifier of the billing plan associated with this notification. Use this to locate the relevant subscription in your system.

object

required

Contains the offerId, offerName, and consumerOfferId — identifying the specific offer and consumer subscription this notification relates to.

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.

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.

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.

string

required

ISO 8601 timestamp of when the charge is scheduled (for upcoming notifications) or when it was due (for outcome notifications).

string

Present onCHARGE_FAILED, andREFUND_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 for the full list of decline reason codes.

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

Welcome

Getting started

Partner management

Migrating to DVM

Offer management

Eligibility

Entitlement management

Billing & Charging

Notifications

Correlation and reconciliation

Dashboard and reporting

Partner care

Overview

Notification types

Upcoming Phase Change

Upcoming Renewal

Charge Succeeded

Charge Failed

Refund Succeeded

Refund Failed

Default timing

Notification examples

Key fields explained

What to do with these notifications

​Overview

​Notification types

Upcoming Phase Change

Upcoming Renewal

Charge Succeeded

Charge Failed

Refund Succeeded

Refund Failed

​Default timing

​Notification examples

​Key fields explained

​What to do with these notifications

Overview

Notification types

Default timing

Notification examples

Key fields explained

What to do with these notifications