FastSpring AppAPI ReferenceWebhooksFastSpring JSChangelogFastSpring.com
Developer Documentation
Sign In

Unsuccessful Subscription Rebills

subscription.charge.failed

Overview of the subscription.charge.failed webhook

When a subscription.charge.failed event is triggered, FastSpring sends a webhook payload with details about the rebill failure. The payload contains the failure reason, which is most commonly due to an expired or declined payment method.

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

This page includes:

  • A full sample payload showing a populated subscription.charge.failed webhook
  • A detailed table listing every payload property, including name, type, and description
  • Notes on when each field is included, omitted, or dependent on specific update types

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

{
    "reason": "EXPIRED_CARD",
    "account": {
      "id": "abCdE1FGH2Hij3KLMnOpqR",
      "account": "abCdE1FGH2Hij3KLMnOpqR",
      "contact": {
        "first": "Jane",
        "last": "Doe",
        "email": "[email protected]",
        "company": "Company Inc.",
        "phone": "5555555",
        "subscribed": true
      },
      "address": {
        "address line 1": "123 Business Rd",
        "address line 2": "Floor 4",
        "city": "Metropolis",
        "country": "US",
        "postal code": "12345",
        "region": "US-NY",
        "region custom": null,
        "company": "Company Inc."
      },
      "language": "en",
      "country": "US",
      "lookup": {
        "global": "lookup-001"
      },
      "url": "https://company.onfastspring.com/account"
    },
    "subscription": {
      "id": "1abc2DE_FGhIjKLm3NoPQR",
      "quote": null,
      "subscription": "1abc2DE_FGhIjKLm3NoPQR",
      "active": true,
      "state": "trial",
      "isSubscriptionEligibleForPauseByBuyer": false,
      "isPauseScheduled": false,
      "changed": 1749236508799,
      "changedValue": 1749236508799,
      "changedInSeconds": 1749236508,
      "changedDisplay": "6/6/25",
      "changedDisplayISO8601": "2025-06-06",
      "changedDisplayEmailEnhancements": "Jun 06, 2025",
      "changedDisplayEmailEnhancementsWithTime": "Jun 06, 2025 07:01:48 PM",
      "paymentMethodAction": "none",
      "live": false,
      "currency": "USD",
      "declineReason": null,
      "account": "abCdE1FGH2Hij3KLMnOpqR",
      "product": "furious-falcon",
      "sku": "SKU-FF-102",
      "display": "Furious Falcon",
      "quantity": 1,
      "adhoc": false,
      "autoRenew": true,
      "price": 14.95,
      "priceDisplay": "$14.95",
      "priceInPayoutCurrency": 14.95,
      "priceInPayoutCurrencyDisplay": "$14.95",
      "discount": 0,
      "discountDisplay": "$0.00",
      "discountInPayoutCurrency": 0,
      "discountInPayoutCurrencyDisplay": "$0.00",
      "subtotal": 14.95,
      "subtotalDisplay": "$14.95",
      "subtotalInPayoutCurrency": 14.95,
      "subtotalInPayoutCurrencyDisplay": "$14.95",
      "next": 1749340800000,
      "nextValue": 1749340800000,
      "nextInSeconds": 1749340800,
      "nextDisplay": "6/8/25",
      "nextDisplayISO8601": "2025-06-08",
      "end": null,
      "endValue": null,
      "endInSeconds": null,
      "endDisplay": null,
      "endDisplayISO8601": null,
      "canceledDate": null,
      "canceledDateValue": null,
      "canceledDateInSeconds": null,
      "canceledDateDisplay": null,
      "canceledDateDisplayISO8601": null,
      "deactivationDate": 1749945600000,
      "deactivationDateValue": 1749945600000,
      "deactivationDateInSeconds": 1749945600,
      "deactivationDateDisplay": "6/15/25",
      "deactivationDateDisplayISO8601": "2025-06-15",
      "sequence": 1,
      "periods": null,
      "remainingPeriods": null,
      "begin": 1749236450805,
      "beginValue": 1749236450805,
      "beginInSeconds": 1749236450,
      "beginDisplay": "6/6/25",
      "beginDisplayISO8601": "2025-06-06",
      "beginDisplayEmailEnhancements": "Jun 06, 2025",
      "beginDisplayEmailEnhancementsWithTime": "Jun 06, 2025 07:00:50 PM",
      "nextDisplayEmailEnhancements": "Jun 08, 2025",
      "nextDisplayEmailEnhancementsWithTime": "Jun 08, 2025 12:00:00 AM",
      "intervalUnit": "month",
      "intervalUnitAbbreviation": "mo",
      "intervalLength": 1,
      "intervalLengthGtOne": false,
      "nextChargeCurrency": "USD",
      "nextChargeDate": 1749340800000,
      "nextChargeDateValue": 1749340800000,
      "nextChargeDateInSeconds": 1749340800,
      "nextChargeDateDisplay": "6/8/25",
      "nextChargeDateDisplayISO8601": "2025-06-08",
      "nextChargePreTax": 13.84,
      "nextChargePreTaxDisplay": "$13.84",
      "nextChargePreTaxInPayoutCurrency": 13.84,
      "nextChargePreTaxInPayoutCurrencyDisplay": "$13.84",
      "nextChargeTotal": 14.95,
      "nextChargeTotalDisplay": "$14.95",
      "nextChargeTotalInPayoutCurrency": 14.95,
      "nextChargeTotalInPayoutCurrencyDisplay": "$14.95",
      "cancellationSetting": {
        "cancellation": "AFTER_PAYMENT_FAILURE",
        "intervalUnit": "week",
        "intervalLength": 1
      },
      "fulfillments": {
        "instructions": "<p>Thank you for subscribing to Example Subscription Monthly. Please download the installer file using the button or link found on this page. Your license key is also displayed here.</p>"
      },
      "instructions": [
        {
          "type": "trial",
          "trialType": "PAID",
          "isNotTrial": false,
          "periodStartDate": 1749340800000,
          "periodStartDateValue": 1749340800000,
          "periodStartDateInSeconds": 1749340800,
          "periodStartDateDisplay": "6/8/25",
          "periodStartDateDisplayISO8601": "2025-06-08",
          "periodEndDate": 1749254400000,
          "periodEndDateValue": 1749254400000,
          "periodEndDateInSeconds": 1749254400,
          "periodEndDateDisplay": "6/7/25",
          "periodEndDateDisplayISO8601": "2025-06-07",
          "discountDurationUnit": "day",
          "discountDurationLength": 1,
          "discountPercent": 100,
          "discountPercentValue": 100,
          "discountPercentDisplay": "100%",
          "unitDiscount": 14.95,
          "unitDiscountDisplay": "$14.95",
          "unitDiscountInPayoutCurrency": 14.95,
          "unitDiscountInPayoutCurrencyDisplay": "$14.95",
          "discountTotal": 14.95,
          "discountTotalDisplay": "$14.95",
          "discountTotalInPayoutCurrency": 14.95,
          "discountTotalInPayoutCurrencyDisplay": "$14.95",
          "total": 0,
          "totalDisplay": "$0.00",
          "totalInPayoutCurrency": 0,
          "totalInPayoutCurrencyDisplay": "$0.00",
          "totalWithTaxes": 14.95,
          "totalWithTaxesDisplay": "$14.95",
          "totalWithTaxesInPayoutCurrency": 14.95,
          "totalWithTaxesInPayoutCurrencyDisplay": "$14.95",
          "price": 14.95,
          "priceDisplay": "$14.95",
          "priceInPayoutCurrency": 14.95,
          "priceInPayoutCurrencyDisplay": "$14.95",
          "priceTotal": 14.95,
          "priceTotalDisplay": "$14.95",
          "priceTotalInPayoutCurrency": 14.95,
          "priceTotalInPayoutCurrencyDisplay": "$14.95",
          "unitPrice": 0,
          "unitPriceDisplay": "$0.00",
          "unitPriceInPayoutCurrency": 0,
          "unitPriceInPayoutCurrencyDisplay": "$0.00"
        },
        {
          "product": "furious-falcon",
          "type": "regular",
          "isNotTrial": true,
          "periodStartDate": 1749340800000,
          "periodStartDateValue": 1749340800000,
          "periodStartDateInSeconds": 1749340800,
          "periodStartDateDisplay": "6/8/25",
          "periodStartDateDisplayISO8601": "2025-06-08",
          "periodEndDate": null,
          "periodEndDateValue": null,
          "periodEndDateInSeconds": null,
          "periodEndDateDisplay": null,
          "periodEndDateDisplayISO8601": null,
          "intervalUnit": "month",
          "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": 14.95,
          "priceDisplay": "$14.95",
          "priceInPayoutCurrency": 14.95,
          "priceInPayoutCurrencyDisplay": "$14.95",
          "priceTotal": 14.95,
          "priceTotalDisplay": "$14.95",
          "priceTotalInPayoutCurrency": 14.95,
          "priceTotalInPayoutCurrencyDisplay": "$14.95",
          "unitPrice": 14.95,
          "unitPriceDisplay": "$14.95",
          "unitPriceInPayoutCurrency": 14.95,
          "unitPriceInPayoutCurrencyDisplay": "$14.95",
          "total": 14.95,
          "totalDisplay": "$14.95",
          "totalInPayoutCurrency": 14.95,
          "totalInPayoutCurrencyDisplay": "$14.95",
          "totalWithTaxes": 14.95,
          "totalWithTaxesDisplay": "$14.95",
          "totalWithTaxesInPayoutCurrency": 14.95,
          "totalWithTaxesInPayoutCurrencyDisplay": "$14.95"
        }
      ],
      "initialOrderId": "S6XqptRvRJmzS1qceZKcNA",
      "initialOrderReference": "ABC1234567-8910-11121"
    }
  }

Payload properties

The payload properties table lists each field in the subscription.charge.failed webhook payload, along with its name, type, and description.

Name Type Description
Event Metadata Back to top ↑
reason string Decline reason for the subscription update (e.g., EXPIRED_CARD).
Account Object Back to top ↑
id string Unique identifier for the account.
account string FastSpring-generated customer account ID.
contact object Contact details for the account.
contact.first string First name of the account contact.
contact.last string Last name of the account contact.
contact.email string Email address of the account contact.
contact.company string Company name of the account contact.
contact.phone string Phone number of the account contact.
contact.subscribed boolean Indicates if the account contact is subscribed.
address object Address details for the account.
address.address line 1 string Primary street address line.
address.address line 2 string Secondary street address line.
address.city string City of the account address.
address.country string 2-letter ISO country code for the address.
address.postal code string Postal or ZIP code of the address.
address.region string Region (state/province) for the address.
address.region custom string Custom region name, if not standard.
address.company string Company name associated with this address.
language string 2-letter ISO code of the account's preferred language.
country string 2-letter ISO country code of the account's location.
lookup object Lookup identifiers for the account.
lookup.global string Global lookup identifier for the account.
url string URL to the account management page.
Subscription Object Back to top ↑
subscription object Container for subscription details.
subscription.id string Unique ID of the subscription.
subscription.quote string Associated quote ID, if created from a quote.
subscription.subscription string Duplicate of subscription.id for backward compatibility.
subscription.active boolean true if the subscription is currently active; otherwise false.
subscription.state string Current state of the subscription (e.g., trial, active).
subscription.isSubscriptionEligibleForPauseByBuyer boolean true if the buyer can pause this subscription; otherwise false.
subscription.isPauseScheduled boolean true if a pause is already scheduled; otherwise false.
subscription.changed integer Timestamp (in milliseconds) of the last subscription update.
subscription.changedValue integer Duplicate of subscription.changed for backward compatibility.
subscription.changedInSeconds integer Timestamp (in seconds) of the last subscription update.
subscription.changedDisplay string Formatted display of the last subscription update.
subscription.changedDisplayISO8601 string ISO 8601 formatted timestamp of the last subscription update.
subscription.changedDisplayEmailEnhancements string Email-enhanced display of the last subscription update.
subscription.changedDisplayEmailEnhancementsWithTime string Email-enhanced display with time for the last subscription update.
paymentMethodAction string Action to perform on the payment method (e.g., none, update).
subscription.live boolean true if the subscription was created in live mode; otherwise false.
subscription.currency string 3-letter ISO currency code for the subscription.
subscription.declineReason string Reason for payment decline, if applicable.
subscription.account string Account ID associated with the subscription.
subscription.product string Product ID associated with the subscription.
subscription.sku string SKU of the product associated with the subscription.
subscription.display string Customer-facing name of the subscription.
subscription.quantity integer Number of subscription units.
subscription.adhoc boolean true if this subscription is manually billed; otherwise false.
subscription.autoRenew boolean true if the subscription auto-renews; otherwise false.
Pricing Back to top ↑
subscription.price number Amount charged per billing period in transaction currency.
subscription.priceDisplay string Formatted display of price.
subscription.priceInPayoutCurrency number Subscription price in payout currency.
subscription.priceInPayoutCurrencyDisplay string Formatted display of priceInPayoutCurrency.
subscription.discount number Total discount on the subscription in transaction currency.
subscription.discountDisplay string Formatted display of discount.
subscription.discountInPayoutCurrency number Discount amount in payout currency.
subscription.discountInPayoutCurrencyDisplay string Formatted display of discountInPayoutCurrency.
subscription.subtotal number Subscription subtotal before tax and discounts.
subscription.subtotalDisplay string Formatted display of subtotal.
subscription.subtotalInPayoutCurrency number Subtotal in payout currency.
subscription.subtotalInPayoutCurrencyDisplay string Formatted display of subtotalInPayoutCurrency.
Rebill and Expiration Back to top ↑
subscription.next integer Timestamp (in milliseconds) of the next scheduled billing.
subscription.nextValue integer Duplicate of subscription.next for backward compatibility.
subscription.nextInSeconds integer Timestamp (in seconds) of the next scheduled billing.
subscription.nextDisplay string Formatted display of next.
subscription.nextDisplayISO8601 string ISO 8601 formatted next billing date.
subscription.end integer Timestamp (in milliseconds) when the subscription ends, if scheduled.
subscription.endValue integer Duplicate of subscription.end for backward compatibility.
subscription.endInSeconds integer Timestamp (in seconds) when the subscription ends, if scheduled.
subscription.endDisplay string Formatted display of end.
subscription.endDisplayISO8601 string ISO 8601 formatted end date.
Cancellation and Deactivation Back to top ↑
subscription.canceledDate integer Timestamp (in milliseconds) when the subscription was canceled, if applicable.
subscription.canceledDateValue integer Duplicate of canceledDate for backward compatibility.
subscription.canceledDateInSeconds integer Timestamp (in seconds) when the subscription was canceled.
subscription.canceledDateDisplay string Formatted display of canceledDate.
subscription.canceledDateDisplayISO8601 string ISO 8601 formatted cancellation date.
subscription.deactivationDate integer Timestamp (in milliseconds) when the subscription deactivates, if applicable.
subscription.deactivationDateValue integer Duplicate of deactivationDate for backward compatibility.
subscription.deactivationDateInSeconds integer Timestamp (in seconds) when the subscription deactivates.
subscription.deactivationDateDisplay string Formatted display of deactivationDate.
subscription.deactivationDateDisplayISO8601 string ISO 8601 formatted deactivation date.
Billing Schedule Back to top ↑
subscription.sequence integer Sequence number of the current billing period.
subscription.periods integer Total number of billing periods for the subscription.
subscription.remainingPeriods integer Number of billing periods remaining.
subscription.begin integer Timestamp (in milliseconds) when the subscription began.
subscription.beginValue integer Duplicate of subscription.begin for backward compatibility.
subscription.beginInSeconds integer Timestamp (in seconds) when the subscription began.
subscription.beginDisplay string Formatted display of begin.
subscription.beginDisplayISO8601 string ISO 8601 formatted start date.
subscription.beginDisplayEmailEnhancements string Email-enhanced display of the start date.
subscription.beginDisplayEmailEnhancementsWithTime string Email-enhanced display with time of the start date.
nextDisplayEmailEnhancements string Formatted display of the next charge date, optimized for email.
nextDisplayEmailEnhancementsWithTime string Formatted display of the next charge date with time, optimized for email.
subscription.intervalUnit string Unit of time between billing periods (e.g., month).
subscription.intervalUnitAbbreviation string Abbreviated unit of time between billing periods (e.g., mo).
subscription.intervalLength integer Number of intervalUnits between charges.
subscription.intervalLengthGtOne boolean true if subscription.intervalLength > 1; otherwise false.
Next Charge Details Back to top ↑
nextChargeCurrency string 3-letter ISO currency code for the upcoming subscription charge.
nextChargeDate integer Timestamp (in milliseconds) of the next scheduled charge.
nextChargeDateValue integer Duplicate of nextChargeDate for backward compatibility.
nextChargeDateInSeconds integer Timestamp (in seconds) of the next scheduled charge.
nextChargeDateDisplay string Formatted display of nextChargeDate.
nextChargeDateDisplayISO8601 string ISO 8601 formatted date for the next charge.
nextChargePreTax number Pre-tax amount for the next charge in transaction currency.
nextChargePreTaxDisplay string Formatted display of nextChargePreTax.
nextChargePreTaxInPayoutCurrency number Pre-tax next charge amount in payout currency.
nextChargePreTaxInPayoutCurrencyDisplay string Formatted display of nextChargePreTaxInPayoutCurrency.
nextChargeTotal number Total amount (including tax) for the next charge in transaction currency.
nextChargeTotalDisplay string Formatted display of nextChargeTotal.
nextChargeTotalInPayoutCurrency number Total next charge amount in payout currency.
nextChargeTotalInPayoutCurrencyDisplay string Formatted display of nextChargeTotalInPayoutCurrency.
Cancellation Settings Back to top ↑
cancellationSetting.cancellation string Trigger policy for cancellation after payment failure (e.g., AFTER_PAYMENT_FAILURE).
cancellationSetting.intervalUnit string Unit of time after failure before cancelling (e.g., week).
cancellationSetting.intervalLength integer Number of intervalUnits to wait before cancellation.
Fulfillment Object Back to top ↑
fulfillments object Container for any fulfillment data associated with the subscription.
fulfillments.instructions string HTML content with instructions for delivering the subscription (e.g., download links, license keys).
Instructions Array Back to top ↑
instructions array Array of billing instruction objects for each subscription period.
instructions.product string Product ID for the billing instruction period (only present on regular instructions).
instructions.type string Type of billing instruction (trial or regular).
instructions.trialType string Type of trial (PAID), present only on trial instructions.
instructions.isNotTrial boolean true if this period is not a trial; otherwise false.
instructions.periodStartDate integer Timestamp (in milliseconds) for the start of this billing period.
instructions.periodStartDateValue integer Duplicate of periodStartDate for backward compatibility.
instructions.periodStartDateInSeconds integer Timestamp (in seconds) for the start of this billing period.
instructions.periodStartDateDisplay string Formatted display of periodStartDate.
instructions.periodStartDateDisplayISO8601 string ISO 8601 formatted start date for this billing period.
instructions.periodEndDate integer Timestamp (in milliseconds) for the end of this billing period, if known.
instructions.periodEndDateValue integer Duplicate of periodEndDate for backward compatibility.
instructions.periodEndDateInSeconds integer Timestamp (in seconds) for the end of this billing period, if known.
instructions.periodEndDateDisplay string Formatted display of periodEndDate.
instructions.periodEndDateDisplayISO8601 string ISO 8601 formatted end date for this billing period.
instructions.discountDurationUnit string Unit of time over which the discount applies (e.g., day), only on trial instructions.
instructions.discountDurationLength integer Length of time the discount applies, in discountDurationUnits.
instructions.discountPercent integer Percentage discount applied to this period.
instructions.discountPercentValue integer Duplicate of discountPercent for backward compatibility.
instructions.discountPercentDisplay string Formatted display of discountPercent (e.g., 100%).
instructions.unitDiscount number Per-unit discount amount in transaction currency.
instructions.unitDiscountDisplay string Formatted display of unitDiscount.
instructions.unitDiscountInPayoutCurrency number Per-unit discount amount in payout currency.
instructions.unitDiscountInPayoutCurrencyDisplay string Formatted display of unitDiscountInPayoutCurrency.
instructions.discountTotal number Total discount amount for the period in transaction currency.
instructions.discountTotalDisplay string Formatted display of discountTotal.
instructions.discountTotalInPayoutCurrency number Total discount in payout currency.
instructions.discountTotalInPayoutCurrencyDisplay string Formatted display of discountTotalInPayoutCurrency.
instructions.total number Total amount due for the period in transaction currency.
instructions.totalDisplay string Formatted display of total.
instructions.totalInPayoutCurrency number Total amount in payout currency.
instructions.totalInPayoutCurrencyDisplay string Formatted display of totalInPayoutCurrency.
instructions.totalWithTaxes number Total amount including taxes in transaction currency.
instructions.totalWithTaxesDisplay string Formatted display of totalWithTaxes.
instructions.totalWithTaxesInPayoutCurrency number Total including taxes in payout currency.
instructions.totalWithTaxesInPayoutCurrencyDisplay string Formatted display of totalWithTaxesInPayoutCurrency.
instructions.price number List price before discounts in transaction currency.
instructions.priceDisplay string Formatted display of price.
instructions.priceInPayoutCurrency number List price in payout currency.
instructions.priceInPayoutCurrencyDisplay string Formatted display of priceInPayoutCurrency.
instructions.priceTotal number Total price before discounts in transaction currency.
instructions.priceTotalDisplay string Formatted display of priceTotal.
instructions.priceTotalInPayoutCurrency number Total price before discounts in payout currency.
instructions.priceTotalInPayoutCurrencyDisplay string Formatted display of priceTotalInPayoutCurrency.
instructions.unitPrice number Unit price after discounts in transaction currency.
instructions.unitPriceDisplay string Formatted display of unitPrice.
instructions.unitPriceInPayoutCurrency number Unit price in payout currency.
instructions.unitPriceInPayoutCurrencyDisplay string Formatted display of unitPriceInPayoutCurrency.
subscription.initialOrderId string Initial order ID that created the subscription.
subscription.initialOrderReference string Initial order reference for the subscription.