---
title: "What does the RevenueDot webhook event BILLING_ISSUE mean?"
description: "BILLING_ISSUE is sent when a renewal charge fails. The store retries and access may continue in a grace period. Prompt the customer to fix their payment method."
url: https://revenuedot.app/docs/webhooks/webhook-billing-issue
---

# What does the RevenueDot webhook event BILLING_ISSUE mean?

The RevenueDot webhook event BILLING_ISSUE means a subscription's renewal payment failed and the store is retrying it.

## Quick facts

| | |
|---|---|
| Event | `BILLING_ISSUE` |
| Where | RevenueDot webhook (`event.type`), RevenueCat's webhook format |
| Sent to | Every enabled webhook whose filters match |
| Fields that are specific to it | `grace_period_expiration_at_ms` |
| What it means | A renewal charge failed. The store retries; access may continue in a grace period. |

## When it is sent

- The store could not charge the customer's payment method at renewal.
- `grace_period_expiration_at_ms` is always present and is null when there is no grace period.
- RevenueDot also sends a `CANCELLATION` with `cancel_reason: BILLING_ERROR`, as RevenueCat does.

## What your server should do

1. Keep access until `grace_period_expiration_at_ms` when it is set, otherwise follow the store's guidance for your app.
2. Ask the customer to update their payment method.
3. Expect `RENEWAL` if billing recovers, or `EXPIRATION` with `BILLING_ERROR` if the store gives up.
4. Deduplicate on `event.id`: deliveries can repeat, because anything but HTTP 200 is retried after 5, 10, 20, 40 and 80 minutes.

## Example

```javascript
import { createHmac, timingSafeEqual } from "node:crypto";

// X-RevenueCat-Webhook-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? "");
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${m[1]}.${rawBody}`).digest();
  return timingSafeEqual(expected, Buffer.from(m[2], "hex"));
}

// Sign a sample delivery the way RevenueDot does, then handle it.
const secret = "whsec_test_secret";
const rawBody = JSON.stringify({ api_version: "1.0", event: {"id":"66339910-3BFF-49F4-B873-D1283D673DE2","type":"BILLING_ISSUE","app_user_id":"user_1","product_id":"pro_monthly","grace_period_expiration_at_ms":1790900000000} });
const t = Math.floor(Date.now() / 1000);
const header = `t=${t},v1=${createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex")}`;

const seen = new Set(); // use a database table in production

function handle(rawBody, header) {
  if (!verify(rawBody, header, secret)) return "401 bad signature";
  const { event } = JSON.parse(rawBody);
  if (seen.has(event.id)) return "200 duplicate";
  seen.add(event.id);
  if (event.type !== "BILLING_ISSUE") return "200 ignored";
  const grace = event.grace_period_expiration_at_ms;
  return grace ? "keep access until " + new Date(grace).toISOString().slice(0, 10) + ", ask to fix payment" : "ask to fix payment";
}

console.log(handle(rawBody, header));
```

*Run-checked: `npm run check:snippets` runs this snippet with Node and compares its output with `ask to fix payment` (checked 2026-10-03).*

## How RevenueDot produces it

`diffSubscription` returns `BILLING_ISSUE` when a billing issue time appears on the stored purchase. Apple's `DID_FAIL_TO_RENEW` and Google's `SUBSCRIPTION_IN_GRACE_PERIOD` and `SUBSCRIPTION_ON_HOLD` all set it.

## Related

- [What does the RevenueDot webhook event RENEWAL mean?](https://revenuedot.app/docs/webhooks/webhook-renewal.md)
- [What does the RevenueDot webhook event EXPIRATION mean?](https://revenuedot.app/docs/webhooks/webhook-expiration.md)
- [What does the RevenueDot webhook event CANCELLATION mean?](https://revenuedot.app/docs/webhooks/webhook-cancellation.md)
- [BILLING_ISSUE fields and a recorded example payload](https://revenuedot.app/docs/api/webhook-events.md#billing_issue)
- [Webhooks guide: set up, verify and test](https://revenuedot.app/docs/guides/webhooks.md)

## Source

- [RevenueDot docs: which webhook events RevenueDot sends](https://revenuedot.app/docs/api/webhook-events)
- [RevenueCat: webhook event types and fields (the format RevenueDot follows)](https://www.revenuecat.com/docs/integrations/webhooks/event-types-and-fields)
- [RevenueDot core: events.ts (the event types and the rules that derive them)](https://github.com/revenuedot/revenuedot/blob/main/packages/core/src/events.ts)
- [RevenueDot server: services/events.ts (how an event is recorded and delivered)](https://github.com/revenuedot/revenuedot/blob/main/apps/server/src/services/events.ts)
- [RevenueDot server: services/purchases.ts (where store changes become events)](https://github.com/revenuedot/revenuedot/blob/main/apps/server/src/services/purchases.ts)

Checked: 2026-10-03