> ## Documentation Index
> Fetch the complete documentation index at: https://docs.settlx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# subscriber.past_due

> A new billing cycle has started and a renewal invoice has been created. Payment has not yet been received.

## When it fires

At the start of each new billing cycle for an `active` subscriber. Settlx creates a renewal invoice and transitions the subscriber to `past_due` until payment is confirmed.

This also fires when a first invoice is created for a new `pending` subscriber (if no trial period is configured).

***

## What to do

* Send a **payment reminder** email to the subscriber
* Optionally restrict non-critical features while the invoice is outstanding
* **Do not revoke access immediately** — the subscriber still has the full grace period to pay

<Info>
  The grace period is configured per plan (`gracePeriodDays`). The subscriber's `gracePeriodEndsAt` in the payload tells you exactly when access should be revoked if no payment arrives.
</Info>

***

## Payload

```json theme={null}
{
  "event": "subscriber.past_due",
  "subscriberId": "9f1e2d3c-4b5a-6789-abcd-ef0123456789",
  "merchantId": "f9e8d7c6-b5a4-3210-9876-543210fedcba",
  "planId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "customer@example.com",
  "status": "past_due",
  "currentPeriodEnd": "2026-06-19T00:00:00.000Z",
  "gracePeriodEndsAt": "2026-05-26T00:00:00.000Z",
  "timestamp": "2026-05-19T00:00:00.000Z"
}
```

| Field               | Type   | Description                                                |
| ------------------- | ------ | ---------------------------------------------------------- |
| `event`             | string | Always `subscriber.past_due`                               |
| `subscriberId`      | string | UUID of the subscriber record                              |
| `merchantId`        | string | Your merchant account UUID                                 |
| `planId`            | string | UUID of the plan                                           |
| `email`             | string | Subscriber email address                                   |
| `status`            | string | Always `past_due`                                          |
| `currentPeriodEnd`  | string | ISO 8601 — end of the billing period                       |
| `gracePeriodEndsAt` | string | ISO 8601 — deadline to pay before the subscription expires |
| `timestamp`         | string | ISO 8601 — when the event was generated                    |

***

## Handler example

```javascript Node.js theme={null}
app.post('/webhooks/settlx', express.raw({ type: 'application/json' }), async (req, res) => {
  verifySignature(req); // see Webhook Integration for verification code

  const event = JSON.parse(req.body);

  if (event.event === 'subscriber.past_due') {
    const { subscriberId, email, gracePeriodEndsAt } = event;

    await db.subscriptions.update(subscriberId, { status: 'past_due' });

    // Send payment reminder with deadline
    await sendEmail(email, 'payment-due', {
      payBy: gracePeriodEndsAt,
    });

    // Optional: show a banner in your UI but keep access active
    await db.users.setFlag(email, 'show_payment_banner', true);
  }

  res.status(200).json({ received: true });
});
```

***

## Related events

* [`subscriber.activated`](/webhook-events/subscriber-activated) — Payment confirmed; subscription renewed.
* [`subscriber.expired`](/webhook-events/subscriber-expired) — Grace period elapsed without payment. Revoke access.