subscription.canceled
Overview of the subscription.canceled webhook
When a subscription.canceled
event is triggered, FastSpring sends a webhook payload with details about the canceled subscription. This webhook typically fires when a customer cancels through their account management portal, when you select Deactivate at Next Period in the FastSpring App, or when you cancel via the API without including billingPeriod=0
.
Webhook behavior
Fires when:
- A customer cancels a subscription via the customer portal
- You select Deactivate at Next Period in the FastSpring App
- You cancel a subscription using the API and omit
billingPeriod=0
Does not fire when:
- You select Deactivate Now in the FastSpring App
- You cancel a subscription using the API and include
billingPeriod=0
- You cancel a managed subscription
This page includes:
- A full sample payload for the
subscription.canceled
webhook - A detailed table listing every payload property, including name, type, and description
- Notes on when this webhook is triggered and which fields appear based on Webhook Expansion
Browse the table sections below or use the quick links to jump to a specific group of fields.
Tip: Not all fields are always included. Refer to the Payload properties table to understand when a field appears.
Webhook payload example (expansion enabled)
When a subscription.canceled
event is triggered, the webhook sends the following JSON payload:
{
"id": "subSCR1pt10nAbc123-456XYZ",
"quote": "QUOT1234ABC5678XYZ",
"subscription": "subSCR1pt10nAbc123-456XYZ",
"active": true,
"state": "canceled",
"changed": 1751328000000,
"changedValue": 1751328000000,
"changedInSeconds": 1751328000,
"changedDisplay": "7/31/25",
"live": true,
"currency": "USD",
"account": {
"id": "acctAbCdEfG123-XyZ456",
"account": "acctAbCdEfG123-XyZ456",
"contact": {
"first": "John",
"last": "Doe",
"email": "[email protected]",
"company": "Example Corp",
"phone": "+1 5550001000"
},
"language": "en",
"country": "US",
"lookup": {
"global": "acctPublicID789_XYZ"
},
"url": "https://examplestore.test.onfastspring.com/account"
},
"product": {
"product": "example-subscription-annual",
"parent": "example-parent-product",
"display": {
"en": "Example Subscription - Annual"
},
"description": {
"summary": {
"en": "This is the summary description for Example Subscription - Annual."
},
"action": {
"en": "Buy Now"
},
"full": {
"en": "This is the long description for Example Subscription - Annual."
}
},
"image": "https://cdn.example.com/images/subscription-annual.png",
"fulfillments": {
"example-subscription-monthly_file_0": {
"fulfillment": "example-subscription-monthly_file_0",
"name": "File Download (installer.exe)",
"applicability": "NON_REBILL_ONLY",
"display": {
"en": "Download Installer"
},
"url": "https://cdn.example.com/files/installer.exe",
"size": 24576,
"behavior": "PREFER_EXPLICIT",
"previous": []
}
},
"format": "digital",
"pricing": {
"trial": 7,
"interval": "month",
"intervalLength": 1,
"intervalCount": 1,
"quantityBehavior": "allow",
"quantityDefault": 1,
"price": {
"USD": 100
},
"dateLimitsEnabled": false,
"reminderNotification": {
"enabled": true,
"interval": "week",
"intervalLength": 1
},
"overdueNotification": {
"enabled": true,
"interval": "week",
"intervalLength": 1,
"amount": 4
},
"cancellation": {
"interval": "week",
"intervalLength": 1
}
}
},
"sku": "sub-annual-001",
"display": "Example Subscription - Annual",
"quantity": 1,
"adhoc": false,
"autoRenew": true,
"price": 100,
"priceDisplay": "$100.00",
"priceInPayoutCurrency": 100,
"priceInPayoutCurrencyDisplay": "$100.00",
"discount": 0,
"discountDisplay": "$0.00",
"discountInPayoutCurrency": 0,
"discountInPayoutCurrencyDisplay": "$0.00",
"subtotal": 110,
"subtotalDisplay": "$110.00",
"subtotalInPayoutCurrency": 110,
"subtotalInPayoutCurrencyDisplay": "$110.00",
"next": 1782864000000,
"nextValue": 1782864000000,
"nextInSeconds": 1782864000,
"nextDisplay": "7/31/26",
"end": 1814486400000,
"endValue": 1814486400000,
"endInSeconds": 1814486400,
"endDisplay": "7/31/27",
"canceledDate": 1814486400000,
"canceledDateValue": 1814486400000,
"canceledDateInSeconds": 1814486400,
"canceledDateDisplay": "7/31/27",
"deactivationDate": 1814572800000,
"deactivationDateValue": 1814572800000,
"deactivationDateInSeconds": 1814572800,
"deactivationDateDisplay": "8/1/27",
"sequence": 1,
"periods": 12,
"remainingPeriods": 11,
"begin": 1751328000000,
"beginValue": 1751328000000,
"beginInSeconds": 1751328000,
"beginDisplay": "7/31/25",
"intervalUnit": "year",
"intervalLength": 1,
"nextChargeCurrency": "USD",
"nextChargeDate": 1782864000000,
"nextChargeDateValue": 1782864000000,
"nextChargeDateInSeconds": 1782864000,
"nextChargeDateDisplay": "7/31/26",
"nextChargePreTax": 110,
"nextChargePreTaxDisplay": "$110.00",
"nextChargePreTaxInPayoutCurrency": 110,
"nextChargePreTaxInPayoutCurrencyDisplay": "$110.00",
"nextChargeTotal": 110,
"nextChargeTotalDisplay": "$110.00",
"nextChargeTotalInPayoutCurrency": 110,
"nextChargeTotalInPayoutCurrencyDisplay": "$110.00",
"nextNotificationType": "PAYMENT_REMINDER",
"nextNotificationDate": 1782259200000,
"nextNotificationDateValue": 1782259200000,
"nextNotificationDateInSeconds": 1782259200,
"nextNotificationDateDisplay": "7/25/26",
"trialReminder": {
"intervalUnit": "day",
"intervalLength": 3
},
"paymentReminder": {
"intervalUnit": "week",
"intervalLength": 1
},
"paymentOverdue": {
"intervalUnit": "week",
"intervalLength": 1,
"total": 4,
"sent": 0
},
"cancellationSetting": {
"cancellation": "AFTER_LAST_NOTIFICATION",
"intervalUnit": "week",
"intervalLength": 1
},
"fulfillments": {
"example-subscription-annual_file_1": [
{
"display": "installer.exe",
"size": 24576,
"file": "https://cdn.example.com/files/installer.exe",
"type": "file"
}
]
},
"instructions": [
{
"product": "example-subscription-annual",
"type": "regular",
"periodStartDate": 1751328000000,
"periodStartDateValue": 1751328000000,
"periodStartDateInSeconds": 1751328000,
"periodStartDateDisplay": "7/31/25",
"periodEndDate": 1782864000000,
"periodEndDateValue": 1782864000000,
"periodEndDateInSeconds": 1782864000,
"periodEndDateDisplay": "7/31/26",
"intervalUnit": "year",
"intervalLength": 1,
"discountPercent": 0,
"discountPercentValue": 0,
"discountPercentDisplay": "0%",
"discountTotal": 0,
"discountTotalDisplay": "$0.00",
"discountTotalInPayoutCurrency": 0,
"discountTotalInPayoutCurrencyDisplay": "$0.00",
"unitDiscount": 0,
"unitDiscountDisplay": "$0.00",
"unitDiscountInPayoutCurrency": 0,
"unitDiscountInPayoutCurrencyDisplay": "$0.00",
"price": 100,
"priceDisplay": "$100.00",
"priceInPayoutCurrency": 100,
"priceInPayoutCurrencyDisplay": "$100.00",
"priceTotal": 100,
"priceTotalDisplay": "$100.00",
"priceTotalInPayoutCurrency": 100,
"priceTotalInPayoutCurrencyDisplay": "$100.00",
"unitPrice": 100,
"unitPriceDisplay": "$100.00",
"unitPriceInPayoutCurrency": 100,
"unitPriceInPayoutCurrencyDisplay": "$100.00",
"total": 100,
"totalDisplay": "$100.00",
"totalInPayoutCurrency": 100,
"totalInPayoutCurrencyDisplay": "$100.00"
}
]
}
Payload properties
The payload properties table outlines each property in the subscription.canceled
event JSON payload, specifying their name, data type, and description.
Navigate this webhook
Jump to a specific section of the subscription.canceled
table using the links below:
Name | Type | Description |
---|---|---|
Subscription Metadata Back to top ↑ | ||
id | string | Unique identifier for the subscription instance. |
quote | string | Quote ID associated with the original order, if applicable. |
subscription | string | Subscription ID (backward compatibility). Matches the id field. |
active | boolean | Indicates whether the subscription is active. true if active; false if deactivated. |
state | string | Current subscription state. Example values: active , overdue , deactivated , trial , canceled . |
Timestamps Back to top ↑ | ||
changed | integer | Timestamp (in milliseconds) when the subscription was last updated. |
changedValue | integer | Same value as changed . Included for backward compatibility. |
changedInSeconds | integer | Timestamp (in seconds) when the subscription was last updated. |
changedDisplay | string | Formatted display value of the last updated timestamp. |
Subscription Settings Back to top ↑ | ||
live | boolean | true indicates a live order. false indicates a test order. |
currency | string | 3-letter ISO code representing the currency of the subscription. |
Account Object Back to top ↑ | ||
account | object | Customer account object. Contains ID, contact info, language, country, and account lookup details. |
account.id | string | FastSpring-generated customer account ID. |
account.account | string | Duplicate of account.id . Included for backward compatibility. |
account.contact.first | string | Customer’s first name. |
account.contact.last | string | Customer’s last name. |
account.contact.email | string | Customer’s email address. |
account.contact.company | string | Customer's company name, if provided. |
account.contact.phone | string | Customer's phone number, if provided. |
account.language | string | 2-letter ISO code representing the customer's preferred language (e.g., en ). |
account.country | string | 2-letter ISO code representing the customer's country (e.g., US ). |
account.lookup.global | string | Globally unique public ID used to look up the account in customer-facing portals. |
account.url | string | URL for the customer-facing account management page. |
Product Object Back to top ↑ | ||
product | object | Product object associated with the subscription. Includes product details, pricing, and fulfillment metadata. |
product.product | string | Product path or ID of the subscription product. |
product.parent | string | ID of the parent product, if the subscription is part of a bundled or related set. |
product.display.en | string | Localized display name of the product in English. |
product.description.summary.en | string | Short summary description of the product in English. |
product.description.action.en | string | Call-to-action text for the product (e.g., “Buy Now”), localized in English. |
product.description.full.en | string | Long-form description of the product in English. |
product.image | string | URL to the main product image used in checkout and customer portals. |
product.fulfillments | object | Object containing one or more fulfillment items keyed by dynamic IDs. |
product.fulfillments.fulfillment | string | Unique identifier for the fulfillment item. |
product.fulfillments.name | string | Name or label of the fulfillment (e.g., "File Download"). |
product.fulfillments.applicability | string | Determines when the fulfillment applies. Example: NON_REBILL_ONLY . |
product.fulfillments.display.en | string | Buyer-facing display name of the fulfillment in English. |
product.fulfillments.url | string | Download URL for the fulfillment file, if applicable. |
product.fulfillments.size | integer | File size in bytes, if the fulfillment is a downloadable file. |
product.fulfillments.behavior | string | Determines the delivery behavior. Example: PREFER_EXPLICIT . |
product.fulfillments.previous | array | Array of previously used fulfillment items, if applicable. |
product.format | string | Format of the product. Example: digital . |
product.format | string | Type of product. Example: digital . |
product.pricing.trial | string | Time unit for the billing interval. Example values: month , year . |
product.pricing.interval | string | Time unit for the billing interval. Example values: month , year . |
product.pricing.intervalLength | integer | Number of units per billing interval. Example: 1 for annual or monthly billing. |
product.pricing.intervalCount | integer | Total number of billing intervals for the subscription. Optional. |
product.pricing.quantityBehavior | string | Indicates how quantity is handled. Example: allow . |
product.pricing.quantityDefault | integer | Default quantity value for the product when added to the cart. |
product.pricing.price.USD | number | Product price in USD. |
product.pricing.dateLimitsEnabled | boolean | Indicates whether there are time-based restrictions on pricing availability. |
product.pricing.reminderNotification | object | Configuration for sending upcoming renewal reminders. |
product.pricing.reminderNotification.enabled | boolean | true if the reminder is enabled; otherwise false. |
product.pricing.reminderNotification.interval | string | Time unit for the reminder interval. Example: week . |
product.pricing.reminderNotification.intervalLength | integer | Number of interval units before the charge to send the reminder. |
product.pricing.overdueNotification | object | Configuration for sending payment overdue notifications. |
product.pricing.overdueNotification.enabled | boolean | true if overdue notices are enabled; otherwise false. |
product.pricing.overdueNotification.interval | string | Time unit between overdue notices. Example: week . |
product.pricing.overdueNotification.intervalLength | integer | Interval length between overdue notices in interval units. |
product.pricing.overdueNotification.amount | integer | Total number of overdue notices to send. |
product.pricing.cancellation | object | Settings that control when to cancel the subscription after failed rebills. |
product.pricing.cancellation.interval | string | Time unit used with intervalLength to determine when to cancel the subscription. Example: week . |
product.pricing.cancellation.intervalLength | integer | Number of interval units after the cancellation condition is met. |
Subscription Details (Root-level) Back to top ↑ | ||
sku | string | Internal SKU for the subscription product. |
display | string | Display name of the subscription product. |
quantity | integer | Quantity of the subscription product in the order. |
adhoc | boolean | true for managed subscriptions; false for standard subscriptions. |
autoRenew | boolean | true for automatic subscriptions; false for manual renewal subscriptions. |
Pricing Back to top ↑ | ||
price | number | Base price of the subscription product. |
priceDisplay | string | Base price formatted for display (e.g., $100.00 ). |
priceInPayoutCurrency | number | Base price converted to your FastSpring disbursement currency. |
priceInPayoutCurrencyDisplay | string | Formatted version of priceInPayoutCurrency . |
discount | number | Total discount amount applied to the subscription. |
discountDisplay | string | Formatted discount amount (e.g., $0.00 ). |
discountInPayoutCurrency | number | Discount amount in your payout currency. |
discountInPayoutCurrencyDisplay | string | Formatted version of discountInPayoutCurrency . |
subtotal | number | Subtotal amount, including price and setup fees, before taxes. |
subtotalDisplay | string | Formatted version of the subtotal. |
subtotalInPayoutCurrency | number | Subtotal amount in your payout currency. |
subtotalInPayoutCurrencyDisplay | string | Formatted subtotal in your payout currency. |
Rebill and Expiration Back to top ↑ | ||
next | integer | Timestamp (in milliseconds) of the next scheduled rebill. |
nextValue | integer | Same as next . Included for backward compatibility. |
nextInSeconds | integer | Next scheduled rebill timestamp, in seconds. |
nextDisplay | string | Formatted date of the next scheduled rebill. |
end | integer | Timestamp (in milliseconds) of the subscription end date. |
endValue | integer | Same as end . Included for backward compatibility. |
endInSeconds | integer | End date of the subscription, in seconds. |
endDisplay | string | Formatted display of the subscription’s end date. |
Cancellation and Deactivation Back to top ↑ | ||
canceledDate | integer | Timestamp (in milliseconds) when the subscription was canceled. |
canceledDateValue | integer | Same as canceledDate . Included for backward compatibility. |
canceledDateInSeconds | integer | Timestamp in seconds when the subscription was canceled. |
canceledDateDisplay | string | Formatted display of the cancelation date. |
deactivationDate | integer | Timestamp (in milliseconds) when the subscription was deactivated. |
deactivationDateValue | integer | Same as deactivationDate . Included for backward compatibility. |
deactivationDateInSeconds | integer | Deactivation timestamp, in seconds. |
deactivationDateDisplay | string | Formatted display of the subscription’s deactivation date. |
Billing Schedule Back to top ↑ | ||
sequence | integer | Current billing period number for the subscription. |
periods | integer | Total number of expected billing periods. |
remainingPeriods | integer | Number of rebills remaining before expiration. |
begin | integer | Activation date timestamp in milliseconds. |
beginValue | integer | Same as begin . Included for backward compatibility. |
beginInSeconds | integer | Activation date timestamp in seconds. |
beginDisplay | string | Formatted activation date. |
intervalUnit | string | Time unit for rebilling. Example values: month , year , adhoc . |
intervalLength | integer | Number of interval units per billing cycle. |
Next Charge Details Back to top ↑ | ||
nextChargeCurrency | string | 3-letter ISO code for the currency of the next scheduled charge. |
nextChargeDate | integer | Next charge date timestamp in milliseconds. |
nextChargeDateValue | integer | Same as nextChargeDate . Included for backward compatibility. |
nextChargeDateInSeconds | integer | Next charge date timestamp in seconds. |
nextChargeDateDisplay | string | Formatted display of the next charge date. |
nextChargePreTax | number | Total pre-tax amount for the upcoming charge. |
nextChargePreTaxDisplay | string | Formatted pre-tax charge amount (e.g., $100.00 ). |
nextChargePreTaxInPayoutCurrency | number | Pre-tax charge amount in your payout currency. |
nextChargePreTaxInPayoutCurrencyDisplay | string | Formatted version of the pre-tax amount in payout currency. |
nextChargeTotal | number | Total amount for the next charge, including tax (if applicable). |
nextChargeTotalDisplay | string | Formatted total charge amount. |
nextChargeTotalInPayoutCurrency | number | Total next charge amount in your payout currency. |
nextChargeTotalInPayoutCurrencyDisplay | string | Formatted version of the total charge amount in payout currency. |
Notification Settings Back to top ↑ | ||
nextNotificationType | string | Type of notification scheduled next. Example: PAYMENT_REMINDER . |
nextNotificationDate | integer | Scheduled notification timestamp in milliseconds. |
nextNotificationDateValue | integer | Same as nextNotificationDate . Included for backward compatibility. |
nextNotificationDateInSeconds | integer | Scheduled notification timestamp in seconds. |
nextNotificationDateDisplay | string | Formatted notification date for display. |
Reminder and Overdue Settings Back to top ↑ | ||
trialReminder | object | Defines the timing of the customer-facing reminder email message that will be sent (if any) regarding the approaching end of a free trial period. |
trialReminder.intervalUnit | string | Time unit used to determine when the reminder is sent. Example: week . |
trialReminder.intervalLength | integer | Number of intervalUnits before the charge that the reminder is sent. |
paymentReminder | object | Defines the interval settings for sending a payment reminder. |
paymentReminder.intervalUnit | string | Time unit used to determine when the reminder is sent. Example: week . |
paymentReminder.intervalLength | integer | Number of intervalUnits before the charge that the reminder is sent. |
paymentOverdue | object | Configuration for sending overdue payment notifications. |
paymentOverdue.intervalUnit | string | Time unit between overdue notices. Example: week . |
paymentOverdue.intervalLength | integer | Interval between overdue notices in intervalUnits . |
paymentOverdue.total | integer | Total number of overdue notices to send. |
paymentOverdue.sent | integer | Number of overdue notices already sent. |
cancellationSetting | object | Rules for canceling a subscription after failed payments or overdue notices. |
cancellationSetting.cancellation | string | Trigger for cancelation. Example: AFTER_LAST_NOTIFICATION . |
cancellationSetting.intervalUnit | string | Time unit used with the cancelation trigger. |
cancellationSetting.intervalLength | integer | Delay before cancelation occurs, in intervalUnits . |
Add-ons Array Back to top ↑ | ||
addons | array | List of optional add-on products included with the subscription. |
addons.product | string | Product path or ID of the add-on item. |
addons.sku | string | SKU associated with the add-on product. |
addons.display | string | Display name of the add-on product. |
addons.quantity | integer | Quantity of the add-on product in the order. |
addons.price | number | Unit price of the add-on. |
addons.priceDisplay | string | Formatted display of the add-on price. |
addons.priceInPayoutCurrency | number | Add-on price in your payout currency. |
addons.priceInPayoutCurrencyDisplay | string | Formatted display of the add-on price in your payout currency. |
addons.discount | number | Total discount applied to the add-on product. |
addons.discountDisplay | string | Formatted discount display value. |
addons.discountInPayoutCurrency | number | Discount amount in your payout currency. |
addons.discountInPayoutCurrencyDisplay | string | Formatted discount in payout currency. |
addons.subtotal | number | Total cost of the add-on after discounts. |
addons.subtotalDisplay | string | Formatted subtotal of the add-on. |
addons.subtotalInPayoutCurrency | number | Subtotal in your payout currency. |
addons.subtotalInPayoutCurrencyDisplay | string | Formatted subtotal in your payout currency. |
addons.discounts | array | List of applied discounts, if any. |
Setup Fee Object Back to top ↑ | ||
setupFee | object | Object containing information about the setup fee applied to the subscription. |
setupFee.price | number | Currency and numeric value of the setup fee. |
setupFee.title | string | Display label for the setup fee shown to buyers. |
Fulfillments object Back to top ↑ | ||
Note: Each entry in the fulfillments object is keyed by a dynamic fulfillment ID (e.g. example-subscription-file ). The fields below describe the structure of each fulfillment item.
|
||
fulfillments.license | string | License key(s) associated with the subscription instances |
fulfillments.display | string | Display name of the downloadable file or fulfillment action. |
fulfillments.size | integer | File size in bytes. Applies when the fulfillment type is file . |
fulfillments.file | string | Secure URL for downloading the fulfillment file. |
fulfillments.type | string | Fulfillment type. Example values: file , license . |
Instructions Array Back to top ↑ | ||
Note: The instructions array describes the billing behavior for each rebill period. It includes pricing, discounts, and duration for each step in the subscription lifecycle.
|
||
instructions | array | Describes the billing logic and pricing terms for each rebill period. |
instructions.product | string | Product ID or path for the subscription associated with this billing period. |
instructions.type | string | Type of instructions. A subscription may have more than one instruction object when applicable:
|
instructions.trialType | string | The type of trial that was signed up for. Options:
|
instructions.periodStartDate | integer | Start date of the instruction period, in milliseconds. |
instructions.periodStartDateValue | integer | Same as periodStartDate . Included for backward compatibility. |
instructions.periodStartDateInSeconds | integer | Start date of the instruction period, in seconds. |
instructions.periodStartDateDisplay | string | Formatted display of the instruction period start date. |
instructions.periodEndDate | integer | End date of the instruction period, in milliseconds. |
instructions.periodEndDateValue | integer | Same as periodEndDate . Included for backward compatibility. |
instructions.periodEndDateInSeconds | integer | End date of the instruction period, in seconds. |
instructions.periodEndDateDisplay | string | Formatted display of the instruction period end date. |
instructions.intervalUnit | string | Time unit for the billing interval. Example: adhoc , day , week , month , year . |
instructions.intervalLength | integer | Length of the billing interval in intervalUnit units. |
instructions.discountPercent | number | Percentage discount applied during the period. |
instructions.discountPercentValue | number | Raw value of the discount percentage. Example: 0 . |
instructions.discountPercentDisplay | string | Formatted display of the discount percentage. |
instructions.discountTotal | number | Total discount applied during the period. |
instructions.discountTotalDisplay | string | Formatted display of the total discount. |
instructions.discountTotalInPayoutCurrency | number | Total discount in your payout currency. |
instructions.discountTotalInPayoutCurrencyDisplay | string | Formatted discount total in payout currency. |
instructions.unitDiscount | number | Discount applied to each unit. |
instructions.unitDiscountDisplay | string | Formatted display of the unit discount. |
instructions.unitDiscountInPayoutCurrency | number | Unit discount in your payout currency. |
instructions.unitDiscountInPayoutCurrencyDisplay | string | Formatted unit discount in payout currency. |
instructions.price | number | Base price of the period before discounts. |
instructions.priceDisplay | string | Formatted display of the base price. |
instructions.priceInPayoutCurrency | number | Base price in payout currency. |
instructions.priceInPayoutCurrencyDisplay | string | Formatted base price in payout currency. |
instructions.priceTotal | number | Total price after discount and before tax. |
instructions.priceTotalDisplay | string | Formatted total price display. |
instructions.priceTotalInPayoutCurrency | number | Total price in your payout currency. |
instructions.priceTotalInPayoutCurrencyDisplay | string | Formatted total price in payout currency. |
instructions.unitPrice | number | Price per unit after discount. |
instructions.unitPriceDisplay | string | Formatted display of the unit price. |
instructions.unitPriceInPayoutCurrency | number | Unit price in payout currency. |
instructions.unitPriceInPayoutCurrencyDisplay | string | Formatted unit price in payout currency. |
instructions.total | number | Total charge amount for the period. |
instructions.totalDisplay | string | Formatted total charge display. |
instructions.totalInPayoutCurrency | number | Total charge amount in payout currency. |
instructions.totalInPayoutCurrencyDisplay | string | Formatted total charge in payout currency. |