--- updatedAt: 2026-03-10T19:29:04.000Z agentTools: projectIndex: https://docs.pelcro.com/v2.4/llms.txt --- # Subscriptions Receive notifications for subscription lifecycle events including creation, renewal, cancellation, and expiration. ## Overview Subscription webhooks notify your application about every stage of the subscription lifecycle — from creation and renewal to cancellation and expiration. These are the most commonly used Pelcro webhooks and carry a deeply nested payload including customer, plan, invoice, and payment method details. *** ## Use Cases * Provision or revoke access when subscriptions are created, renewed, or expire * Trigger dunning flows when subscriptions are canceled or past due * Sync subscription status to your CMS or access control system * Alert customers before their trial ends * Track gift subscription fulfillment * Monitor churn risk with prediction scores *** ## Events | Event | Description | | ------------------------------------------------------------------ | --------------------------------------------------- | | [`subscription.created`](#subscriptioncreated) | A new subscription was created | | [`subscription.updated`](#subscriptionupdated) | A subscription was modified | | [`subscription.changed`](#subscriptionchanged) | A subscription was changed (e.g., plan switch) | | [`subscription.canceled`](#subscriptioncanceled) | A subscription was canceled | | [`subscription.renewed`](#subscriptionrenewed) | A subscription was renewed for a new billing period | | [`subscription.expired`](#subscriptionexpired) | A subscription has expired | | [`subscription.trial_will_end`](#subscriptiontrial_will_end) | A subscription's trial period is about to end | | [`subscription.gift_notification`](#subscriptiongift_notification) | A gift subscription notification was sent | *** ## subscription.created ### Triggered When * A customer subscribes via the SDK * A subscription is created via the Core API * A subscription is created from the Platform > **Note:** This event is **not** fired during data migrations (when the subscription is flagged as migrating). ### Payload ```json { "type": "subscription.created", "id": "evt_a1B2c3D4e5F6g7H8i9J0k1L2", "created": 1704067200, "data": { "object": { "object": "subscription", "id": 100001, "address_id": 200001, "address_shipping": { "object": "address", "id": 200001, "city": "Springfield", "company": null, "country": "US", "country_name": "United States", "created_at": "2025-06-15T10:00:00.000000Z", "department": null, "first_name": "Jane", "is_default": true, "last_name": "Doe", "line1": "123 Main Street", "line2": null, "postal_code": "62704", "salutation": null, "site_ids": [1], "state": "IL", "state_name": "Illinois", "title": null, "type": "shipping", "updated_at": "2025-06-15T10:00:00.000000Z" }, "agency_id": null, "auto_renew": true, "backdate_start_date": null, "billing": 1, "billing_cycle_anchor": "2026-01-01T12:00:00.000000Z", "campaign_id": null, "campaign_key": null, "cancel_at": null, "cancel_at_period_end": 0, "cancel_reason": null, "canceled_at": null, "canceled_by_email": null, "canceled_by_type": null, "churn_prediction_created_at": null, "churn_prediction_updated_at": null, "churn_risk_bucket": null, "churn_risk_score": null, "coupon": null, "created": "2026-01-01T12:00:00.000000Z", "current_period_end": "2026-02-01T12:00:00.000000Z", "current_period_start": "2026-01-01T12:00:00.000000Z", "customer": { "object": "customer", "id": 300001, "balance": 0, "billing_email": null, "created": "2025-06-15T10:00:00.000000Z", "currency": "usd", "default_source": { "object": "source", "id": 400001, "object_id": "pm_XXXXXXXXXXXXXXXXXXXX", "object_gateway": "stripe", "brand": "visa", "country": "US", "exp_month": 12, "exp_year": 2028, "funding": "credit", "last4": "4242", "site_ids": [1] }, "delinquent": false, "display_name": null, "email": "customer@example.com", "email_confirm": 0, "email_hardbounce": false, "first_name": "Jane", "has_password": 1, "language": null, "last_active_at": 1704067190, "last_login_method": "email", "last_name": "Doe", "mail_marketing": null, "metadata": null, "object_id": "cus_XXXXXXXXXXXXXX", "organization": null, "password_last_updated_at": null, "phone": null, "phone_confirm": null, "salutation": null, "site_ids": [1], "tele_marketing": null, "title": null, "username": null }, "days_until_due": null, "default_source": { "object": "source", "id": 400001, "object_id": "pm_XXXXXXXXXXXXXXXXXXXX", "object_gateway": "stripe", "brand": "visa", "country": "US", "exp_month": 12, "exp_year": 2028, "funding": "credit", "last4": "4242", "site_ids": [1] }, "default_tax_rates": null, "ended_at": null, "expires_at": null, "gift_code": null, "gift_donor_subscription_id": null, "gift_message": null, "gift_notification_sent": 0, "gift_recipient_email": null, "gift_recipient_first_name": null, "gift_recipient_last_name": null, "gift_start_date": null, "is_gift_donor": 0, "is_gift_recipient": 0, "is_redeemed": null, "latest_invoice": { "object": "invoice", "id": 500001, "...": "full invoice object (see Invoice Webhooks)" }, "metadata": null, "object_id": "sub_XXXXXXXXXXXXXXXXXXXXXXXX", "plan": { "id": 600001, "product_id": 700001, "parent_plan_id": null, "object_id": "plan_XXXXXXXXXXXXXX", "active": "active", "type": "regular", "amount": 1999, "recognized_revenue_type": "time", "renewal_strategy": null, "auto_renew": true, "available_online": true, "allow_send_invoice": true, "auto_uncollectible_days": null, "invoice_upcoming_notification": null, "currency": "usd", "countries": null, "entitlements": null, "interval": "month", "interval_count": 1, "is_imported": false, "is_hidden": false, "is_donation": false, "metadata": null, "member_seat_capacity": null, "nickname": "Monthly Premium", "name_internal": null, "refundable": false, "shipments_per_interval": null, "description": "Monthly access to premium content.", "trial_period_days": 0, "ip_addresses": null, "domains": null, "created_at": "2025-12-15T10:00:00.000000Z", "updated_at": "2025-12-15T10:00:00.000000Z", "site_ids": [1], "product": { "id": 700001, "object_id": "prod_XXXXXXXXXXXXXX", "type": "service", "active": "active", "address_required": null, "countries": null, "description": "Premium content subscription.", "entitlements": null, "is_imported": null, "is_hidden": null, "language": null, "livemode": true, "metadata": null, "name": "Premium Content", "name_internal": null, "shippable": false, "statement_descriptor": null, "created_at": "2025-12-15T10:00:00.000000Z", "updated_at": "2025-12-15T10:00:00.000000Z", "site_ids": [1] } }, "quantity": 1, "recommended_plan_id": null, "renews_at": 1738411200, "schedules": null, "shipments_remaining": null, "shipments_suspended_until": null, "shipments_undeliverable": false, "shipping_address": { "...": "same as address_shipping (deprecated)" }, "site_id": 1, "source": null, "start_date": "2026-01-01T12:00:00.000000Z", "status": "active", "trial_end": null, "trial_start": null } } } ``` *** ## subscription.updated ### Triggered When * Any subscription attribute is saved (the most frequently fired subscription event) * A subscription is updated via the Core API or from the Platform * A subscription is updated during an agency import ### Payload The payload includes a `previous_attributes` object containing only the fields that changed. ```json { "type": "subscription.updated", "id": "evt_b2C3d4E5f6G7h8I9j0K1l2M3", "created": 1704153600, "data": { "object": { "object": "subscription", "id": 100001, "...": "full subscription object (same structure as subscription.created)" }, "previous_attributes": { "current_period_start": "2025-12-01T12:00:00.000000Z", "current_period_end": "2026-01-01T12:00:00.000000Z", "billing_cycle_anchor": "2025-12-01T12:00:00.000000Z" } } } ``` *** ## subscription.changed ### Triggered When * A subscription's plan is changed (upgrade or downgrade) ### Payload The payload may include a `previous_attributes` object containing the fields that changed. ```json { "type": "subscription.changed", "id": "evt_c3D4e5F6g7H8i9J0k1L2m3N4", "created": 1704240000, "data": { "object": { "object": "subscription", "id": 100001, "...": "full subscription object with the new plan and updated fields" }, "previous_attributes": { "plan": { "id": 600001, "nickname": "Monthly Basic", "amount": 999 } } } } ``` *** ## subscription.canceled ### Triggered When * A customer cancels their subscription via the SDK * A subscription is canceled via the Core API or from the Platform * A subscription is immediately canceled (`cancelNow`) with or without a refund * A subscription schedule triggers a cancellation ### Payload When a subscription is canceled, the `canceled_at`, `canceled_by_email`, `canceled_by_type`, and `cancel_reason` fields are populated. If the subscription will remain active until the end of the billing period, `cancel_at_period_end` is `1` and `status` remains `"active"`. ```json { "type": "subscription.canceled", "id": "evt_d4E5f6G7h8I9j0K1l2M3n4O5", "created": 1704326400, "data": { "object": { "object": "subscription", "id": 100001, "...": "full subscription object", "auto_renew": false, "cancel_at_period_end": 1, "cancel_reason": "Too expensive", "canceled_at": "2026-01-04T12:00:00.000000Z", "canceled_by_email": "admin@example.com", "canceled_by_type": "Admin/Collaborator", "expires_at": 1738411200, "status": "active" } } } ``` *** ## subscription.renewed ### Triggered When * A subscription is renewed at the end of a billing period by the [Pelcro Billing Engine](https://docs.pelcro.com/docs/our-billing-engine) * A subscription is manually renewed via the Core API, SDK, or Platform * A canceled or expired subscription is reactivated/restarted (Pelcro-owned subscriptions) * A campaign-driven renewal is processed * An agency import renews a subscription ### Payload ```json { "type": "subscription.renewed", "id": "evt_e5F6g7H8i9J0k1L2m3N4o5P6", "created": 1706832000, "data": { "object": { "object": "subscription", "id": 100001, "...": "full subscription object with updated billing period dates", "current_period_start": "2026-02-01T12:00:00.000000Z", "current_period_end": "2026-03-01T12:00:00.000000Z", "status": "active" } } } ``` *** ## subscription.expired ### Triggered When * A subscription's billing period has ended and the [Pelcro Billing Engine](https://docs.pelcro.com/docs/our-billing-engine) expiration workflow runs * A subscription is immediately canceled (`cancelNow`) — this fires both `subscription.canceled` and `subscription.expired` back-to-back ### Payload ```json { "type": "subscription.expired", "id": "evt_f6G7h8I9j0K1l2M3n4O5p6Q7", "created": 1738411200, "data": { "object": { "object": "subscription", "id": 100001, "...": "full subscription object", "auto_renew": false, "cancel_at_period_end": 0, "ended_at": "2026-02-01T12:00:00.000000Z", "status": "canceled" } } } ``` *** ## subscription.trial\_will\_end ### Triggered When * A subscription's trial period is approaching its end date (a scheduled job scans for trials ending soon and fires this event) ### Payload The payload includes a `previous_attributes` object containing only the fields that changed. ```json { "type": "subscription.trial_will_end", "id": "evt_g7H8i9J0k1L2m3N4o5P6q7R8", "created": 1704240000, "data": { "object": { "object": "subscription", "id": 100001, "...": "full subscription object", "status": "trialing", "trial_start": "2026-01-01T12:00:00.000000Z", "trial_end": "2026-01-14T12:00:00.000000Z" }, "previous_attributes": { "status": "trialing" } } } ``` *** ## subscription.gift\_notification ### Triggered When * A gift subscription is created and the `gift_start_date` is today or in the past (fires immediately at creation) * A scheduled job processes gift subscriptions whose `gift_start_date` has arrived (for future-dated gifts) ### Payload Gift-related fields are populated when this event fires. ```json { "type": "subscription.gift_notification", "id": "evt_h8I9j0K1l2M3n4O5p6Q7r8S9", "created": 1704067200, "data": { "object": { "object": "subscription", "id": 100001, "...": "full subscription object", "is_gift_donor": 1, "is_gift_recipient": 0, "gift_code": "GIFT-XXXX-XXXX", "gift_recipient_email": "recipient@example.com", "gift_recipient_first_name": "John", "gift_recipient_last_name": "Smith", "gift_message": "Enjoy your subscription!", "gift_start_date": "2026-02-01T00:00:00.000000Z", "gift_notification_sent": 1, "gift_donor_subscription_id": null } } } ``` *** ## Payload Fields ### Subscription Object | Field | Type | Description | | ---------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `object` | string | Object type identifier, always `subscription` | | `id` | integer | Unique identifier for the subscription | | `object_id` | string \| null | External gateway identifier (e.g., Stripe subscription ID) | | `site_id` | integer | Site the subscription belongs to | | `address_id` | integer \| null | Shipping address ID | | `status` | string | Subscription status: `"active"`, `"canceled"`, `"past_due"`, `"trialing"`, `"unpaid"`, `"incomplete"`, `"incomplete_expired"`, `"extended"`, `"pending_payment"`, or `"scheduled"` | | `auto_renew` | boolean | Whether the subscription will auto-renew (`true` when active and not set to cancel) | | `cancel_at_period_end` | integer | Whether the subscription will cancel at period end: `0` (no) or `1` (yes) | | `billing` | integer | Billing type | | `billing_cycle_anchor` | string \| null | ISO 8601 timestamp of the billing cycle anchor | | `cancel_at` | string \| null | ISO 8601 timestamp when the subscription is scheduled to cancel | | `canceled_at` | string \| null | ISO 8601 timestamp when the subscription was canceled | | `canceled_by_email` | string \| null | Email of the user who canceled the subscription | | `canceled_by_type` | string \| null | Who canceled: `"Customer"`, `"Admin/Collaborator"`, `"System"`, `"churn_prediction"`, or `null` | | `cancel_reason` | string \| null | Reason provided for cancellation | | `created` | string | ISO 8601 timestamp when the subscription was created | | `current_period_start` | string \| null | ISO 8601 timestamp of the current billing period start | | `current_period_end` | string \| null | ISO 8601 timestamp of the current billing period end | | `days_until_due` | integer \| null | Number of days before an invoice is due (for send-invoice billing) | | `ended_at` | string \| null | ISO 8601 timestamp when the subscription ended | | `expires_at` | integer \| null | Unix timestamp when the subscription will expire (`null` if auto-renewing) | | `renews_at` | integer \| null | Unix timestamp when the subscription will next renew (`null` if not renewing) | | `quantity` | integer \| null | Number of seats or units | | `start_date` | string \| null | ISO 8601 timestamp when the subscription started | | `trial_start` | string \| null | ISO 8601 timestamp when the trial started | | `trial_end` | string \| null | ISO 8601 timestamp when the trial ends | | `source` | string \| null | Deprecated source field | | `backdate_start_date` | string \| null | ISO 8601 timestamp for backdated subscriptions | | `metadata` | object \| null | Custom key-value metadata | | `recommended_plan_id` | integer \| null | Recommended plan ID for upgrades | | `agency_id` | integer \| null | Associated agency ID | ### Gift Fields | Field | Type | Description | | ---------------------------- | --------------- | --------------------------------------------------------- | | `is_gift_donor` | integer | Whether this subscription is a gift donation: `0` or `1` | | `is_gift_recipient` | integer | Whether this is a gift recipient subscription: `0` or `1` | | `is_redeemed` | integer \| null | Whether the gift has been redeemed | | `gift_code` | string \| null | Gift redemption code | | `gift_recipient_email` | string \| null | Email of the gift recipient | | `gift_recipient_first_name` | string \| null | Gift recipient's first name | | `gift_recipient_last_name` | string \| null | Gift recipient's last name | | `gift_message` | string \| null | Message from the gift donor | | `gift_start_date` | string \| null | ISO 8601 timestamp when the gift starts | | `gift_notification_sent` | integer | Whether the gift notification was sent: `0` or `1` | | `gift_donor_subscription_id` | integer \| null | ID of the donor's subscription | ### Shipment Fields | Field | Type | Description | | --------------------------- | --------------- | ----------------------------------------------------- | | `shipments_remaining` | integer \| null | Number of shipments remaining in the current period | | `shipments_undeliverable` | boolean | Whether shipments are undeliverable | | `shipments_suspended_until` | string \| null | ISO 8601 timestamp until when shipments are suspended | ### Churn Prediction Fields > 📘 **Premium Feature** > > Churn Prediction Score is a premium add-on. Contact to activate it for your account. Additional fees apply. These fields will be `null` until the feature is enabled. | Field | Type | Description | | ----------------------------- | --------------- | ----------------------------------------------------- | | `churn_risk_score` | integer \| null | Predicted churn risk score | | `churn_risk_bucket` | string \| null | Churn risk category: `"low"`, `"medium"`, or `"high"` | | `churn_prediction_created_at` | integer \| null | Unix timestamp when the prediction was created | | `churn_prediction_updated_at` | integer \| null | Unix timestamp when the prediction was last updated | ### Campaign Fields | Field | Type | Description | | -------------- | --------------- | ------------------------------------------ | | `campaign_id` | integer \| null | Associated campaign ID | | `campaign_key` | string \| null | Campaign key used for acquisition tracking | ### Nested Objects | Field | Type | Description | | ------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer` | object \| null | Full customer object (see [Customer Webhooks](https://docs.pelcro.com/docs/webhooks-customers)) | | `plan` | object \| null | Full plan object with nested product (see [Plan Webhooks](https://docs.pelcro.com/docs/webhooks-plans)) | | `coupon` | object \| null | Applied coupon (see below) | | `default_source` | object \| null | Default payment method (see [Payment Method Webhooks](https://docs.pelcro.com/docs/webhooks-payment-methods)). The nested `customer` field is excluded to avoid circular nesting. | | `latest_invoice` | object \| null | Most recent invoice with nested charge (see [Invoice Webhooks](https://docs.pelcro.com/docs/webhooks-invoices)). The nested `subscription` field is excluded to avoid circular nesting. | | `address_shipping` | object \| null | Shipping address (see [Address Webhooks](https://docs.pelcro.com/docs/webhooks-addresses)) | | `shipping_address` | object \| null | Same as `address_shipping` (deprecated naming, kept for backwards compatibility) | | `schedules` | object \| null | Subscription schedules list (see below) | | `default_tax_rates` | object \| null | Applied tax rates list (see below) | ### Coupon Object (Nested) | Field | Type | Description | | -------------------- | --------------- | ------------------------------------------------- | | `object` | string | Always `coupon` | | `object_id` | string | External gateway coupon ID | | `type` | string | Coupon type (e.g., `"subscription"`) | | `amount_off` | integer \| null | Discount amount in cents | | `code` | string | Coupon code | | `created` | string | ISO 8601 timestamp | | `currency` | string \| null | Three-letter ISO currency code | | `duration` | string | Duration: `"once"`, `"repeating"`, or `"forever"` | | `duration_in_months` | integer \| null | Number of months (for repeating coupons) | | `livemode` | boolean | Whether this is a live coupon | | `name` | string | Coupon display name | | `max_redemptions` | integer \| null | Maximum number of times the coupon can be used | | `percent_off` | float \| null | Discount percentage | | `redeem_by` | string \| null | ISO 8601 timestamp when the coupon expires | | `times_redeemed` | integer | Number of times the coupon has been used | | `valid` | boolean | Whether the coupon is still valid | ### Schedules Object (Nested) When present, schedules use a list format: ```json { "object": "list", "data": [ { "object": "subscription_schedule", "object_id": "sub_sched_XXXXXXXXXXXX", "status": "active", "phases": { "object": "list", "data": [ { "object": "subscription_schedule_phase", "start_date": "2026-01-01T12:00:00.000000Z", "end_date": "2026-04-01T12:00:00.000000Z", "coupon": null, "plans": { "object": "list", "data": [{ "...": "phase plan objects" }] } } ] } } ] } ``` ### Previous Attributes (updated, changed, and trial\_will\_end events) | Field | Type | Description | | --------------------- | ------ | ---------------------------------------------------------------------------------------------------- | | `previous_attributes` | object | Contains only the publishable fields that changed, with their **previous** values before the update. | *** ## Notes * The subscription payload is the **most deeply nested** of all webhook resources — it includes full customer, plan (with product), invoice (with charge), payment method, and address objects. * `status` is a **string** (e.g., `"active"`, `"canceled"`), not an integer. * `auto_renew` is **computed**: it is `true` when the subscription is active or trialing and `cancel_at_period_end` is `0`. * `expires_at` and `renews_at` are **unix timestamps** (integers), unlike most other date fields which use ISO 8601 strings. * `cancel_at_period_end` is an **integer** (`0` or `1`), not a boolean. * `canceled_by_type` maps the internal value `"Publisher"` to `"Admin/Collaborator"` in the webhook payload. * The `default_source` object in the subscription payload excludes the nested `customer` to avoid circular nesting. Similarly, `latest_invoice` excludes the nested `subscription`. * Both `shipping_address` (deprecated) and `address_shipping` (current) are included in the payload with identical data for backwards compatibility. * `subscription.expired` is the event name shown to subscribers, even though it corresponds to the internal event code `SUBSCRIPTION_DELETED` (305). *** ## Related * [Webhooks Overview](webhooks) - Setup, signatures, and configuration * [Customer Webhooks](https://docs.pelcro.com/docs/webhooks-customers) - Customer object field descriptions * [Plan Webhooks](https://docs.pelcro.com/docs/webhooks-plans) - Plan and product object field descriptions * [Invoice Webhooks](https://docs.pelcro.com/docs/webhooks-invoices) - Invoice object field descriptions * [Payment Method Webhooks](https://docs.pelcro.com/docs/webhooks-payment-methods) - Payment method field descriptions * [Address Webhooks](https://docs.pelcro.com/docs/webhooks-addresses) - Address object field descriptions # Sibling pages * [Email Templates](https://docs.pelcro.com/v2.4/docs/e-mail-templates-for-webhooks.md) * [Addresses](https://docs.pelcro.com/v2.4/docs/webhooks-addresses.md) * [Bills](https://docs.pelcro.com/v2.4/docs/webhooks-bills.md) * [Campaigns](https://docs.pelcro.com/v2.4/docs/webhooks-campaigns.md) * [Charges](https://docs.pelcro.com/v2.4/docs/webhooks-charges.md) * [Customers](https://docs.pelcro.com/v2.4/docs/webhooks-customers.md) * [Exports](https://docs.pelcro.com/v2.4/docs/webhooks-exports.md) * [Fraud Prevention](https://docs.pelcro.com/v2.4/docs/webhooks-fraud-prevention.md) * [Invoices](https://docs.pelcro.com/v2.4/docs/webhooks-invoices.md) * [Members](https://docs.pelcro.com/v2.4/docs/webhooks-members.md) * [Newsletters](https://docs.pelcro.com/v2.4/docs/webhooks-newsletters.md) * [Orders](https://docs.pelcro.com/v2.4/docs/webhooks-orders.md) * [Payment Methods](https://docs.pelcro.com/v2.4/docs/webhooks-payment-methods.md) * [Plans](https://docs.pelcro.com/v2.4/docs/webhooks-plans.md) * [Products](https://docs.pelcro.com/v2.4/docs/webhooks-products.md) * [Vendors](https://docs.pelcro.com/v2.4/docs/webhooks-vendors.md)