Introduction

This section defines the complete schemas for events related to Subscriptions on Webround Commerce. Subscription management allows for the automation of recurring sales by monitoring payment status, trial periods, and billing cycles synchronized with Stripe in real-time.

Why Listen to Subscription Events

Integrating subscription events is essential for:

• Access Management: Activating or revoking permissions and services based on the subscription status (e.g., active, past_due, canceled).
• Billing Synchronization: Monitoring period end dates (currentPeriodEnd) and managing scheduled renewals or cancellations.
• Customer Care: Providing immediate assistance for failed invoices by monitoring the latestInvoiceId.
• Trial Analysis: Tracking the start and end of trial periods to drive marketing conversion strategies.

Complete Events and Payload Table

Event	Payload Schema	JSON Example
subscription.created	Subscription Schema	Link
subscription.updated	Subscription Schema	Link
subscription.canceled	Subscription Schema	Link
subscription.deleted	Subscription Deleted Schema	Link

---

Subscription Schema (subscriptionDataSchema)

Field	Type	Notes
id	uuid	Required. Unique ID on Webround
stripeId	string	Required. Stripe subscription ID
storeCustomerId	uuid	Required. Internal customer ID
stripeCustomerId	string	Required. Stripe customer ID
status	string	Status (e.g., trialing, active, past_due, canceled)
activeSince	isoDate	Activation start date
currentPeriodEnd	isoDate	End date of the current billing cycle
cancelAtPeriodEnd	boolean	If true, the subscription will expire at the end of the period
latestInvoiceId	string	ID of the last generated invoice
trialStart/End	isoDate	Trial period dates

Subscription Example

{
    "envelopeId": "e1f2g3h4-i5j6-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "subscription.updated",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T23:45:00.000Z",
    "data": {
        "id": "s1b2c3d4-e5f6-4a5b-b6c7-d8e9f0a1b2c3",
        "stripeId": "sub_1QRsT2U3V4W5X6",
        "storeCustomerId": "c1d2e3f4-g5h6-4a5b-b6c7-d8e9f0a1b2c3",
        "stripeCustomerId": "cus_R987654321",
        "stripeAccountId": "acct_123456789",
        "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
        "status": "active",
        "activeSince": "2026-01-22T10:00:00.000Z",
        "currentPeriodEnd": "2026-03-22T10:00:00.000Z",
        "cancelAtPeriodEnd": false,
        "latestInvoiceId": "in_1QSx...",
        "latestInvoiceUrl": "https://invoice.stripe.com/...",
        "trialStart": null,
        "trialEnd": null,
        "createdAt": "2026-01-22T10:00:00.000Z",
        "updatedAt": "2026-02-22T23:45:00.000Z"
    },
    "eventId": "k1l2m3n4-o5p6-4a5b-b6c7-d8e9f0a1b2c3"
}

---

Subscription Deleted Schema (subscriptionDeletedSchema)

Field	Type	Notes
subscriptionId	uuid	Required. ID of the removed subscription

Subscription Deleted Example

{
    "envelopeId": "f2g3h4i5-j6k7-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "subscription.deleted",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T23:50:00.000Z",
    "data": {
        "subscriptionId": "s1b2c3d4-e5f6-4a5b-b6c7-d8e9f0a1b2c3"
    },
    "eventId": "l2m3n4o5-p6q7-4a5b-b6c7-d8e9f0a1b2c3"
}