subscriber.enrolled - Settlx

When it fires

Immediately after a subscriber is enrolled — either via the Enroll Subscriber API or from the merchant dashboard. The subscriber’s status is pending and a first invoice has already been created.

What to do

Send the customer a welcome email with payment instructions
Show a “complete your subscription setup” prompt in your UI if they’re mid-onboarding
Do not provision access yet — the customer has not paid

Do not grant product access on subscriber.enrolled. Wait for subscriber.activated, which fires only after the first payment is confirmed on-chain.

Payload

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

Field	Type	Description
`event`	string	Always `subscriber.enrolled`
`subscriberId`	string	UUID of the subscriber record
`merchantId`	string	Your merchant account UUID
`planId`	string	UUID of the plan they enrolled into
`email`	string	Subscriber email address
`status`	string	Always `pending`
`currentPeriodEnd`	string	ISO 8601 — end of the current billing period
`gracePeriodEndsAt`	string	ISO 8601 — deadline to pay before expiry
`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.enrolled') {
    const { subscriberId, email, planId, gracePeriodEndsAt } = event;

    // Store the subscriber in your own database
    await db.subscribers.upsert({
      id: subscriberId,
      email,
      planId,
      status: 'pending',
    });

    // Send welcome email with payment instructions
    await sendEmail(email, 'welcome-subscription', {
      paymentDeadline: gracePeriodEndsAt,
    });

    // Do NOT provision access yet
  }

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

subscriber.activated — First payment confirmed. Provision access now.
subscriber.expired — Grace period elapsed without payment.