Webhook Expansion

Overview of Webhook Expansion, and the contents that return when you enable it.

By default, webhook events only include the ID of the event type. This can be an Account ID, Subscription ID, Product or Item ID, or an Order ID.

When you enable Webhook Expansion, it fully expands the following objects:

  • account
  • order
  • product or item
  • subscription

All account, order, product, and subscription information will return in your webhook. This way, you do not need to subscribe to as many webhook events or fill in the information with API calls.

Enable Webhook Expansion

  1. In the FastSpring App, navigate to Integrations > Webhooks.
  2. Create a new webhook, or select Edit Webhook Details on an existing webhook.
  3. Select the Enable Webhook Expansion checkbox.
  4. Save your changes.

Account Contents

The account object returns the following information about your customer.

Name

Type

Description

account

object

Houses details of the customer account.

    id

string

FastSpring-generated customer account ID.

    account

string

FastSpring-generated customer account ID.

    contact

object

Customer's contact details.

        first

string

Customer's first name.

        last

string

Customer's last name.

        email        

string

Customer's email address.

        company

string

Customer's associated company name.

        phone

string

Customer's phone number.

    language

string

2 character ISO code of the language associated with the customer's account.

    country

string

2 character ISO code of the country associated with the customer's account.

    lookup

object

Contains lookup IDs for the customer account.

        global

string

External customer account ID, generated by FastSpring.

        custom

string

Custom account ID specified via the /accounts endpoint of the [FastSpring API].

    url

string

URL of the Store's default account management page.

Order Contents

The order object returns the following information about the associated order session.

Name

Type

Description

order

object

Order information.

    order

string

Internal order ID. (backward compatibility)

    id

string

Internal order ID.

    reference

string

Customer-facing order reference.

    buyerReference

string

Purchase order number.

    completed

boolean

True for completed orders. Otherwise, false.

    changed

integer

Date of the most recent update, in milliseconds.

    changedValue

integer

Date of the most recent update, in milliseconds. (backward compatibility)

    changedInSeconds

integer

Date of the most recent update, in seconds.

    changedDisplay

string

Date of the most recent update to the order. This is formatted for display based on the language in which the order was processed.

    language

string

2 character ISO code of the order language.

    live

boolean

True indicates a live order. False indicates a test order.

    currency

string

3 character ISO code of the order currency.

    payoutCurrency

string

3 character ISO code of your disbursement currency.

    invoiceUrl

string

URL of the associated invoice.

    account

string

FastSpring-generated customer account ID.

    total

number

Order total in the transaction's currency.

    totalDisplay

string

Order total, formatted for display in the transaction's currency.

    totalInPayoutCurrency

number

Order total in your disbursement currency.

    totalInPayoutCurrencyDisplay

string

Order total formatted to display in your disbursement currency.

    tax

number

Tax amount

    taxDisplay

string

Tax amount, formatted for display in the transaction's currency.

    taxInPayoutCurrency

number

Tax amount in the currency of your FastSpring disbursements.

    taxInPayoutCurrencyDisplay

string

Tax amount, formatted for display in the currency of your FastSpring disbursements.

    subtotal

number

Order subtotal in the transaction's currency.

    subtotalDisplay

string

Order subtotal, formatted for display in the transaction's currency.

    subtotalInPayoutCurrency

number

Order subtotal in the currency of your FastSpring disbursements.

    subtotalInPayoutCurrencyDisplay

string

Order subtotal, formatted to display in the currency of your FastSpring disbursements.

    discount

number

Total amount of all discounts associated with the order. This displays in the currency associated with the subscription instance.

    discountDisplay

string

Total amount of all discounts associated with the order, formatted for display in the associated currency.

    discountInPayoutCurrency

number

Total amount of all discounts associated with the order, in your disbursement currency.

    discountInPayoutCurrencyDisplay

string

Total amount of all discounts associated with the order, formatted for display in your FastSpring disbursements currency.

    discountWithTax

number

Discount amount, including tax.

    discountWithTaxDisplay

string

Discount amount including tax, formatted for display in the transaction's currency

    discountWithTaxInPayoutCurrency

number

Discount amount including tax, in the currency of your FastSpring disbursements.

    discountWithTaxInPayoutCurrencyDisplay        

string

Discount amount including tax, formatted for display in the currency of your FastSpring disbursements.

    billDescriptor

string

Description information sent to the payment account for display on the customer's statement.

    payment

object

Payment method information.

        type

string

Payment method used for the order: paypal, amazon, creditcard, test, bank, alipay, purchase-order, free.

        creditcard

string

Type of credit or debit card used for the order: visa, mastercard, amex, discover, jcb, carteblanche, dinersclub, unionpay.

        cardEnding

string

Last four digits of the card number used for the order.

        bank

string

Type of bank transfer used to pay for the order: wire, brazilwire, ideal, giropay, sofort, ecard, sepa, alipay

    customer

object

Customer information.

        first

string

Customer's first name.

        last

string

Customer's last name.

        email

string

Customer's email address.

        company

string

Customer's company name.

        phone

string

Customer's telephone number.

    address

object

Address information associated with the order.

       city

string

City

        addressLine1

string

First line of the address. This is applicable when you enable Force physical address collection for all orders on your storefront.

        addressLine2

string

Second line of the address. This is applicable when you enable Force physical address collection for all orders on your storefront.

        regionCode

string

2 character ISO code of the US state.

        regionDisplay

string

State or region, formatted for display.

        region

string

State or region. (backward compatibility)

        postalCode

string

Postal code.

        country

string

Country.

        display

string

String of address information formatted for display.

    recipients

array

Customer and gift recipient information. This differs from customer and address information on gift purchases.

    recipient

object

Recipient information.

        first

string

Recipient's first name.

        last

string

Recipient's last name.

        email

string

Recipient's email address.

        company

string

Recipient's associated company.

        phone

string

Recipient's phone number.

        account

string

Recipient's FastSpring-generated customer account ID.

        address

object

Object containing recipient address information

            city

string

Recipient's city

            regionCode

string

2 character ISO code of the recipient's state.

            regionDisplay

string

Recipient's state or region, formatted for display.

            region

string

Recipient's state or region.

            postalCode

string

Recipient's postal code.

            country

string

Recipient's country.

            display

string

String of address information formatted for display.

    notes

array

Internal order notes. You can add notes within the app.

Product Contents

The product object returns the following information regarding the items within the order session.

Name

Type

Description

product

object

This object displays product information associated with the order.

    product

string

Product ID and path.

    parent

string

ID of the parent product. This only applies to variations.

    display

object

Customer-facing display name. This may include additional strings for each language.

    description

object

Contents of the product's Summary, Long Description, and Call to Action fields.

        summary

object

Contents of the product's Summary field. This may include additional strings for each language.

        action

object

Contents of the product's Call to Action field. This may include additional strings for each language.

        full

object

Contents of the product's Long Description field. This may include additional strings for each language.

    image

string

URL of the image file.

    sku

string

SKU ID of the product.

    fulfillments

object

Associated fulfillment information.

        instructions

object

Contents of the product's Post Order Instructions field. This may include additional strings for each language.

        <fulfillment action name>        

object

Fulfillment information. This object is repeated for each configured product.

            fulfillment

string

Fulfillment action name.

            name

string

Description of the fulfillment action type. This includes the file name for the file downloads.

            applicability

string

Settings from the Fulfillment Applicability field in the current fulfillment action. ALWAYS, BASE, REBILL ONLY, CONFIGURATION, NON_REBILL_ONLY

            display

string

Displays the name of the download if the fulfillment action is a Remote URL Download.

            url

string

Displays the download URL if the fulfillment action is a Remote URL Download.

            size

number

Displays the byte size of the download URL if the fulfillment action is a Remote URL Download.

            behavior

string

Setting of the download's Download Version Behavior field: PREFER_EXPLICIT or CURRENT.

            previous

array

Previous version of the download file, if you have updated it.

                display

string

Name of the previous version of the download file.

                size

integer

Size of the previous version of the download file.

                type

string

File type of the previous download file.

                modified

integer

Date of the most recent modification of this download file, in milliseconds.

    format

string

Product format: digital, physical, or digital-and-physical

    attributes

object

Product-level attributes. This may contain multiple strings consisting of key value pairs.

    pricing

object

Product pricing information.

        trial

integer

Number of free trial days, if applicable.

        renew

string

Renewal date.

        interval

string

Subscription rebill frequency.

        intervalLength

integer

Number of intervals between rebills.

        intervalCount

integer

Total number of expected rebills.

        quantityBehavior

string

Behavior of the quantity field: allow, lock, or hide.

        quantityDefault

integer

Default quantity for the product.

        price

object

Product price. This may contain multiple pairings for each currency.

        quantityDiscounts

object

Amount or percentage of the product-level discount.

When Use Volume Discounts is selected, this indicates the thresholds and corresponding amounts or percentages.

        dateLimitsEnabled

boolean

Indicate whether beginning and end dates have been configured.

        dateLimits

object

If date limits are enabled, this indicates the beginning and end date and time for the discount to be applied on an initial transaction.

            start

string

First date to which the discount will apply.

            end

string

Final date to which the discount will apply.

        discountReason

object

Customer-facing description of the discount. This may contain additional strings for each language.

        discountDuration

integer

Number of subscription billings (including the initial transaction) to which the discount will apply.

        reminderNotification

object

Payment reminder notifications configured for the subscription.

            enabled

boolean

True indicates payment reminders are enabled.
False indicates payment reminders are disabled.

            interval

string

Frequency of payment reminder notifications.

            intervalLength

integer

Number of intervals prior to the rebill date that FastSpring sends the

        overdueNotification

object

Details of the payment overdue notification configured for the product.

            enabled

boolean

Indicates whether payment overdue notifications are enabled for the subscription.

            interval

string

Frequency of payment overdue notifications.

            intervalLength

integer

Number of intervals following a declined rebill that FastSpring sends the first overdue payment notification.

            amount

integer

Total number of payment overdue notifications that FastSpring will send.

        cancellation

object

Cancellation settings applied when a rebill fails.

            interval

string

Interval unit that controls when the subscription will cancel after a failed billing.

            intervalLength        

integer

Number of cancelation intervals following a declined rebill. This can follow the last payment overdue notification if the the notifications are enabled.

Item Contents

The items array returns the following information regarding the items within the order session. This array may be used in place of the Products object above.

Name

Type

Description

items

array

One object for each item in the associated order.

    product

string

Product ID.

    quantity

integer

Product quantity.

    display

string

Customer-facing display name.

    sku

string

SKU ID of the product.

    subtotal

number

Product subtotal, in the transaction's currency.

    subtotalDisplay

string

Product subtotal, formatted for display in the transaction's currency.

    subtotalInPayoutCurrency

number

Product subtotal, in your disbursement currency.

    subtotalInPayoutCurrencyDisplay

string

Product subtotal, formatted to display in your disbursement currency.

    attributes

object

Product-level attributes for the associated product.

    discount

number

Discount amount applied to the product.

    discountDisplay

string

Discount amount applied to the product, formatted to display in the transaction's currency.

    discountInPayoutCurrency

number

Discount amount applied to the product, in your disbursement currency.

    discountInPayoutCurrencyDisplay    

string

Discount amount applied to the product, formatted to display in your disbursement currency.

    subscription

string
object

Subscription ID associated with the order. See Subscriptions below for full contents when webhook expansion is enabled.

Subscription Contents

The subscriptions object returns the following information regarding each subscription in the order session.

Name

Type

Description

subscriptions

object

Subscription information associated with the ID.

    id

string

Subscription ID.

    subscription

string

Subscription ID.

    active

boolean

Activation status.

    state

string

Current status of the subscription: "active", "overdue", "canceled", "deactivated", "trial"

    changed

integer

Date of the most recent change, in milliseconds.

    changedValue

integer

Date of the most recent change, in milliseconds. (backward compatibility)

    changedInSeconds

integer

Date of the most recent change, in seconds.

    chagedDisplay

string

Date of the most recent update to the order. This is formatted for display based on the language in which the order was processed.

    live

boolean

True indicates a live order. False indicates a test order.

    currency

string

3 character ISO code of the order currency.

    account

string

FastSpring customer account ID.

subscriptions.product

string

ID of the subscription

    display

string

Customer-facing display name.

    quantity

integer

Quantity of the subscription.

    adhoc

boolean

"True" for managed subscriptions. "False" for standard subscriptions.

    autoRenew

boolean

"True" for automatic subscriptions. "False" for manual renewal subscriptions.

    price

number

Amount of each subscription rebill.

    priceDisplay

string

Subscription rebill amount, formatted for display in the customer's currency.

    priceInPayoutCurrency

number

Subscription price, in your FastSpring disbursement currency.

    priceInPayoutCurrencyDisplay

string

Subscription price, formatted for display in your FastSpring disbursement currency.

    discount

number

Total discounted amount.

    discountDisplay

string

Total discounted amount in the subscription. This is formatted for display in the customer's currency.

    discountInPayoutCurrency

number

Total discounted amount in the subscription.

    discountInPayoutCurrencyDisplay   

string

Total discounted amount in the subscription. This is formatted for display in your disbursement currency.

    subtotal

number

Subscription subtotal. This does not include tax.

    subtotalDisplay

string

Subscription subtotal formatted to display in your disbursement currency.

    subtotalInPayoutCurrency

number

Subscription subtotal, in your disbursement currency.

    subtotalInPayoutCurrencyDisplay

string

Subscription subtotal formatted to display in your disbursement currency.

    attributes

object

Product-level attributes associated with the subscription.

    next

integer

Date of the next rebill, in milliseconds.

    nextValue

integer

Date of the next rebill. (backward compatibility)

    nextInSeconds

integer

Date of the next rebill, in seconds

    nextDisplay

string

Date of the next rebill. This is formatted to display based on the language selected for the original subscription order.

    end

integer

Expected end date of the subscription, in milliseconds. This applies to subscriptions with a pre-defined number of charges.

    endValue

integer

Expected end date of the subscription, in milliseconds. This applies to subscriptions with a pre-defined number of charges.(backward compatibility)

    endInSeconds

integer

Expected end date of the subscription (if any), in seconds. This applies to subscriptions with a pre-defined number of charges.

    endDisplay

string

Expected end date of the subscription (if any). This is formatted to display based on the language selected for the original subscription order.

    canceledDate

integer

Subscription cancelation date, in milliseconds.

    canceledDateValue

integer

Subscription cancelation date, in milliseconds. (backward compatibility)

    canceledDateInSeconds

integer

Subscription cancelation date, in seconds.

    canceledDateDisplay

string

Subscription cancelation date. This is formatted to display in the customer's language.

    deactivationDate

integer

Subscription deactivation date, in milliseconds. Null if the subscription is deactivated immediately.

    deactivationDateValue

integer

Subscription deactivation date, in milliseconds. Null if the subscription is deactivated immediately. (backward compatibility)

    deactivationDateInSeconds

integer

Subscription deactivation date, in seconds. Null if the subscription is deactivated immediately.

    deactivationDateDisplay

integer

Subscription deactivation date. This is formatted to display based on the language selected in the order. Null if the subscription is deactivated immediately.

    sequence

integer

Sequence number of the current billing period.

    periods

integer

Expected total number of rebills. This applies to subscriptions with a pre-defined number of charges.

    remainingPeriods

integer

Number of rebills remaining.

    begin

integer

Date that the subscription instance was created, in seconds.

    beginValue

integer

Date that the subscription instance was created, in milliseconds. (backward compatibility)

    beginInSeconds

integer

Date that the subscription instance was created, in seconds.

    beginDisplay

string

Date that the subscription began. This is formatted to display based on the language of the order.

    intervalUnit

string

Unit of time that defines the subscription charge interval: "adhoc", "day", "week", "month", "year".

    intervalLength

string

Number of intervalUnits per billing period.

    nextChargeCurrency

string

3 character ISO code of the currency to be used for the next rebill.

    nextChargeDate

string

Date of the next rebill, in milliseconds. (backward compatibility)

    nextChargeDateDisplay

string

Date of the next rebill, formatted for display based on the language selected for the order.

    nextChargeTotal

number

Next rebill amount.

    nextChargeTotalDisplay

string

Next rebill amount, formatted for display based on the nextChargeCurrency.

    nextChargeTotalInPayoutCurrency

number

Next rebill amount, in the currency of your FastSpring disbursements.

    nextChargeTotalInPayoutCurrencyDisplay   

string

Next rebill amount, formatted for display in the currency of your FastSpring disbursements.

    nextNotificationType

string

Type of notification that is next. "TRIAL_REMINDER", "PAYMENT_REMINDER", "PAYMENT_OVERDUE"

    nextNotificationDate

integer

Date of the next reminder notification, in milliseconds.

    nextNotificationDateValue

integer

Date of the next reminder notification, in milliseconds. (backward compatibility)

    nextNotificationDateInSeconds

integer

Date of the next reminder notification, in seconds.

    nextNotificationDateDisplay

string

Date of the next reminder email, formatted for display based on the language of the original order.

    trialReminder

object

Defines when customers will receive trial reminder notifications.

        intervalUnit

integer

Unit of time used to define when customers will receive trial reminder notifications: "day", "week", "month", "year".

        intervalLength

integer

Number of interval units prior to the first subscription charge that

    paymentReminder

object

Timing of the customer-facing reminder email message sent before each rebill.

        intervalUnit

string

Unit of time used to define when customers will receive trial reminder notifications: "day", "week", "month", "year".

        intervalLength

integer

Number of intervalUnitsPrior to each scheduled rebill that FastSpring sends the payment reminder.

    paymentOverdue

object

Timing of customer-facing payment overdue notification when a rebill fails.

        intervalUnit

string

Unit of time used to define when customers will receive payment overdue notifications in reference to the failed rebill.

        intervalLength

integer

Number of interval units following the failed rebill that FastSpring sends the first overdue payment notification.

        total

integer

Total number of payment overdue notifications to be sent.

        sent

integer

Number of payment overdue notifications that have been sent to date.

    cancellationSetting

object

Timing of automatic subscription cancellation after a failed rebill.

        cancellation

string

Event used to determine the timing of automatic subscription cancellation, as configured for the subscription: AFTER_LAST_NOTIFICATION or AFTER_PAYMENT_FAILURE

        intervalUnit

string

Unit of time used to determine when a subscription will be canceled as a result of a failed rebill.

        intervalLength

integer

Number of interval units following the event trigger that the subscription will be canceled due to a failed subscription billing.

    discounts

array

Coupon applied to the subscription, if any.

        totalDiscountValue

number

Total discount amount that will apply. This is only present

        discountPath

string

ID of the coupon applied to the subscription.

        discountDuration

integer

Total number of billings to which the coupon applies.

        percentValue

string

Discount percent applied to the subscription.

        discountValue

string

Discount amount per billing period.

    instructions

array

Rebill instructions.

        type

string

Type of instructions. May have more than one instruction object, when applicable.

        periodStartDate

integer

Date of the beginning of the instruction period, in milliseconds.

        periodStartDateValue

integer

Date of the beginning of the instruction period, in milliseconds. (backward compatibility)

        periodStartDateInSeconds

integer

Date of the beginning of the instruction period, in seconds.

            periodStartDateDisplay

string

Date of the beginning of the instruction period, formatted for display based on the order language.

        periodEndDate

integer

Date of the end of the instruction period, in milliseconds.

        periodEndDateValue

integer

Date of the end of the instruction period, in milliseconds. (backward compatibility)

        periodEndDateInSeconds

integer

Date of the end of the instruction period, in seconds.

        periodEndDateDisplay

string

Date of the end of the instruction period, formatted for display based on the order language.

        discountDurationUnit

string

Appears when instructions type is "discounted" or "trial"; unit of time used in conjunction with DurationLength to determine the total discount duration.

        discountDurationLength

integer

Appears when instructions type is "discounted" or "trial"; number of discountDurationUnits in the total discount period.

        .discountPercent

integer

Discount percent for the current instruction period.

        discountPercentValue

integer

Discount percent for the current instruction period. (backward compatibility)

        discountPercentDisplay

string

Discount percent for the current instruction period, formatted for display.

        unitDiscount

number

Discount percent for the current instruction period, in the customer's currency.

        unitDiscountDisplay

string

Discount amount per unit for the current instruction period, formatted for display in the customer's currency.

        unitDiscountInPayoutCurrency

number

Discount amount per unit for the current instruction period, in your disbursement currency.

        unitDiscountInPayoutCurrencyDisplay

string

Discount amount per unit for the current instruction period, formatted for display in your disbursement currency.

        discountTotal

number

Total discount amount for the current instruction period, in the customer's currency.

        discountTotalDisplay

string

Total discount amount for the current instruction period, formatted for display in the customer's currency.

        discountTotalInPayoutCurrency

number

Total discount amount for the current instruction period, in your disbursement currency.

        discountTotalInPayoutCurrencyDisplay

string

Total discount amount for the current instruction period, formatted to display in your disbursement currency.

        price

number

Product list price, prior to discounts.

        priceDisplay

string

Product list price, prior to discounts. This is formatted to display in the customer's currency.

        priceInPayoutCurrency

number

Product list price, prior to discounts, in your disbursement currency.

        priceInPayoutCurrencyDisplay

string

Product list price, prior to discounts. This is formatted to display in your disbursement currency.

        priceTotal

number

Total price of the current instruction period.

        priceTotalDisplay

string

Total price of the current instruction period. This is formatted to display in the customer's currency.

        priceTotalInPayoutCurrency

number

Total price of the current instruction period. This is formatted to display in your disbursement currency.

        priceTotalInPayoutCurrencyDisplay

string

Total price of the current instruction period. This is formatted to display in your disbursement currency.

        unitPrice

number

Unit price of the instruction period, after the discount is applied.

        unitPriceDisplay

string

Unit price of the current instruction period, after the discount is applied. This is formatted to display in the customer's currency.

        unitPriceInPayoutCurrency

number

Unit price of the current instruction period, after the discount is applied. This is formatted to display in the your disbursement currency.

        unitPriceInPayoutCurrencyDisplay

string

Unit price of the current instruction period, after the discount is applied. This is formatted to display in the your disbursement currency.

        customReferenceID

string

Use POST /subscriptions to add a value to a subscription instance via the FastSpring API


Did this page help you?