New Subscriptions

subscription.activated

Overview of the subscription.activated webhook

When a subscription.activated event is triggered, FastSpring sends a webhook payload containing details about a newly created subscription. This webhook only fires when a buyer starts a new subscription, including new trials. It does not fire on rebills.

If webhook expansion is enabled, the payload includes full account and product objects. Otherwise, the payload includes only the corresponding IDs.

This page provides:

  • A full sample payload showing a populated subscription.activated webhook
  • A detailed table listing every payload property, including name, type, and description
  • Notes on field behavior, including how to detect trials and what's included when webhook expansion is enabled

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.activated event is triggered, the webhook sends the following JSON payload:

{
  "id": "subSCR1pt10nAbc123-456XYZ",
  "quote": "QUOT1234ABC5678XYZ",
  "subscription": "subSCR1pt10nAbc123-456XYZ",
  "active": true,
  "state": "active",
  "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",
    "offers": [
      {
        "type": "addon",
        "display": {
          "en": "Extended Support"
        },
        "items": ["example-addon-product"]
      }
    ],
    "fulfillments": {
      "example-subscription-annual_file_1": {
        "fulfillment": "example-subscription-annual_file_1",
        "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": {
      "interval": "year",
      "intervalLength": 1,
      "intervalCount": 1,
      "quantityBehavior": "allow",
      "quantityDefault": 1,
      "price": {
        "USD": 100
      },
      "dateLimitsEnabled": false,
      "setupFee": {
        "price": {
          "USD": 10
        },
        "title": {
          "en": "One-time Setup Fee"
        }
      },
      "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",
  "paymentReminder": {
    "intervalUnit": "week",
    "intervalLength": 1
  },
  "paymentOverdue": {
    "intervalUnit": "week",
    "intervalLength": 1,
    "total": 4,
    "sent": 0
  },
  "cancellationSetting": {
    "cancellation": "AFTER_LAST_NOTIFICATION",
    "intervalUnit": "week",
    "intervalLength": 1
  },
  "addons": [
    {
      "product": "example-addon-product",
      "sku": "addon-001",
      "display": "Example Add-on Product",
      "quantity": 1,
      "price": 10,
      "priceDisplay": "$10.00",
      "priceInPayoutCurrency": 10,
      "priceInPayoutCurrencyDisplay": "$10.00",
      "discount": 0,
      "discountDisplay": "$0.00",
      "discountInPayoutCurrency": 0,
      "discountInPayoutCurrencyDisplay": "$0.00",
      "subtotal": 10,
      "subtotalDisplay": "$10.00",
      "subtotalInPayoutCurrency": 10,
      "subtotalInPayoutCurrencyDisplay": "$10.00",
      "discounts": []
    }
  ],
  "setupFee": {
    "price": {
      "USD": 10
    },
    "title": {
      "en": "One-time Setup Fee"
    }
  },
  "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.activated event JSON payload, specifying their name, data type, and description.

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.offers array List of add-on offers related to the product.
product.offers.type string Type of offer (e.g., addon).
product.offers.display.en string Localized name of the offer in English.
product.offers.items array List of product IDs included in the offer.
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.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.setupFee object Details about any one-time setup fee associated with the subscription product.
product.pricing.setupFee.price.USD number Setup fee amount in USD.
product.pricing.setupFee.title.en string Localized display label for the setup fee. Example: One-time Setup Fee.
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 ↑
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.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:
  • trial: only exists if there's a free trial
  • discounted: only exists if there's a product-level discount
  • regular: always present
instructions.trialType string The type of trial that was signed up for. Options:
  • PAID: a discounted trial subscription
  • FREE_WITH_PAYMENT a free trial subscription that requires a payment instrument:
  • FREE_WITHOUT_PAYMENT: a free trial subscription that requires a payment instrument
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.