subscriber.past_due - Settlx

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

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.

Payload

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

Node.js

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 });
});

subscriber.activated — Payment confirmed; subscription renewed.
subscriber.expired — Grace period elapsed without payment. Revoke access.