Subscription Status Changed

subscription-status-changed follows a buyer's subscription to one of your plans. Despite its name, it also fires when a billing cycle moves nextPaymentDate forward without changing status.

When it fires

The buyer subscribes. The subscription is created in CREATING while its first checkout is paid.
The first checkout is paid: the subscription becomes ACTIVE, or TRIAL if the plan has a trial period.
The first checkout fails or expires: the subscription becomes FAILED.
A billing cycle is charged and nextPaymentDate moves to the next cycle. A subscription in TRIAL becomes ACTIVE at its first paid cycle.
Every charge attempt for a cycle has failed: the subscription becomes OVERDUE.
You cancel it with Cancel Subscription, or the buyer cancels it: the subscription becomes CANCELLED.

What to do

`data.status`	Suggested action
`CREATING`	No action. Wait for the first checkout.
`TRIAL`, `ACTIVE`	Grant or keep access. `nextPaymentDate` is the next billing date.
`FAILED`	The buyer was not charged and the subscription never started. Ask them to subscribe again, with another payment method if needed.
`OVERDUE`	Payment failed for a cycle after all retries. Suspend access or contact the buyer. The subscription is not charged again.
`CANCELLED`	Remove access at the end of the period you choose. The subscription is not charged again.

Payload

data is the subscription as Get Subscription describes it, read when the webhook is sent. Fields with no value are omitted. Amounts use the Money object.

Field	Type	Description
`id`	string	Subscription ID, for example `R-01JD5A1C3E5G7J9L1N3Q5S7U9W`.
`status`	string	`CREATING`, `TRIAL`, `ACTIVE`, `FAILED`, `OVERDUE` or `CANCELLED`. See the table above.
`merchantId`	string	Your merchant ID.
`userId`	string	ID of the buyer who subscribed.
`userEmail`	string	Buyer's email address.
`userReferenceId`	string	Your own reference for the buyer.
`subscriptionPlanId`	string	ID of the plan subscribed to.
`subscriptionPlanName`	string	Name of that plan.
`subscribeDate`	string	When the buyer subscribed, in ISO 8601 UTC.
`amount`	Money	Amount charged each billing cycle.
`schedule`	object	Billing schedule. `interval` is `daily`, `weekly`, `monthly` or `yearly`. `intervalCount` is how many intervals pass between charges, for example `2` with `monthly` for every two months.
`nextPaymentDate`	string	Date of the next charge, as `YYYY-MM-DD`.
`checkoutInstrumentId`	string	ID of the card or account charged each cycle.
`instrumentType`	string	Type of that instrument, for example `payment-card-3`. Same values as `enabledCheckoutInstruments` on checkout-status-changed.
`citCheckoutId`	string	ID of the first checkout, the one the buyer paid when subscribing.
`authorizationCode`	string	Authorization code the card issuer returned when it approved that first checkout. Set once it is paid; omitted when no code was returned.
`termsOfServiceUrl`	string	Your terms of service, shown to the buyer.
`privacyPolicyUrl`	string	Your privacy policy, shown to the buyer.
`auditInfo`	object	`createdAt`, `updatedAt` (ISO 8601 UTC), `createdBy` and `updatedBy`.

Example

The full request body Payment Labs sends:

{
  "payorId": "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
  "event": "subscription-status-changed",
  "timestamp": "2026-04-01T00:10:42.307Z",
  "data": {
    "id": "R-01JD5A1C3E5G7J9L1N3Q5S7U9W",
    "merchantId": "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
    "userId": "U-01JBX5K7M9P1Q3R5S7T9V1W3X5",
    "userEmail": "[email protected]",
    "userReferenceId": "member-3307",
    "subscriptionPlanId": "RD-01JD49X1Z3B5D7F9H1K3M5P7R9",
    "subscriptionPlanName": "Monthly membership",
    "subscribeDate": "2026-03-01T09:14:55.000Z",
    "checkoutInstrumentId": "SI-01JD3K7M9P1R3T5V7X9Z1B3D5F",
    "instrumentType": "payment-card-3",
    "citCheckoutId": "S-01JD5A0B2D4F6H8K0M2P4R6T8V",
    "authorizationCode": "A1B2C3",
    "schedule": {
      "interval": "monthly",
      "intervalCount": 1
    },
    "amount": {
      "value": 19.99,
      "wholeValue": 1999,
      "currency": "USD",
      "formattedValue": "$19.99",
      "digits": 2
    },
    "status": "ACTIVE",
    "nextPaymentDate": "2026-05-01",
    "auditInfo": {
      "createdAt": "2026-03-01T09:14:55.000Z",
      "createdBy": "U-01JBX5K7M9P1Q3R5S7T9V1W3X5",
      "updatedAt": "2026-04-01T00:10:41.950Z",
      "updatedBy": "U-01JBX5K7M9P1Q3R5S7T9V1W3X5"
    },
    "termsOfServiceUrl": "https://shop.example.com/terms",
    "privacyPolicyUrl": "https://shop.example.com/privacy"
  }
}