Subscription Status Webhooks

Receive real-time updates about subscription lifecycle events

The Subscription Status Webhook notifies your server whenever a subscriber’s status changes, including new subscriptions, renewals, grace transitions, cancellations, reactivations, and quantity/package updates.

Use this webhook to keep your internal user access logic, CRM, analytics systems, and billing dashboards fully synchronized with Zotlo lifecycle events.

When This Is Triggered

You will receive a callback when any of the following events occur:

Event Type	Description
newSubscriber	A new subscription has been created (trial or paid)
renewal	A subscription has successfully renewed
activeToGrace	Renewal failed → subscriber moved to grace period
graceToActive	A retry succeeded → subscriber returned to active
graceToPassive	All retries failed → subscription became passive
cancel	Subscription canceled by user, merchant, or system
reactivate	A canceled subscription was reactivated
package_update	The subscriber upgraded or downgraded their plan

Webhook Structure

Every Subscription Status webhook contains two main sections:

• queue → event metadata

• parameters → full subscription profile and changes

Example Payload

{
  "queue": {
    "type": "SubscriberUpdate",
    "eventType": "newSubscriber",
    "requestID": "5a33b022-b877-4888-9eed-89a294640a3c",
    "createDate": {
      "date": "2024-05-13 08:18:22.978000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "appId": 1651
  },
  "parameters": {
    "profile": {
      "status": "active",
      "realStatus": "active",
      "subscriberId": "[email protected]",
      "subscriptionId": 10414,
      "subscriptionType": "trial",
      "startDate": "2024-05-13 08:18:22",
      "expireDate": "2024-05-16 08:18:22",
      "renewalDate": "2024-05-16 08:18:22",
      "package": "paypal_test",
      "country": "US",
      "phoneNumber": null,
      "language": "en",
      "originalTransactionId": "bfe87fcd-72f7-4902-88ba-b2695c829590",
      "lastTransactionId": "bfe87fcd-72f7-4902-88b2695c829590",
      "subscriptionPackageType": "single",
      "cancellation": null,
      "customParameters": {
        "clientUuid": "5adf7031-34f3-402b-88fc-2fe8cc87d0af"
      },
      "quantity": 1,
      "pendingQuantity": 0,
      "renewalFetchCount": 0
    },
    "package": {
      "packageId": "pro_test",
      "price": 1,
      "currency": "USD",
      "packageType": "subscription",
      "name": "pro_test",
      "subscriptionPackageType": "single",
      "bundlePackages": []
    },
    "newPackage": null,
    "card": {
      "cardNumber": "41111111****1111",
      "expireDate": "06/2024",
      "tokenId": 11082
    },
    "customer": null,
    "package_update": 0
  }
}

Field Reference

queue

Metadata describing the event:

Field	Description
queue.type	Always SubscriberUpdate
queue.eventType	Type of subscription event (renewal, cancel, newSubscriber, etc.)
queue.requestID	Unique identifier for this webhook call
queue.createDate	Timestamp of the event
queue.appId	ID of the project where the transaction occurred

parameters.profile

Current subscription profile and lifecycle state:

Field	Description
status	Current status → active, grace, or passive
realStatus	The true state (canceled users return passive immediately even if cycle not ended)
subscriptionType	trial or paid
subscriberId	Unique identifier sent during purchase (email or phone)
subscriptionId	Internal Zotlo subscription record ID
startDate	Subscription start date
expireDate	Access expiration date
renewalDate	Scheduled next billing attempt
package	Current packageId
originalTransactionId	First purchase transactionId
lastTransactionId	Latest successful payment transactionId
country	Subscriber’s country
language	Subscriber’s preferred language
cancellation	Cancellation details if subscription was canceled
quantity	Current billable quantity
pendingQuantity	Quantity change that will apply on next renewal
customParameters	Custom metadata sent during purchase

parameters.package

Information about the package currently active or last used.

Field	Description
packageId	ID of the package
price	Base price
currency	Currency
packageType	subscription / one-time
name	Display name

parameters.newPackage

Returned when a downgrade has occurred. null if no plan change happened.

parameters.card

Masked card details, if a card is used.

Field	Description
cardNumber	Masked card
expireDate	Expiry date
tokenId	Tokenized card ID

parameters.customer

Customer details (if applicable). May return null.

parameters.package_update

Indicates whether this event was triggered after a plan change:

• 1 → package was updated

• 0 → no change

How to Use This Webhook

Typical use cases:

• Update subscription status in your backend

• Grant or revoke access based on status or realStatus

• Trigger email notifications (trial ending, renewal success, cancellation)

• Update CRM / marketing automation

• Sync billing data to analytics systems

• Automate upgrade/downgrade flows

Logic for Access Control

Use realStatus for determining true access logic when cancellations are involved:

• status = active but realStatus = passive → user canceled; access decision depends on your rules

• status = grace → payment failed; retry active; your app decides access

• status = passive → subscription ended