FastSpring AppAPI ReferenceWebhooksJavaScript LibraryChangelogFastSpring.com
Developer Documentation
Sign In

Co-term Payment Charge Failed

Event payload example and property overview for subscription.group.payment.charge.failed

Webhook response payload example (expansion enabled)

When a subscription.group.payment.charge.failed event is triggered, the webhook sends the following JSON payload:

{
  "cotermGroupId": "aB1c2deFGhIjKL3mn-opqR",
  "cotermGroupDisplayName": "Tech Services Monthly Plan",
  "cotermGroupPeriodStartDate": 1754044800000,
  "cotermGroupPeriodEndDate": 1756646400000,
  "cotermGroupPrimarySubscription": "1abc2DE_FGhIjKLm3NoPQR",
  "cotermGroupStatus": "DUNNING",
  "cotermGroupOrderId": "aBCDE12fGH3iJkL4mNOpq",
  "cotermNextChargeDate": 1756646400000,
  "cotermNextChargeTotal": 199.95,
  "cotermNextChargeTotalDisplay": "$199.95",
  "cotermGroupSize": 2,
  "currency": "USD",
  "total": 40,
  "status": "failed",
  "timestamp": 1739203714927,
  "reason": "EXPIRED_CARD",
  "account": {
    "id": "abCdE1FGH2Hij3KLMnOpqR",
    "account": "abCdE1FGH2Hij3KLMnOpqR",
    "contact": {
      "first": "Jane",
      "last": "Doe",
      "email": "jane.doe@company.com",
      "company": null,
      "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"
  },
  "paymentOverdue": {
    "intervalUnit": "week",
    "intervalLength": 1,
    "total": 4,
    "sent": 0
  },
  "cancellationSetting": {
    "cancellation": "AFTER_LAST_NOTIFICATION",
    "intervalUnit": "week",
    "intervalLength": 1
  },
  "subscriptions": [
    {
      "id": "1abc2DE_FGhIjKLm3NoPQR",
      "active": true,
      "state": "overdue",
      "isSubscriptionEligibleForPauseByBuyer": false,
      "isPauseScheduled": false,
      "changed": 1739203715234,
      "live": false,
      "currency": "USD",
      "account": "abCdE1FGH2Hij3KLMnOpqR",
      "product": "cloud-storage",
      "sku": "SKU-CS-101",
      "display": "Cloud Storage Service",
      "quantity": 1,
      "adhoc": false,
      "autoRenew": true,
      "price": 10,
      "discount": 0,
      "subtotal": 20,
      "next": 1744329600000,
      "end": null,
      "canceledDate": null,
      "deactivationDate": null,
      "sequence": 1,
      "periods": null,
      "remainingPeriods": null,
      "begin": 1738265837569,
      "intervalUnit": "month",
      "intervalUnitAbbreviation": "mo",
      "intervalLength": 1,
      "nextChargeCurrency": "USD",
      "nextChargeDate": 1744329600000,
      "nextChargePreTax": 18.52,
      "nextChargeTotal": 20,
      "addons": null,
      "discounts": null,
      "fulfillments": {},
      "instructions": [
        {
          "product": "cloud-storage",
          "type": "regular",
          "isNotTrial": true,
          "periodStartDate": 1738195200000,
          "periodEndDate": null,
          "discountIntervalUnit": null,
          "discountDurationLength": null,
          "discountDuration": null,
          "discountDurationUnit": null,
          "intervalUnit": "month",
          "intervalLength": 1,
          "discountPercent": 0,
          "discountTotal": 0,
          "unitDiscount": 0,
          "price": 10,
          "priceDisplay": "$10.00",
          "priceTotal": 20,
          "unitPrice": 10,
          "total": 20,
          "totalWithTaxes": 20
        }
      ]
    },
    {
      "id": "2abc2DE_FGhIjKLm3NoPQR",
      "active": true,
      "state": "overdue",
      "isSubscriptionEligibleForPauseByBuyer": false,
      "isPauseScheduled": false,
      "changed": 1739203715234,
      "live": false,
      "currency": "USD",
      "account": "abCdE1FGH2Hij3KLMnOpqR",
      "product": "data-analytics",
      "sku": "SKU-DA-102",
      "display": "Data Analytics Service",
      "quantity": 1,
      "adhoc": false,
      "autoRenew": true,
      "price": 10,
      "discount": 0,
      "subtotal": 10,
      "next": 1744329600000,
      "end": null,
      "canceledDate": null,
      "deactivationDate": null,
      "sequence": 1,
      "periods": null,
      "remainingPeriods": null,
      "begin": 1738256076037,
      "intervalUnit": "month",
      "intervalUnitAbbreviation": "mo",
      "intervalLength": 1,
      "nextChargeCurrency": "USD",
      "nextChargeDate": 1744329600000,
      "nextChargePreTax": 9.26,
      "nextChargeTotal": 10,
      "addons": null,
      "discounts": null,
      "fulfillments": {},
      "instructions": [
        {
          "product": "data-analytics",
          "type": "regular",
          "isNotTrial": true,
          "periodStartDate": 1738195200000,
          "periodEndDate": null,
          "discountIntervalUnit": null,
          "discountDurationLength": null,
          "discountDuration": null,
          "discountDurationUnit": null,
          "intervalUnit": "month",
          "intervalLength": 1,
          "discountPercent": 0,
          "discountTotal": 0,
          "unitDiscount": 0,
          "price": 10,
          "priceDisplay": "$10.00",
          "priceTotal": 10,
          "unitPrice": 10,
          "total": 10,
          "totalWithTaxes": 10
        }
      ]
    }
  ]
}

Webhook response payload properties

The webhook response properties table outlines each property in the subscription.group.payment.charge.failed event JSON payload, specifying their name, data type, and description.

Name Type Description
Co-term Group Information
cotermGroupId string Unique identifier for the co-term group.
cotermGroupDisplayName string Display name of the co-term group. This property is optional when creating a co-term group.
cotermGroupPeriodStartDate integer Start date of the co-term group period, in milliseconds.
cotermGroupPeriodEndDate integer End date of the co-term group period, in milliseconds.
cotermGroupPrimarySubscription string ID of the primary subscription in the co-term group. This property represents the most recently purchased subscription within the group.
cotermGroupStatus string Status of the co-term group (e.g., "DUNNING").
cotermGroupOrderId string Order ID associated with the co-term group.
cotermNextChargeDate integer Next charge date for the co-term group in milliseconds. This value is computed by adding one day to the length of the current term (see the monthly and yearly subscription examples below).

Monthly Subscription: If the co-term is initiated on February 11, the next charge date becomes March 12 (one full month plus one day).

Yearly Subscription: If initiated on February 11, 2025, the next charge date becomes February 12, 2026 (one full year plus one day).
cotermNextChargeTotal number Total amount for the next charge.
cotermGroupSize string Number of subscriptions in the co-term group.
currency string Currency code used (e.g., "USD").
total integer Total amount for the order.
status string Status of the order (e.g., "failed").
timestamp integer Timestamp when the order was recorded, in milliseconds.
reason string Reason why the payment failed (e.g., "EXPIRED_CARD").
Account Object
account object Account object containing account details.
account.id string Unique identifier for the account.
account.account string FastSpring-generated customer account ID.
account.contact.first string First name of the account contact.
account.contact.last string Last name of the account contact.
account.contact.email string Email address of the account contact.
account.contact.company string Company name of the account contact.
account.contact.phone string Phone number of the account contact.
account.contact.subscribed boolean Indicates if the account contact is subscribed.
account.address.address line 1 string First line of the account address.
account.address.address line 2 string Second line of the account address.
account.address.city string City of the account address.
account.address.country string Country of the account address (ISO code).
account.address.postal code string Postal code of the account address.
account.address.region string Region or state of the account address.
account.address.region custom string Custom region information for the account address.
account.address.company string Company associated with the account address.
account.language string Preferred language of the account (e.g., "en").
account.country string Country code for the account.
account.lookup.global string Global lookup identifier for the account.
account.url string URL to access the account details.
Payment Overdue Object
paymentOverdue.intervalUnit string Unit of time indicating when FastSpring sends the customer an overdue payment notification (e.g., "week").
paymentOverdue.intervalLength integer Number of intervalUnits following the failed rebill that FastSpring will send the first payment overdue notification.
paymentOverdue.total integer Total number of payment overdue notifications to be sent, including the first one.
paymentOverdue.sent integer Number of payment overdue notifications that have been sent to date.
Cancellation Settings Object
cancellationSetting.cancellation string Cancellation policy for the co-term group. Determines the timing of automatic cancellation (e.g., "AFTER_LAST_NOTIFICATION" or "AFTER_PAYMENT_FAILURE").
cancellationSetting.intervalUnit string Unit of time for the cancellation interval (e.g., "week").
cancellationSetting.intervalLength integer Number of intervalUnits following the cancellation event that the co-term group will be canceled.
Subscriptions Array
subscriptions.id string Unique identifier for the subscription.
subscriptions.active boolean Indicates if the subscription is active.
subscriptions.state string Current state of the subscription (e.g., trial, active, canceled).
subscriptions.isSubscriptionEligibleForPauseByBuyer boolean Indicates if the subscription can be paused by the buyer.
subscriptions.isPauseScheduled boolean Indicates if a pause is scheduled for the subscription.
subscriptions.changed integer Timestamp of the last change in milliseconds.
subscriptions.live boolean Indicates if the subscription is live or in test mode.
subscriptions.currency string 3-character ISO code of the currency used for billing (e.g., "USD")
subscriptions.account string Account ID associated with the subscription.
subscriptions.product string Product associated with the subscription.
subscriptions.sku string Stock Keeping Unit (SKU) for the subscription (if applicable).
subscriptions.display string Display name of the subscription product.
subscriptions.quantity integer Quantity of the subscription product.
subscriptions.adhoc boolean Indicates if the subscription is ad-hoc.
subscriptions.autoRenew boolean Indicates if the subscription is set to auto-renew.
subscriptions.price number Price of the subscription.
subscriptions.discount number Discount amount applied to the subscription.
subscriptions.subtotal number Subtotal amount of the subscription.
subscriptions.next integer Next charge date for the subscription in milliseconds.
subscriptions.end string End date of the subscription (if applicable).
subscriptions.canceledDate string Date when the subscription was canceled (if applicable).
subscriptions.deactivationDate string Date when the subscription was deactivated (if applicable).
subscriptions.sequence integer Sequence number of the current billing period.
subscriptions.periods string Total number of billing periods. This applies to subscriptions with a fixed number of rebills.
subscriptions.remainingPeriods string Number of remaining rebills. This is based on the number of expected periods.
subscriptions.begin integer Date that the subscription was activated, in milliseconds.
subscriptions.intervalUnit string Time unit used to determine the subscription's rebill frequency (e.g., adhoc, day, week, month, year).
subscriptions.intervalUnitAbbreviation string Abbreviation for the interval unit (e.g., "wk").
subscriptions.intervalLength integer Number of intervalUnits per billing period for the subscription.
subscriptions.nextChargeCurrency string 3-character ISO currency code for the next charge (e.g., "USD").
subscriptions.nextChargeDate integer Next charge date for the subscription in milliseconds.
subscriptions.nextChargePreTax integer Pre-tax amount for the next charge.
subscriptions.nextChargeTotal integer Total amount for the next charge.
Add-ons Array (within Subscriptions array)
subscriptions.addons.product string Product (product-path) associated with the add-on.
subscriptions.addons.sku string SKU for the add-on (if applicable).
subscriptions.addons.display string Display name for the add-on.
subscriptions.addons.quantity integer Quantity of the add-on.
subscriptions.addons.price integer Price per unit of the add-on.
subscriptions.addons.discount integer Coupon amount applied to the add-on.
subscriptions.addons.subtotal integer Subtotal amount for the add-on.
subscriptions.addons.subtotalDisplay integer Add-on subtotal, formatted for display.
subscriptions.addons.discounts array Coupon code(s) applied to the add-on.
Fulfillments Object (within Subscriptions array)
subscriptions.fulfillments object Fulfillment details for the subscription.
Instructions Array (within Subscriptions array)
subscriptions.instructions.product string Product (product-path) associated with the instruction.
subscriptions.instructions.type string Type of instruction.

A subscription may have more than one instructions 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
subscriptions.instructions.isNotTrial boolean Indicates if the instruction is not a trial.
subscriptions.instructions.periodStartDate integer Start date of the period in milliseconds.
subscriptions.instructions.periodEndDate string End date of the period (if applicable).
subscriptions.instructions.discountIntervalUnit integer Number of discount duration units remaining, excluding the current discount period.

Only appears when type is "discounted" or "trial".
subscriptions.instructions.discountDurationLength integer Number of discount duration units remaining, excluding the current discount period.

Only appears when type is "discounted" or "trial".
subscriptions.instructions.discountDuration integer Number of discount duration units remaining, excluding the current discount period.

Only appears when type is "discounted" or "trial".
subscriptions.instructions.discountDurationUnit string Unit of time used to determine the remaining discount duration, excluding the current discount period.

Only appears when type is "discounted" or "trial".
subscriptions.instructions.intervalUnit string Time unit for the interval (e.g., "week").
subscriptions.instructions.intervalLength integer Length of the interval.
subscriptions.instructions.discountPercent integer Discount percentage applied to the instruction.
subscriptions.instructions.discountTotal integer Total discount applied to the instruction.
subscriptions.instructions.unitDiscount integer Discount per unit for the instruction.
subscriptions.instructions.price integer Price per unit for the instruction.
subscriptions.instructions.priceTotal integer Total price for the instruction.
subscriptions.instructions.unitPrice integer Unit price for the instruction before taxes.
subscriptions.instructions.total integer Total amount for the instruction before taxes.
subscriptions.instructions.totalWithTaxes integer Total amount for the instruction including taxes.