With Split Partner Accounts, FastSpring can send your partner a percentage of your sales or revenue. Your partner will receive the percentage of profits that you request for them.

Add a Partner to your Account

If you are interested in adding a partner to your Store, follow the steps below:

  1. Navigate to the FastSpring Payee Signup Form. In the URL, replace XXXXCOMPANYIDXXXX with your company ID.
  2. Send this form to your partner to fill out.
  3. Contact our support team with the following information:

After Support configures the partner account, FastSpring will automatically deduct the requested shares from your payout.

If a customer returns their product, FastSpring transfers your partner’s share to your account. Then, we issue the refund from your account, however we retain the order fees.

Types of Shares

When you request to add a partner, specify whether the partner will receive a percentage of the sale price or overall revenue. 

Limiting Products and Stores

When you request to add a partner to your store, indicate the limitations of the partner. For example, you may only want to share profits from specific products, or a specific store. Profits which you can limit include:

Whoops.

We had trouble finding that documentation article.

Please try again – you can search at the top of the page,
or use the left hand navigation to find helpful articles.

The account.created server webhook event fires when a customer account is created. For example, when a customer whose email address does not match an existing account places a new order, a new customer account is created, and this event fires. Customer Accounts and single sign-on provides detailed information regarding customer accounts.

 About Webhook Expansion

account.created is not affected by webhook expansion.

 IMPORTANT

Each post from FastSpring to your endpoint may contain more than one webhook event in its payload. For more information, please see About Webhooks.

 

Contents of Event Payload

Name Type Description
id string FastSpring-generated customer account ID
account string FastSpring-generated customer account ID
contact object contains customer contact details
contact.first string customer's first name
contact.last string customer's last name
contact.email string customer's email address
contact.company string customer's company name (may be null)
contact.phone string customer's telephone number (may be null)
language string two-character ISO code for the customer's language
country string two-character ISO code for the customer's country
lookup object parameters used to look up the account (e.g. via the FastSpring API)
lookup.global string customer-visible account ID
lookup.custom string optional custom account ID assigned by you (e.g., your internal ID for this customer)
lookup.url string default URL for the customer-facing account management page

 

Example

account.created webhook example
{ 
  "id":"TBODFuwPRX2OiZj3u0MlQw",
  "account":"TBODFuwPRX2OiZj3u0MlQw",
  "contact":{
    "first":"John",
    "last":"Doe",
    "email":"ne1@all.com",
    "company":null,
    "phone":"1-805-409-9008"
  },
  "language":"en",
  "country":"US",
  "lookup":{
    "global":"lc3PZF_mSIiwV2ZUvcoZSQ",
    "custom" : "8675309"
    "url":"https://yourexamplestore.onfastspring.com/account"
  }
}

The payoutEntry.created server webhook event fires when a payout event has been created – e.g., for an order or a return.

 About Webhook Expansion

When webhook expansion is enabled, payoutEntry.created includes the entire order (or return)account, and subscription objects (if applicable). With expansion disabled, the event has only the order ID, the account ID, and the subscription ID rather than the full objects.

 IMPORTANT

Each post from FastSpring to your endpoint may contain more than one webhook event in its payload. For more information, please see About Webhooks.

 

Contents of Event Payload

The contents of the payoutEntry.created event payload varies depending on whether the triggering event is an order or a return. For events triggered by an order (including subscription billings), the order ID (and optionally, the entire order object) appear in the payload. For events triggered by a return, the return ID (and optionally, the entire return object) appears. Regardless of the triggering event type, the payload includes the account ID (and optionally, the entire account object), as well as the subtractions and payouts objects.

Name Type Description
When the triggering event is an order (including subscription billings)
orderID string internal order ID
reference string customer-visible order reference
live Boolean "false" for a test order
order string (expansion disabled)
object (expansion enabled)
internal order ID (expansion disabled)
order object with all order details (expansion enabled)
order.order string internal order ID
order.id string internal order ID
order.reference string customer-visible order reference
order.buyerReference string optional purchase order number entered by the customer
order.completed Boolean "true" for a completed order; "false" if not completed
order.changed integer date of the most recent update to the order record, in milliseconds
order.changedValue integer date of the most recent update to the order record, in milliseconds
(backward compatibility)
order.changedInSeconds integer date of the most recent update to the order record, in seconds
order.changedDisplay string date of the most recent update to the order record, formatted for display based on the language in which the order was processed
order.language string two-character ISO code for the order language
order.live Boolean "false" for a test order
order.currency string three-character ISO code for the order currency
order.payoutCurrency string three-character ISO code for the currency in which your disbursement will be made
order.invoiceUrl string URL of the customer-facing invoice for this order
order.account string FastSpring-generated customer account ID
order.total number order total in the transaction's currency
order.totalDisplay string order total, formatted for display in the transaction's currency
order.totalInPayoutCurrency number order total in the currency of your FastSpring disbursements
order.totalInPayoutCurrencyDisplay string order total, formatted for display in the currency of your FastSpring disbursements
order.tax number amount of tax
order.taxDisplay string amount of tax, formatted for display in the transaction's currency
order.taxInPayoutCurrency number amount of tax in the currency of your FastSpring disbursements
order.taxInPayoutCurrencyDisplay string amount of tax, formatted for display in the currency of your FastSpring disbursements
order.subtotal number order subtotal in the transaction's currency
order.subtotalDisplay string order subtotal, formatted for display in the transaction's currency
order.subtotalInPayoutCurrency number order subtotal in the currency of your FastSpring disbursements
order.subtotalInPayoutCurrencyDisplay string order subtotal, formatted for display in the currency of your FastSpring disbursements
order.discount number total discount applied to the order in the transaction's currency
order.discountDisplay string total discount applied to the order, formatted for display in the transaction's currency
order.discountInPayoutCurrency number total discount applied to the order, in the currency of your FastSpring disbursements
order.discountInPayoutCurrencyDisplay string total discount applied to the order, formatted for display in the currency of your FastSpring disbursements
order.discountWithTax number discount amount including tax
order.discountWithTaxDisplay string discount amount including tax, formatted for display in the transaction's currency
order.discountWithTaxInPayoutCurrency number discount amount including tax, in the currency of your FastSpring disbursements
order.discountWithTaxInPayoutCurrencyDisplay string discount amount including tax, formatted for display in the currency of your FastSpring disbursements
order.billDescriptor string description information sent to the payment account for display on the customer's statement
order.payment object details about the transaction's payment method
order.payment.type string payment method used for the order: "paypal", "amazon", "creditcard", "test", "bank", "alipay", "purchase-order", "free"
order.payment.creditcard string (appears when payment.type = creditcard); type of credit or debit card used for the order: "visa", "mastercard", "amex", "discover", "jcb", "carteblanche", "dinersclub", "unionpay"
order.payment.cardEnding string (appears when payment.type = creditcard); last four digits of the card number used for the order
order.payment.bank string (appears when payment.type = bank); type of bank transfer used to pay for the order: "wire", "brazilwire", "ideal", "giropay", "sofort", "ecard", "sepa", "alipay"
order.customer object details about the customer
order.customer.first string customer's first name
order.customer.last string customer's last name
order.customer.email string customer's email address
order.customer.company string customer's company name
order.customer.phone string customer's telephone number
order.address object details about the customer address associated with this order
order.address.city string name of the city in the address
order.address.addressLine1 string first address line (for physical shipments or when Force physical address collection for all orders is enabled for the Storefront)
order.address.addressLine2 string second, optional address line (for physical shipments or when Force physical address collection for all orders is enabled for the Storefront)
order.address.regionCode string two-character ISO code for the state of the address (present for U.S. addresses only)
order.address.regionDisplay string state or region of the address, formatted for display
order.address.region string state or region of the address (backward compatibility)
order.address.postalCode string postal code of the address
order.address.country string country of the address
order.address.display string concatenated string of address information, formatted for display
order.recipients array details on the customer and the recipient of gift purchases; for non-gift purchases, info will be the same as order.customer and order.address info
order.recipients.recipient object object containing all details of the current recipient in the array
order.recipients.recipient.first string recipient's first name
order.recipients.recipient.last string recipient's last name
order.recipients.recipient.email string recipient's email address
order.recipients.recipient.company string recipient's company (optional)
order.recipients.recipient.phone string recipient's phone number
order.recipients.recipient.account string recipient's FastSpring-generated customer account ID
order.recipients.recipient.address object multi-line object containing recipient address information
order.recipients.recipient.address.addressLine1 string recipient's street address (when a physical product was in the order or "Force physical address collection" was enabled)
order.recipients.recipient.address.city string recipient's city
order.recipients.recipient.address.regionCode string two-character ISO code for the state of the address (present for U.S. addresses only)
order.recipients.recipient.address.regionDisplay string state or region of the address, formatted for display
order.recipients.recipient.address.region string state or region of the address
order.recipients.recipient.address.postalCode string postal code of the address
order.recipients.recipient.address.country string country of the address
order.recipients.recipient.address.display string concatenated string of address information, formatted for display
order.notes array optional internal order notes entered via the FastSpring App
order.items array products included in the order, one object per product
order.items.product string product path / product ID
order.items.quantity integer quantity of the current product in this transaction
order.items.display string customer-facing Display name of the product
order.items.sku string optional internal SKU ID (e.g., your part number) for the current product
order.items.subtotal number subtotal for the current product, in the transaction's currency
order.items.subtotalDisplay string subtotal for the current product, formatted for display in the transaction's currency
order.items.subtotalInPayoutCurrency number subtotal for the current product, in the currency of your FastSpring disbursements
order.items.subtotalInPayoutCurrencyDisplay string subtotal for the current product, formatted for display in the currency of your FastSpring disbursements
order.items.attributes object multiple-field object containing optional product-level attributes for the current product
order.items.discount number amount of any discount applied to the current product
order.items.discountDisplay string amount of any discount applied to the current product, formatted for display in the transaction's currency
order.items.discountInPayoutCurrency number amount of any discount applied to the current product, in the currency of your FastSpring disbursements
order.items.discountInPayoutCurrencyDisplay string amount of any discount applied to the current product, formatted for display in the currency of your FastSpring disbursements
order.items.subscription string ID of the subscription associated with the current product (if applicable)
order.items.fulfillments object multiple-field object containing details of fulfillment actions associated with the current product (file, license, or instructions)
order.items.fulfillments.<fulfillment ID> array identifier for the current fulfillment action (other than instructions); array consists of fulfillment attributes
order.items.fulfillments.<fulfillment ID>.license string (when "type" = "license") license key associated with the current fulfillment action
order.items.fulfillments.<fulfillment ID>.display string name of the current fulfillment action: when "type" = "license", "License Key"
when "type" = "file", <download file name>
order.items.fulfillments.<fulfillment ID>.size integer (when "type" = "file") size of the download file, in bytes
order.items.fulfillments.<fulfillment ID>.file string (when "type" = "file") order-specific URL for the product download associated with this fulfillment action
order.items.fulfillments.<fulfillment ID>.type string "license" or "file"
order.items.fulfillments.instructions string contents of the Post Order Instructions field for the current product
order.items.driver object when the current item was sold as a cross-sell or an upsell, or when the current item is a bundle child or a subscription's
one-time setup fee, this indicates the relationship to driving product
order.items.driver.type string relationship to parent / triggering item (e.g. "cross-sell", "bundle", "configuration", "one_time_fee")
order.items.driver.path string product path / ID of parent / triggering item;
when type = "cross-sell" this indicates the triggering item;
when type = "bundle" this indicates in the bundle parent, meaning that the current item is a child of the specified bundle product
when type = "configuration" this indicates the triggering item (as with a cross-sell)
when type = "one_time_fee" this indicates the subscription product with which the one-time setup fee is associated
order.coupons array list of coupon IDs applied to the order (currently, only one coupon can be applied to an order)
When the triggering event is a return
return string (expansion disabled)
object (expansion enabled)
internal return ID (expansion disabled)
return object with all return details (expansion enabled)
return.return string return ID
return.reference string customer-facing return reference
return.completed Boolean "true" for a completed return, never false in this context
return.changed integer date of the most recent update to the return record, in milliseconds
return.changedValue integer date of the most recent update to the return record, in milliseconds
(backward compatibility)
return.changedInSeconds integer date of the most recent update to the return record, in seconds
return.changedDisplay string date of the most recent update to the return record, formatted for display based on the language in which the order was processed
return.live Boolean "false" for returns on a test order
return.account string FastSpring-generated customer account ID
return.currency string three-character ISO code for the return currency (which is always the same as the original order currency)
return.payoutCurrency string three-character ISO code for the currency in which your disbursements are made
return.totalReturn number total return amount
return.totalReturnDisplay string total return amount, formatted for display in return.currency
return.totalReturnInPayoutCurrency number total return amount, in the currency in which your disbursements are made
return.totalReturnInPayoutCurrencyDisplay string total return amount, formatted for display in the currency in which your disbursements are made
return.tax number amount of tax
return.taxDisplay string amount of tax, formatted for display in the transaction's currency
return.taxInPayoutCurrency number amount of tax in the currency of your FastSpring disbursements
return.taxInPayoutCurrencyDisplay string amount of tax, formatted for display in the currency of your FastSpring disbursements
return.subtotal number return subtotal in return.currency
return.subtotalDisplay string return subtotal formatted for display in return.currency
return.subtotalInPayoutCurrency number return subtotal in the currency in which your FastSpring disbursements are made
return.subtotalInPayoutCurrencyDisplay string return subtotal formatted for display in the currency in which your FastSpring disbursements are made
return.totalRefundInPayoutCurrency number total refund amount, in the currency in which your FastSpring disbursements are made
return.payment object details about the transaction's–and the return's–payment method
return.payment.type string payment method used for the order: "paypal", "amazon", "creditcard", "test", "bank", "alipay", "purchase-order", "free"
return.payment.creditcard string (appears when payment.type = creditcard); type of credit or debit card used for the order: "visa", "mastercard", "amex", "discover", "jcb", "carteblanche", "dinersclub", "unionpay"
return.payment.cardEnding string (appears when payment.type = creditcard); last four digits of the card number used for the order
return.payment.bank string (appears when payment.type = bank); type of bank transfer used to pay for the order: "wire", "brazilwire", "ideal", "giropay", "sofort", "ecard", "sepa", "alipay"
return.reason string pre-defined return reason selected while processing the return
return.note string optional comment/note entered while processing the return
return.original object details of the original order being returned
return.original.id string internal order ID
return.original.order string internal order ID
return.original.reference string customer-visible order reference
return.original.account string FastSpring-generated customer account ID
return.original.currency string currency of the original order
return.original.payoutCurrency string currency in which your FastSpring disbursements are made, as of the time of the original order
return.original.total number order total in the transaction's currency
return.original.totalDisplay string order total, formatted for display in the transaction's currency
return.original.totalInPayoutCurrency number order total in the currency of your FastSpring disbursements
return.original.totalInPayoutCurrencyDisplay string order total, formatted for display in the currency of your FastSpring disbursements
return.original.tax number amount of tax
return.original.taxDisplay string amount of tax, formatted for display in the transaction's currency
return.original.taxInPayoutCurrency number amount of tax in the currency of your FastSpring disbursements
return.original.taxInPayoutCurrencyDisplay string amount of tax, formatted for display in the currency of your FastSpring disbursements
return.original.subtotal number order subtotal in the transaction's currency
return.original.subtotalDisplay string order subtotal, formatted for display in the transaction's currency
return.original.subtotalInPayoutCurrency number order subtotal in the currency of your FastSpring disbursements
return.original.subtotalInPayoutCurrencyDisplay string order subtotal, formatted for display in the currency of your FastSpring disbursements
return.original.notes string text of any optional internal note(s) entered for the original order
return.customer object details of the customer to whom any refund is being made
return.customer.first string customer's first name
return.customer.last string customer's last name
return.customer.email string customer's email address
return.customer.company string customer's company name
return.customer.phone string customer's telephone number
return.items array an array consisting of a separate object for each product being returned
return.items.product string product path/product ID of the current product being returned
return.items.quantity integer quantity of the current product being returned
return.items.display string Display name of the current product being returned
return.items.sku string optional internal SKU ID (e.g., your part number) for the current product being returned
return.items.subtotal number subtotal for the current product being returned, in return.currency
return.items.subtotalDisplay string subtotal for the current product being returned, formatted for display in return.currency
return.items.subtotalInPayoutCurrency number subtotal for the current product being returned, in the currency of your FastSpring disbursements
return.items.subtotalInPayoutCurrencyDisplay string subtotal for the current product being returned, formatted for display in the currency of your FastSpring disbursements
account object (expansion enabled only) details of the customer account (expansion enabled only)
account.id string FastSpring-generated customer account ID
account.account string FastSpring-generated customer account ID
account.contact object customer's contact details
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
account.contact.phone string customer's telephone number
account.language string two-character ISO code for the language associated with the customer's account
account.country string two-character ISO code for the country associated with the customer's account
account.lookup object multiple-field object containing lookup IDs for the customer account (e.g., for use with the /accounts endpoint of the FastSpring API)
account.lookup.global string external customer account ID, generated by FastSpring
account.lookup.custom string optional custom account ID specified via the /accounts endpoint of the FastSpring API (not shown in examples below)
account.url string URL for the Store's default account management page
subscriptions object (expansion enabled only) details of the subscription associated with the current product (if applicable; expansion enabled only)
subscriptions.id string ID of the subscription
subscriptions.subscription string ID of the subscription
subscriptions.active Boolean is the current subscription active? ("false" if deactivated)
subscriptions.state string current status of the subscription: "active", "overdue", "canceled", "deactivated", "trial"
subscriptions.changed integer date of the most recent change to the subscription, in milliseconds
subscriptions.changedValue integer date of the most recent change to the subscription, in milliseconds (backward compatibility)
subscriptions.changedInSeconds integer date of the most recent change to the subscription, in seconds
subscriptions.chagedDisplay string date of the most recent change to the subscription, formatted for display based on the language selected for the original subscription order
subscriptions.live Boolean "true" if not a test order
subscriptions.currency string three-character ISO code for the currency associated with the subscription
subscriptions.account string FastSpring-generated customer account ID
subscriptions.product string product path/product ID of the subscription product
subscriptions.sku string optional internal SKU ID (e.g., your part number) for the current product
subscriptions.display string customer-facing Display name of the subscription product
subscriptions.quantity integer subscribed quantity of the subscription product
subscriptions.adhoc Boolean "true" for managed subscriptions, "false" for standard subscriptions
subscriptions.autoRenew Boolean "true" for automatic subscriptions, "false" for manual renewal subscriptions
subscriptions.price number price of the subscription; the amount of each subscription charge, in subscriptions.currency
subscriptions.priceDisplay string price of subscription, formatted for display in subscriptions.currency
subscriptions.priceInPayoutCurrency number price of the subscription, in the currency of your FastSpring disbursements
subscriptions.priceInPayoutCurrencyDisplay string price of the subscription, formatted for display in the currency of your FastSpring disbursements
subscriptions.discount number total amount of all discounts associated with the subscription, in subscriptions.currency
subscriptions.discountDisplay string total amount of all discounts associated with the subscription, formatted for display in the subscriptions.currency
subscriptions.discountInPayoutCurrency number total amount of all discounts associated with the subscription, in the currency of your FastSpring disbursements
subscriptions.discountInPayoutCurrencyDisplay string total amount of all discounts associated with the subscription, formatted for display in the currency of your FastSpring disbursements
subscriptions.subtotal number subtotal for the subscription,including items.subscription.price and subscriptions.discount, but before tax
subscriptions.subtotalDisplay string subtotal for the subscription, formatted for display in subscriptions.currency
subscriptions.subtotalInPayoutCurrency number subtotal for the subscription, in the currency of your FastSpring disbursements
subscriptions.subtotalInPayoutCurrencyDisplay string subtotal for the subscription, formatted for display in the currency of your FastSpring disbursements
subscriptions.attributes object multiple-field object containing optional product-level attributes for the subscription (inherited from the subscription product)
subscriptions.next integer date of the next scheduled subscription charge, in milliseconds
subscriptions.nextValue integer date of the next scheduled subscription charge (backward compatibility)
subscriptions.nextInSeconds integer date of the next scheduled subscription charge, in seconds
subscriptions.nextDisplay string date of the next scheduled subscription charge, formatted for display based on the language selected for the original subscription order
subscriptions.end integer expected end date of the subscription (if any), in milliseconds (e.g., for subscriptions with a pre-defined number of charges)
subscriptions.endValue integer expected end date of the subscription (if any), in milliseconds (e.g., for subscriptions with a pre-defined number of charges) (backward compatibility)
subscriptions.endInSeconds integer expected end date of the subscription (if any), in seconds (e.g., for subscriptions with a pre-defined number of charges)
subscriptions.endDisplay string expected end date of the subscription (if any), formatted for display based on the language selected for the original subscription order
subscriptions.canceledDate integer date on which the subscription was canceled, in milliseconds, if applicable
subscriptions.canceledDateValue integer date on which the subscription was canceled, in milliseconds, if applicable (backward compatibility)
subscriptions.canceledDateInSeconds integer date on which the subscription was canceled, in seconds, if applicable
subscriptions.canceledDateDisplay string date on which the subscription was canceled, if applicable, formatted for display based on the language selected for the original subscription order
subscriptions.deactivationDate integer date on which the subscription was or will be deactivated, if applicable, in milliseconds (null if deactivated immediately upon cancellation)
subscriptions.deactivationDateValue integer date on which the subscription was or will be deactivated, if applicable, in milliseconds (null if deactivated immediately upon cancellation) (backward compatibility)
subscriptions.deactivationDateInSeconds integer date on which the subscription was or will be deactivated, if applicable, in seconds (null if deactivated immediately upon cancellation)
subscriptions.deactivationDateDisplay integer date on which the subscription was or will be deactivated, if applicable, formatted for display based on the language selected for the original subscription order (null if deactivated immediately upon cancellation)
subscriptions.sequence integer sequence number of the current billing period
subscriptions.periods integer expected total number of billing periods (e.g., for subscriptions with a pre-defined number of charges)
subscriptions.remainingPeriods integer number of periods remaining based on total number expected subscriptions.periods
subscriptions.begin integer date on which the subscription began, in milliseconds
subscriptions.beginValue integer date on which the subscription began, in milliseconds (backward compatibility)
subscriptions.beginInSeconds integer date on which the subscription began, in seconds
subscriptions.beginDisplay string date on which the subscription began, formatted for display based on the language selected for the original subscription order
subscriptions.intervalUnit string unit of time used in conjunction with subscriptions.intervalLength to determine the subscription's charge interval: "adhoc", "day", "week", "month", "year"
subscriptions.intervalLength integer number of intervalUnits per billing period for the subscription
subscriptions.nextChargeCurrency string three-character ISO code of the currency to be used for the next charge
subscriptions.nextChargeDate integer date of the next upcoming charge, in milliseconds
subscriptions.nextChargeDateValue integer date of the next upcoming charge, in milliseconds (backward compatibility)
subscriptions.nextChargeDateDisplay string date of the next upcoming charge, formatted for display based on the language selected for the original subscription order
subscriptions.nextChargeTotal number amount of the next upcoming charge, in the subscriptions.nextChargeCurrency
subscriptions.nextChargeTotalDisplay string amount of the next upcoming charge, formatted for display based on the subscriptions.nextChargeCurrency
subscriptions.nextChargeTotalInPayoutCurrency number amount of the next upcoming charge, in the currency of your FastSpring disbursements
subscriptions.nextChargeTotalInPayoutCurrencyDisplay string amount of the next upcoming charge, formatted for display in the currency of your FastSpring disbursements
subscriptions.nextNotificationType string type of next customer-facing email notification message: "TRIAL_REMINDER", "PAYMENT_REMINDER", "PAYMENT_OVERDUE"
subscriptions.nextNotificationDate integer date of the next customer-facing email notification message, in milliseconds
subscriptions.nextNotificationDateValue integer date of the next customer-facing email notification message, in milliseconds (backward compatibility)
subscriptions.nextNotificationDateInSeconds integer date of the next customer-facing email notification message, in seconds
subscriptions.nextNotificationDateDisplay string date of the next customer-facing email notification message, formatted for display based on the language of the original subscription order
subscriptions.trialReminder object defines the timing of the customer-facing reminder email message that will be sent (if any) regarding the approaching end of a free trial period
subscriptions.trialReminder.intervalUnit string unit of time used in conjunction with subscriptions.trialReminder.intervalLength to determine how long before the date of the first subscription charge the trial reminder message will be sent: "day", "week", "month", "year"
subscriptions.trialReminder.intervalLength integer number of subscriptions.trialReminder.intervalUnits before the date of the first subscription charge the trial reminder message will be sent
subscriptions.paymentReminder object defines the timing of the customer-facing reminder email message sent before each scheduled subscription billing
subscriptions.paymentReminder.intervalUnit string unit of time used in conjunction with subscriptions.paymentReminder.intervalLength to determine how long prior to the date of the first subscription charge the trial reminder message will be sent: "day", "week", "month", "year"
subscriptions.paymentReminder.intervalLength integer number of subscriptions.paymentReminder.intervalUnitsprior to each scheduled subscription billing that the pament reminder message will be sent
subscriptions.paymentOverdue object defines the timing of the customer-facing payment overdue notification message(s) sent when a scheduled billing has failed
subscriptions.paymentOverdue.intervalUnit string unit of time used in conjunction with subscriptions.paymentOverdue.intervalLength to determine how long after a failed subscription billing a payment overdue notification will be sent (or how long after a prior payment overdue notification message has been sent): "day", "week", "month", "year"
subscriptions.paymentOverdue.intervalLength integer number subscriptions.paymentOverdue.intervalUnits following the failed subscription billing that the first payment overdue notification will be sent – and number of subscriptions.paymentOverdue.intervalUnits between subsequent payment overdue notifications, if any
subscriptions.paymentOverdue.total integer total number of payment overdue notifications to be sent, including the first one
subscriptions.paymentOverdue.sent integer number of payment overdue notifications that have been sent to date
subscriptions.cancellationSetting object defines the timing of automatic subscription cancellation in the event of a failed subscription billing
subscriptions.cancellationSetting.cancellation string event trigger used in determining the timing of automatic subscription cancellation, as configured for the subscription product: "AFTER_LAST_NOTIFICATION" or "AFTER_PAYMENT_FAILURE"
subscriptions.cancellationSetting.intervalUnit string unit of time used in conjunction with subscriptions.cancellationSetting.intervalLength and subscriptions.cancellationSetting.cancellation to determine when a subscription will be canceled as a result of a failed subscription billing
subscriptions.cancellationSetting.intervalLength integer number of subscriptions.cancellationSetting.intervalUnits following the subscriptions.cancellationSetting.cancellation event trigger that the subscription will be canceled due to a failed subscription billing
subscriptions.discounts array information about the coupon applied to the subscription (if any)
subscriptions.discounts.totalDiscountValue number total amount of the discount that will be applied, based on subscriptions.discounts.discountValue multiplied by subscriptions.discounts.discountDuration (only present when the discount type is an amount rather than a percentage)
subscriptions.discounts.discountPath string coupon ID of the coupon applied to the subscription
subscriptions.discounts.discountDuration integer total number of billings, including the original order, to which the coupon discount will be applied
subscriptions.discounts.percentValue number percentage of the coupon discount applied to the subscription (only present when the discount type is a percentage rather than an amount)
subscriptions.discounts.discountValue number amount of the discount per billing period, in the subscriptions.currency (only present when the discount type is an amount rather than a percentage)
subscriptions.instructions array instructions for recurring billings
subscriptions.instructions.type string type of instructions for the current instruction object; 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)
subscriptions.instructions.periodStartDate integer date of the beginning of the instruction period, in milliseconds
subscriptions.instructions.periodStartDateValue integer date of the beginning of the instruction period, in milliseconds (backward compatibility)
subscriptions.instructions.periodStartDateInSeconds integer date of the beginning of the instruction period, in seconds
subscriptions.instructions.periodStartDateDisplay string date of the beginning of the instruction period, formatted for display based on the language selected for the original subscription order
subscriptions.instructions.periodEndDate integer date of the end of the instruction period, in milliseconds
subscriptions.instructions.periodEndDateValue integer date of the end of the instruction period, in milliseconds (backward compatibility)
subscriptions.instructions.periodEndDateInSeconds integer date of the end of the instruction period, in seconds
subscriptions.instructions.periodEndDateDisplay string date of the end of the instruction period, formatted for display based on the language selected for the original subscription order
subscriptions.instructions.discountDurationUnit string only appears when subscriptions.instructions.type = "discounted" or "trial"; unit of time used in conjunction with subscriptions.instructions.discountDurationLength to determine the total discount duration: "day", "week", "month", or "year"
subscriptions.instructions.discountDurationLength integer only appears when subscriptions.instructions.type = "discounted" or "trial"; number of subscriptions.instructions.discountDurationUnits in the total discount period
subscriptions.instructions.discountPercent integer percentage of the discount for the current instruction period
subscriptions.instructions.discountPercentValue integer percentage of the discount for the current instruction period (backward compatibility)
subscriptions.instructions.discountPercentDisplay string percentage of the discount for the current instruction period, formatted for display
subscriptions.instructions.unitDiscount number discount amount per unit for the current instruction period, in the subscriptions.currency
subscriptions.instructions.unitDiscountDisplay string discount amount per unit for the current instruction period, formatted for display in the subscriptions.currency
subscriptions.instructions.unitDiscountInPayoutCurrency number discount amount per unit for the current instruction period, in the currency of your FastSpring disbursements
subscriptions.instructions.unitDiscountInPayoutCurrencyDisplay string discount amount per unit for the current instruction period, formatted for display in the currency of your FastSpring disbursements
subscriptions.instructions.discountTotal number total amount of the discount for the current instruction period, in the subscriptions.currency
subscriptions.instructions.discountTotalDisplay string total amount of the discount for the current instruction period, formatted for display based on the subscriptions.currency
subscriptions.instructions.discountTotalInPayoutCurrency number total amount of the discount for the current instruction period, in the currency of your FastSpring disbursements
subscriptions.instructions.discountTotalInPayoutCurrencyDisplay string total amount of the discount for the current instruction period, formatted for display in the currency of your FastSpring disbursements
subscriptions.instructions.price number list price of the product before any discounts, in the subscriptions.currency
subscriptions.instructions.priceDisplay string list price of the product before any discounts, formatted for display in the subscriptions.currency
subscriptions.instructions.priceInPayoutCurrency number list price of the product before any discounts, in the currency of your FastSpring disbursements
subscriptions.instructions.priceInPayoutCurrencyDisplay string list price of the product before any discounts, formatted for display in the currency of your FastSpring disbursements
subscriptions.instructions.priceTotal number product of (subscriptions.instructions.price * subscriptions.quantity), in the subscriptions.currency, for the current instruction period
subscriptions.instructions.priceTotalDisplay string product of (subscriptions.instructions.price * subscriptions.quantity), formatted for display in the subscriptions.currency, for the current instruction period
subscriptions.instructions.priceTotalInPayoutCurrency number product of (subscriptions.instructions.price * subscriptions.quantity), in the currency of your FastSpring disbursements, for the current instruction period
subscriptions.instructions.priceTotalInPayoutCurrencyDisplay string product of (subscriptions.instructions.price * subscriptions.quantity), formatted for display in the currency of your FastSpring disbursements, for the current instruction period
subscriptions.instructions.unitPrice number effective unit price after any discount, for the current instruction period, in the subscriptions.currency
subscriptions.instructions.unitPriceDisplay string effective unit price after any discount, for the current instruction period, formatted for display in the subscriptions.currency
subscriptions.instructions.unitPriceInPayoutCurrency number effective unit price after any discount, for the current instruction period, in the currency of your FastSpring disbursements
subscriptions.instructions.unitPriceInPayoutCurrencyDisplay string effective unit price after any discount, for the current instruction period, formatted for display in the currency of your FastSpring disbursements
subscriptions.instructions.total number product of (subscriptions.instructions.unitPrice * subscriptions.quantity) for the current instruction period, in the subscriptions.currency
subscriptions.instructions.totalDisplay string product of (subscriptions.instructions.unitPrice * subscriptions.quantity) for the current instruction period, formatted for display in the subscriptions.currency
subscriptions.instructions.totalInPayoutCurrency number product of (subscriptions.instructions.unitPrice * subscriptions.quantity) for the current instruction period, in the currency of your FastSpring disbursements
subscriptions.instructions.totalInPayoutCurrencyDisplay string product of (subscriptions.instructions.unitPrice * subscriptions.quantity) for the current instruction period, formatted for display in the currency of your FastSpring disbursements
subscriptions.customReferenceID string an optional value that you can add to a subscription instance via the FastSpring API using POST /subscriptions
subtractions object details of deductions from the total amount that will be disbursed to you for this transaction
subtractions.tax object details of the tax amounts associated with this transaction
subtractions.tax.currency string three-character ISO code of the currency in which subtractions.tax.amount is rendered
subtractions.tax.amount number amount of tax rendered for this transaction
subtractions.tax.percentage integer tax percentage applied to this transaction
subtractions.fastspring object details of the FastSpring processing fee associated with this transaction
subtractions.fastspring.currency string three-character ISO code of the currency in which subtractions.fastspring.amount is rendered
subtractions.fastspring.amount number amount of the FastSpring processing fee associated with this transaction
subtractions.fastspring.percentage integer percentage of the FastSpring processing fee associated with this transaction
payouts array details of the amount to be disbursed to you for this transaction
payouts.payee string name of the recipient of the disbursement for this transaction
payouts.currency string three-character ISO code of the currency in which payouts.payout is rendered
payouts.payout number the amount of the payout to be paid to the current payouts.payee, in the payouts.currency.
payouts.subtotal number the amount of all payouts (will be the same for each payouts.payee)
payouts.total number the total amount of the order (including subtractions)

 

Examples

Example 1 – Triggered by an Order, Webhook Expansion Enabled

payoutEntry.created webhook example (webhook expansion enabled)
{
  "orderId": "bVMeceKDSHCwtMtLTUPh0g",
  "reference": "YOUREXAMPLESTOR191212-7788-69112B",
  "live": false,
  "order": {
    "order": "bVMeceKDSHCwtMtLTUPh0g",
    "id": "bVMeceKDSHCwtMtLTUPh0g",
    "reference": "YOUREXAMPLESTOR191212-7788-69112B",
    "buyerReference": null,
    "completed": true,
    "changed": 1576186812232,
    "changedValue": 1576186812232,
    "changedInSeconds": 1576186812,
    "changedDisplay": "12/12/19",
    "language": "en",
    "live": false,
    "currency": "USD",
    "payoutCurrency": "USD",
    "invoiceUrl": "https://yourexamplestore.test.onfastspring.com/account/order/YOUREXAMPLESTOR191212-7788-69112B/invoice"",
    "account": "gB_slATyQBqSpAxA7-1YAg",
    "total": 22.5,
    "totalDisplay": "$22.50",
    "totalInPayoutCurrency": 22.5,
    "totalInPayoutCurrencyDisplay": "$22.50",
    "tax": 0,
    "taxDisplay": "$0.00",
    "taxInPayoutCurrency": 0,
    "taxInPayoutCurrencyDisplay": "$0.00",
    "subtotal": 22.5,
    "subtotalDisplay": "$22.50",
    "subtotalInPayoutCurrency": 22.5,
    "subtotalInPayoutCurrencyDisplay": "$22.50",
    "discount": 7.5,
    "discountDisplay": "$7.50",
    "discountInPayoutCurrency": 7.5,
    "discountInPayoutCurrencyDisplay": "$7.50",
    "discountWithTax": 10.12,
    "discountWithTaxDisplay": "$10.12",
    "discountWithTaxInPayoutCurrency": 10.12,
    "discountWithTaxInPayoutCurrencyDisplay": "$10.12",
    "billDescriptor": "FS* fsprg.com",
    "payment": {
      "type": "test"
    },
    "customer": {
      "first": "John",
      "last": "Doe",
      "email": "ne1@all.com",
      "company": null,
      "phone": null
    },
    "address": {
      "city": "Santa Barbara",
      "regionCode": "CA",
      "regionDisplay": "California",
      "region": "California",
      "postalCode": "93101",
      "country": "US",
      "display": "Santa Barbara, California, 93101, US"
    },
    "recipients": [
      {
        "recipient": {
          "first": "John",
          "last": "Doe",
          "email": "ne1@all.com",
          "company": null,
          "phone": null,
          "account": "gB_slATyQBqSpAxA7-1YAg",
          "address": {
            "city": "Santa Barbara",
            "regionCode": "CA",
            "regionDisplay": "California",
            "region": "California",
            "postalCode": "93101",
            "country": "US",
            "display": "Santa Barbara, California, 93101, US"
          }
        }
      }
    ],
    "notes": [],
    "items": [
      {
        "product": "example-subscription-monthly",
        "quantity": 1,
        "display": "Example Subscription - Monthly",
        "sku": null,
        "subtotal": 22.5,
        "subtotalDisplay": "$22.50",
        "subtotalInPayoutCurrency": 22.5,
        "subtotalInPayoutCurrencyDisplay": "$22.50",
        "discount": 7.5,
        "discountDisplay": "$7.50",
        "discountInPayoutCurrency": 7.5,
        "discountInPayoutCurrencyDisplay": "$7.50",
        "subscription": "nCEk1Iq_RJKcR1XCR2xpSw",
        "coupon": "LIMITED",
        "fulfillments": {}
      }
    ],
    "coupons": [
      "LIMITED"
    ]
  },
  "account": {
    "id": "gB_slATyQBqSpAxA7-1YAg",
    "account": "gB_slATyQBqSpAxA7-1YAg",
    "contact": {
      "first": "John",
      "last": "Doe",
      "email": "ne1@all.com",
      "company": null,
      "phone": null
    },
    "language": "en",
    "country": "US",
    "lookup": {
      "global": "VKMqlZ--TIuD44BvXdNkbg"
    },
    "url": "https://yourexamplestore.test.onfastspring.com/account""
  },
  "subscriptions": [
    {
      "id": "nCEk1Iq_RJKcR1XCR2xpSw",
      "subscription": "nCEk1Iq_RJKcR1XCR2xpSw",
      "active": true,
      "state": "active",
      "changed": 1576186587354,
      "changedValue": 1576186587354,
      "changedInSeconds": 1576186587,
      "changedDisplay": "12/12/19",
      "live": false,
      "currency": "USD",
      "account": "gB_slATyQBqSpAxA7-1YAg",
      "product": "example-subscription-monthly",
      "sku": null,
      "display": "Example Subscription - Monthly",
      "quantity": 1,
      "adhoc": false,
      "autoRenew": true,
      "price": 30,
      "priceDisplay": "$30.00",
      "priceInPayoutCurrency": 30,
      "priceInPayoutCurrencyDisplay": "$30.00",
      "discount": 0,
      "discountDisplay": "$0.00",
      "discountInPayoutCurrency": 0,
      "discountInPayoutCurrencyDisplay": "$0.00",
      "subtotal": 30,
      "subtotalDisplay": "$30.00",
      "subtotalInPayoutCurrency": 30,
      "subtotalInPayoutCurrencyDisplay": "$30.00",
      "discountDuration": 0,
      "next": 1583971200000,
      "nextValue": 1583971200000,
      "nextInSeconds": 1583971200,
      "nextDisplay": "3/12/20",
      "end": null,
      "endValue": null,
      "endInSeconds": null,
      "endDisplay": null,
      "canceledDate": null,
      "canceledDateValue": null,
      "canceledDateInSeconds": null,
      "canceledDateDisplay": null,
      "deactivationDate": null,
      "deactivationDateValue": null,
      "deactivationDateInSeconds": null,
      "deactivationDateDisplay": null,
      "sequence": 3,
      "periods": null,
      "remainingPeriods": null,
      "begin": 1576108800000,
      "beginValue": 1576108800000,
      "beginInSeconds": 1576108800,
      "beginDisplay": "12/12/19",
      "intervalUnit": "month",
      "intervalLength": 1,
      "nextChargeCurrency": "USD",
      "nextChargeDate": 1583971200000,
      "nextChargeDateValue": 1583971200000,
      "nextChargeDateInSeconds": 1583971200,
      "nextChargeDateDisplay": "3/12/20",
      "nextChargePreTax": 30,
      "nextChargePreTaxDisplay": "$30.00",
      "nextChargePreTaxInPayoutCurrency": 30,
      "nextChargePreTaxInPayoutCurrencyDisplay": "$30.00",
      "nextChargeTotal": 30,
      "nextChargeTotalDisplay": "$30.00",
      "nextChargeTotalInPayoutCurrency": 30,
      "nextChargeTotalInPayoutCurrencyDisplay": "$30.00",
      "nextNotificationType": "PAYMENT_REMINDER",
      "nextNotificationDate": 1583366400000,
      "nextNotificationDateValue": 1583366400000,
      "nextNotificationDateInSeconds": 1583366400,
      "nextNotificationDateDisplay": "3/5/20",
      "paymentReminder": {
        "intervalUnit": "week",
        "intervalLength": 1
      },
      "paymentOverdue": {
        "intervalUnit": "week",
        "intervalLength": 1,
        "total": 4,
        "sent": 0
      },
      "cancellationSetting": {
        "cancellation": "AFTER_LAST_NOTIFICATION",
        "intervalUnit": "week",
        "intervalLength": 1
      },
      "instructions": [
        {
          "product": "example-subscription-monthly",
          "type": "regular",
          "periodStartDate": null,
          "periodStartDateValue": null,
          "periodStartDateInSeconds": null,
          "periodStartDateDisplay": null,
          "periodEndDate": null,
          "periodEndDateValue": null,
          "periodEndDateInSeconds": null,
          "periodEndDateDisplay": 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": 30,
          "priceDisplay": "$30.00",
          "priceInPayoutCurrency": 30,
          "priceInPayoutCurrencyDisplay": "$30.00",
          "priceTotal": 30,
          "priceTotalDisplay": "$30.00",
          "priceTotalInPayoutCurrency": 30,
          "priceTotalInPayoutCurrencyDisplay": "$30.00",
          "unitPrice": 30,
          "unitPriceDisplay": "$30.00",
          "unitPriceInPayoutCurrency": 30,
          "unitPriceInPayoutCurrencyDisplay": "$30.00",
          "total": 30,
          "totalDisplay": "$30.00",
          "totalInPayoutCurrency": 30,
          "totalInPayoutCurrencyDisplay": "$30.00"
        }
      ]
    }
  ],
  "subtractions": {
    "tax": {
      "currency": "USD",
      "amount": 0,
      "percentage": 0
    },
    "fastspring": {
      "currency": "USD",
      "amount": 2.2775,
      "percentage": 10.12
    }
  },
  "payouts": [
    {
      "payee": "yourexamplestore",
      "currency": "USD",
      "payout": "20.22",
      "subtotal": 20.22,
      "total": "22.50"
    }
  ]
}

 

Example 2 – Triggered by a Return, Webhook Expansion Disabled

payoutEntry.created webhook example (webhook expansion disabled)
{
  "return": "xrWuQKxURT2PnrSvHt8HnQ",
  "account": "gB_slATyQBqSpAxA7-1YAg",
  "live": false,
  "subscriptions": [
    "nCEk1Iq_RJKcR1XCR2xpSw"
  ],
  "subtractions": {
    "tax": {
      "amount": 0,
      "percentage": 0
    },
    "fastspring": {
      "amount": 0,
      "percentage": 0
    }
  },
  "subtotal": -22.5,
  "payouts": [
    {
      "payee": "yourexamplestore",
      "currency": "USD",
      "payout": "-22.50",
      "totalReturn": "-22.50"
    }
  ]
}

This article provides information about the /returns endpoint of the FastSpring API. For more information about the API itself, please see About the FastSpring API.

Using this endpoint, you can retrieve return details or create full order returns. For more information about returns, please see Refunding Orders.

 

Get One or More Returns

GET /returns/{id1}[,{id2},{id3},...]

   

Get returns by id response
{
	"returns": [
	{
		"return": "QpMoe70PT5mMb5OMT4N5lA",                             // return ID
		"reference": "SUD160811-6921-74128X",                           // customer-facing return refernce (not the original order reference)
		"completed": true,                                              // false if return is pending
		"changed": 1470953997043,                                       // date of the last update to this return record, in milliseconds
		"changedValue": 1470953997043,
		"changedInSeconds": 1470953997,                                 // date of the last update to this return record, in seconds
		"changedDisplay": "8/11/16",                                    // date of the last update to this return record, formatted for display based on the language in which the order was processed, as selected by the customer
		"live": false,                                                  // true if not a test order
		"account": "_sOMzG2pSIyAeWXkcoNgUA",                            // FastSpring-generated customer account ID
		"currency": "USD",
		"payoutCurrency": "USD",
		"totalReturn": 10.0,
		"totalReturnDisplay": "$10.00",
		"totalReturnInPayoutCurrency": 10.0,
		"totalReturnInPayoutCurrencyDisplay": "$10.00",
		"tax": 0.0,
		"taxDisplay": "$0.00",
		"taxInPayoutCurrency": 0.0,
		"taxInPayoutCurrencyDisplay": "$0.00",
		"subtotal": 10.0,
		"subtotalDisplay": "$10.00",
		"subtotalInPayoutCurrency": 10.0,
		"subtotalInPayoutCurrencyDisplay": "$10.00",
		"totalRefundInPayoutCurrency": 10.0,
		"payment": {
			"type": "test",
			"cardEnding": "4242"
		},
		"reason": "Product Not Received",                                // return reason selected by publisher / seller when processing the refund
		"note": "Note during the refund of the order(Canceling The Subscription)",     // optional return comment entered by publisher / seller when processing the refund
                "type": "RETURN",                                                // return type: CHARGEBACK, PAYMENTRISK, PAYPAL, RETURN
		"original": {
			"id": "embMdXyCQZinGxkk2v85GA", 
			"order": "embMdXyCQZinGxkk2v85GA",                           // internal ID of the original order
			"reference": "SUD160811-1752-43151",                         // customer-facing reference for the original order
			"account": "_sOMzG2pSIyAeWXkcoNgUA",                         // FastSpring-generated customer account ID of the original order
			"currency": "USD",
			"payoutCurrency": "USD",
			"total": 10.0,
			"totalDisplay": "$10.00",
			"totalInPayoutCurrency": 10.0,
			"totalInPayoutCurrencyDisplay": "$10.00",
			"tax": 0.0,
			"taxDisplay": "$0.00",
			"taxInPayoutCurrency": 0.0,
			"taxInPayoutCurrencyDisplay": "$0.00",
			"subtotal": 10.0,
			"subtotalDisplay": "$10.00",
			"subtotalInPayoutCurrency": 10.0,
			"subtotalInPayoutCurrencyDisplay": "$10.00",
			"notes": [
			    {
				"note": "Before canceling the subscription",             // example note entered by the publisher / seller on the original order record (not the refund)
				"creator": "admin@yourexamplestore.com"                     // user ID of the seller's agent who entered the note
			    }
			],
			"subscriptions": 
			[
			"RPN1Bp62Q3mEXloZvxUxmg"                                     // ID of the subscription associated with the returned order (if any)
			]
		},
		"customer": {
			"first": "Test",
			"last": "Order",
			"email": "test@tes.com",
			"company": "Test",
			"phone": "1234567890"
		},
		"items": [
		    {
			"product": "newtestsuborder",
			"quantity": 1,
			"display": "newtestsuborder",
			"sku": null,
			"subtotal": 10.0,
			"subtotalDisplay": "$10.00",
			"subtotalInPayoutCurrency": 10.0,
			"subtotalInPayoutCurrencyDisplay": "$10.00",
			"subscription": "RPN1Bp62Q3mEXloZvxUxmg"                     // ID of the subscription associated with the returned order (if any)
		     }
		],
		"action": "return.get",
		"result": "success"
	}
  ]
}

 

POST one or more full order returns

POST /returns

 Note

At this time, it is not possible to perform partial refunds or return specific line items via the API. However, you can still do this via the FastSpring App. For help with these types of returns, please see Refunding Orders.

 Note

Processing a full return via the API for an order associated with a subscription does not automatically cancel the subscription. You can cancel the subscription by calling DELETE /subscriptions/{subscriptionId}.
Sample Request
{ 
  "returns":[ 
    { 
      "order":"17VblT1XR1aAnIIScCgpfw",                     // order ID OR order reference to be returned
      "reason":"DUPLICATE_ORDER",                           // PRODUCT_NOT_RECEIVED | PRODUCT_DIFFERENCE | FRAUD | ORDER_ERROR | DISCOUNT | DUPLICATE_ORDER | COMPATIBILITY_ISSUE | OTHER (NONE if missing)
      "note":"As requested by customer",                    // optional, customer-visible note explaining the return reason
      "notification":"ORIGINAL"                             // notify the customer of the return via email? "ORIGINAL" = yes; "NONE" = no
    }
  ]
}
Sample Response
{
    "returns": [
        {
            "return": "JV8jCQrJT1GD7yndYgrorw",
            "reference": "FUR191003-4739-52106X",
            "completed": true,
            "changed": 1570130905372,
            "changedValue": 1570130905372,
            "changedInSeconds": 1570130905,
            "changedDisplay": "10/3/19",
            "live": true,
            "account": "2-hl9JWwQrualioCsY5lbg",
            "currency": "USD",
            "payoutCurrency": "USD",
            "totalReturn": 5.31,
            "totalReturnDisplay": "$5.31",
            "totalReturnInPayoutCurrency": 5.31,
            "totalReturnInPayoutCurrencyDisplay": "$5.31",
            "tax": 0.36,
            "taxDisplay": "$0.36",
            "taxInPayoutCurrency": 0.36,
            "taxInPayoutCurrencyDisplay": "$0.36",
            "subtotal": 4.95,
            "subtotalDisplay": "$4.95",
            "subtotalInPayoutCurrency": 4.95,
            "subtotalInPayoutCurrencyDisplay": "$4.95",
            "totalRefundInPayoutCurrency": 5.31,
            "payment": {
                "type": "creditcard",
                "creditcard": "visa",
                "cardEnding": "0369"
            },
            "reason": "DUPLICATE_ORDER",
            "note": "As requested by customer",
            "original": {
                "id": "kfPW5xbyTG-TuivKhtZYrA",
                "order": "kfPW5xbyTG-TuivKhtZYrA",
                "reference": "FUR191003-8210-23117",
                "account": "2-hl9JWwQrualioCsY5lbg",
                "currency": "USD",
                "payoutCurrency": "USD",
                "total": 5.31,
                "totalDisplay": "$5.31",
                "totalInPayoutCurrency": 5.31,
                "totalInPayoutCurrencyDisplay": "$5.31",
                "tax": 0.36,
                "taxDisplay": "$0.36",
                "taxInPayoutCurrency": 0.36,
                "taxInPayoutCurrencyDisplay": "$0.36",
                "subtotal": 4.95,
                "subtotalDisplay": "$4.95",
                "subtotalInPayoutCurrency": 4.95,
                "subtotalInPayoutCurrencyDisplay": "$4.95",
                "notes": []
            },
            "customer": {
                "first": "Leeroy",
                "last": "Jenkins",
                "email": "ne1@all.com",
                "company": null,
                "phone": null
            },
            "items": [
                {
                    "product": "eggs",
                    "quantity": 1,
                    "display": "Eggs",
                    "sku": "falcon1",
                    "subtotal": 4.95,
                    "subtotalDisplay": "$4.95",
                    "subtotalInPayoutCurrency": 4.95,
                    "subtotalInPayoutCurrencyDisplay": "$4.95",
                    "attributes": {
                        "conditions": "{exclude:{countries:['AT','GB']}}"
                    }
                }
            ],
            "action": "return.create",
            "result": "success"
        }
    ]
}

The subscription.updated server webhook event fires when you have edited a subscription instance (e.g., by modifying the subscription instance's product or next payment date) via the FastSpring App or the /subscriptions endpoint of the FastSpring API).

About Webhook Expansion:
When webhook expansion is enabled, subscription.updated includes the complete account object and the complete product object, rather than just the account ID and the product ID.
Each post from FastSpring to your endpoint may contain more than one webhook event in its payload. For more information, please see About Webhooks.

 

Contents of Event Payload

Name Type Description
id string ID of the subscription
quote string internal ID quote associated with the original order
subscription string ID of the subscription (backward compatibility)
active Boolean is the current subscription active? ("false" if deactivated)
state string current status of the subscription: "active", "overdue", "canceled", "deactivated", "trial"
changed integer date of the most recent change to the subscription, in milliseconds
changedValue integer date of the most recent change to the subscription, in milliseconds (backward compatibility)
changedInSeconds integer date of the most recent change to the subscription, in seconds
changedDisplay string date of the most recent change to the subscription, formatted display based on the language of the original subscription order
live Boolean "true" if not a test order
currency string three-character ISO code for the currency associated with the subscription
account string (expansion disabled)
object (expansion enabled)
FastSpring-generated customer account ID (expansion disabled)
details of the customer account (expansion enabled)
account.id string FastSpring-generated customer account ID
account.account string FastSpring-generated customer account ID
account.contact object customer's contact details
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
account.contact.phone string customer's telephone number
account.language string two-character ISO code for the language associated with the customer's account
account.country string two-character ISO code for the country associated with the customer's account
account.lookup object multiple-field object containing lookup IDs for the customer account (e.g., for use with the /accounts endpoint of the FastSpring API)
account.lookup.global string external customer account ID, generated by FastSpring
account.lookup.custom string optional custom account ID specified via the /accounts endpoint of the FastSpring API (not shown in examples below)
account.url string URL for the Store's default account management page
product string (expansion disabled)
object (expansion enabled)
product path/product ID of the subscription product (expansion disabled)
details about the product associated with the subscription
product.product string product ID/product path
product.parent string if the product is a product variation, this field indicates the product ID/product path of the parent product; otherwise, this will have a null value
product.display object customer-facing Display name; may contain multiple strings, one for each localized language with format "ISO language code":"string"
product.description object contents of the product's Summary, Long Description, and Call to Action fields
product.description.summary object contents of the product's Summary field; may contain multiple strings, one for each localized language with format "ISO language code":"string"
product.description.action object contents of the product's Call to Action field; may contain multiple strings, one for each localized language with format "ISO language code":"string"
product.description.full object contents of the product's Long Description field; may contain multiple strings, one for each localized language with format "ISO language code":"string"
product.image string URL for the FastSpring-hosted product icon image file
product.sku string optional internal SKU ID (e.g., your part number) for the current product
product.fulfillments object details of the product's fulfillment actions
product.fulfillments.instructions object contents of the product's Post-Order Instructions field; may contain multiple strings, one for each localized language with format "ISO language code":"string"
product.fulfillments.<fulfillment action name> object details of each fulfillment action assigned to the product; this object is repeated once for each fulfillment action
product.fulfillments.<fulfillment action name>.fulfillment string name of the current fulfillment action
product.fulfillments.<fulfillment action name>.name string description of the current fulfillment action type (includes file name for file downloads)
product.fulfillments.<fulfillment action name>.applicability string setting from the current fulfillment action's Fulfillment Applicability field: "ALWAYS", "BASE", "REBILL ONLY", "CONFIGURATION", or "NON_REBILL_ONLY"
product.fulfillments.<fulfillment action name>.display string when the current fulfillment action is a remote URL download, displays the download's Name
product.fulfillments.<fulfillment action name>.url string when the current fulfillment action is a remote URL download, displays the URL from which the file is to be downloaded
product.fulfillments.<fulfillment action name>.size number when the current fulfillment action is a remote URL download, displays the size of the download file, in bytes
product.fulfillments.<fulfillment action name>.behavior string when the current fulfillment action is a download, indicates the setting of the current fulfillment action's Download Version Behavior field: "PREFER_EXPLICIT" or "CURRENT"
product.fulfillments.<fulfillment action name>.previous array when the current fulfillment action is a download, and you have updated the download file from the original version, provides details of the previous version
product.fulfillments.<fulfillment action name>.previous.display string filename of the previous version file for this download fulfillment
product.fulfillments.<fulfillment action name>.previous.size integer size of the previous version file for this download fulfillment
product.fulfillments.<fulfillment action name>.previous.type string type of the previous version file for this download fulfillment (e.g. "application/octet-stream")
product.fulfillments.<fulfillment action name>.previous.modified integer last modified date of the previous version file for this download fulfillment, in milliseconds
product.format string product format: "digital", "physical" or "digital-and-physical"
product.attributes object optional product-level attributes; may contain multiple strings consisting of "key":"value" pairs
product.pricing object product pricing details
product.pricing.trial integer if Free Trial Days are configured, specifies the number of days
product.pricing.renew string disregard this field – manual renewal subscriptions are currently controlled in Storefront Settings
product.pricing.interval string frequency of subscription billings: "day", "month",
product.pricing.intervalLength integer number of product.pricing.intervals between scheduled billings
product.pricing.intervalCount integer indicates the total number of expected billing periods
product.pricing.quantityBehavior string indicates the behavior of the quantity field for the product: "allow", "lock", or "hide"
product.pricing.quantityDefault integer default quantity for the product
product.pricing.price object product price; may contain multiple "string":number pairings, one for each specified currency (e.g. "USD":14.95)
product.pricing.quantityDiscounts object when Use Volume Discounts is selected, indicates the quantity thresholds and corresponding discount amounts or percentages (e.g. "2":10.0, "5":15.0 or "2":{"EUR":1.75,"USD":2.0}, "5":{"EUR":2.25,"USD":3.0})
when Use Volume Discounts is not selected, indicates the amount or percentage of the product-level discount (e.g., "1":{"USD":3.75})
product.pricing.dateLimitsEnabled Boolean indicate whether or not beginning and end dates have been specified for product-level discounts
product.pricing.dateLimits object when product.pricing.dateLimitsEnabled is true, indicates the beginning and or ending date and time for the discount to be applied on an initial transaction
product.pricing.dateLimits.start string beginning date and time when the discount will be applied
product.pricing.dateLimits.end string ending date and time, after which the discount will no longer be applied
product.pricing.discountReason object optional, customer-facing explanation of the product-level discount; may contain multiple strings, one for each localized language with format "ISO language code":"string"
product.pricing.discountDuration integer when a product-level discount is configured, indicates the number of subscription billings (including the initial transaction) to which the discount will be applied
product.pricing.reminderNotification object details of any payment reminder notification email messages configured for the subscription product
product.pricing.reminderNotification.enabled Boolean indicates whether or not payment reminders are enabled for the subscription product
product.pricing.reminderNotification.interval string interval unit that controls the frequency of payment reminder notification email messages: "DAY", "WEEK", "MONTH", or "YEAR"
product.pricing.reminderNotification.intervalLength integer number of product.pricing.reminderNotification.intervals before the scheduled billing date that FastSpring will send the reminder notification email message
product.pricing.overdueNotification object details of any payment overdue notification email messages configured for the subscription product; these are messages sent when a subscription billing has failed or been declined
product.pricing.overdueNotification.enabled Boolean indicates whether or not payment overdue notification messages are enabled for the subscription product
product.pricing.overdueNotification.interval string interval unit that controls the frequency of payment overdue notification email messages: "DAY", "WEEK", "MONTH", or "YEAR"
product.pricing.overdueNotification.intervalLength integer number of product.pricing.overdueNotification.intervals following a declined subscription billing that FastSpring will send the first payment overdue notification message, and the number of intervals between subsequent notification messages
product.pricing.overdueNotification.amount integer total number of payment overdue notification messages that FastSpring will send
product.pricing.cancellation object cancellation settings to be used in the event of a failed subscription billing
product.pricing.cancellation.interval string interval unit that controls when the subscription will automatically be canceled in the event of a failed billing: "DAY", "WEEK", "MONTH", "YEAR"
product.pricing.cancellation.intervalLength integer number of product.pricing.cancellation.intervals following a declined subscription billing – OR following the last payment overdue notification, if product.pricing.overdueNotification.enabled is true – after which the subscription will be canceled automatically
sku string optional internal SKU ID (e.g., your part number) for the current product
display string customer-facing Display name of the subscription product
quantity integer subscribed quantity of the subscription product
adhoc Boolean "true" for managed subscriptions, "false" for standard subscriptions
autoRenew Boolean "true" for automatic subscriptions, "false" for manual renewal subscriptions
price number price of the subscription; the amount of each subscription charge, in currency
priceDisplay string price of subscription, formatted for display in currency
priceInPayoutCurrency number price of the subscription, in the currency of your FastSpring disbursements
priceInPayoutCurrencyDisplay string price of the subscription, formatted for display in the currency of your FastSpring disbursements
discount number total amount of all discounts associated with the subscription, in currency
discountDisplay string total amount of all discounts associated with the subscription, formatted for display in the currency
discountInPayoutCurrency number total amount of all discounts associated with the subscription, in the currency of your FastSpring disbursements
discountInPayoutCurrencyDisplay string total amount of all discounts associated with the subscription, formatted for display in the currency of your FastSpring disbursements
subtotal number subtotal for the subscription, including price and discount, but before tax
subtotalDisplay string subtotal for the subscription, formatted for display in currency
subtotalInPayoutCurrency number subtotal for the subscription, in the currency of your FastSpring disbursements
subtotalInPayoutCurrencyDisplay string subtotal for the subscription, formatted for display in the currency of your FastSpring disbursements
attributes object multiple-field object containing optional product-level attributes for the subscription (inherited from the subscription product)
tags object multiple-field object containing optional order-level tags for the subscription (inherited from the original transaction)
next integer date of the next scheduled subscription charge, in milliseconds
nextValue integer date of the next scheduled subscription charge (backward compatibility)
nextInSeconds integer date of the next scheduled subscription charge, in seconds
nextDisplay string date of the next scheduled subscription charge, formatted for display based on the language selected for the original subscription order
end integer expected end date of the subscription (if any), in milliseconds (e.g., for subscriptions with a pre-defined number of charges)
endValue integer expected end date of the subscription (if any), in milliseconds (e.g., for subscriptions with a pre-defined number of charges) (backward compatibility)
endInSeconds integer expected end date of the subscription (if any), in seconds (e.g., for subscriptions with a pre-defined number of charges)
endDisplay string expected end date of the subscription (if any), formatted for display based on the language selected for the original subscription order
canceledDate integer date on which the subscription was canceled, in milliseconds, if applicable
canceledDateValue integer date on which the subscription was canceled, in milliseconds, if applicable (backward compatibility)
canceledDateInSeconds integer date on which the subscription was canceled, in seconds, if applicable
canceledDateDisplay string date on which the subscription was canceled, if applicable, formatted for display based on the language selected for the original subscription order
deactivationDate integer date on which the subscription was or will be deactivated, if applicable, in milliseconds (null if deactivated immediately upon cancellation)
deactivationDateValue integer date on which the subscription was or will be deactivated, if applicable, in milliseconds (null if deactivated immediately upon cancellation) (backward compatibility)
deactivationDateInSeconds integer date on which the subscription was or will be deactivated, if applicable, in seconds (null if deactivated immediately upon cancellation)
deactivationDateDisplay integer date on which the subscription was or will be deactivated, if applicable, formatted for display based on the language selected for the original subscription order (null if deactivated immediately upon cancellation)
sequence integer sequence number of the current billing period
periods integer expected total number of billing periods (e.g., for subscriptions with a pre-defined number of charges)
remainingPeriods integer number of periods remaining based on total number expected periods
begin integer date on which the subscription began, in milliseconds
beginValue integer date on which the subscription began, in milliseconds (backward compatibility)
beginInSeconds integer date on which the subscription began, in seconds
beginDisplay string date on which the subscription began, formatted for display based on the language selected for the original subscription order
intervalUnit string unit of time used in conjunction with intervalLength to determine the subscription's charge interval: "adhoc", "day", "week", "month", "year"
intervalLength integer number of intervalUnits per billing period for the subscription
intervalCount integer only appears when the subscription product is scheduled to end or renew into a different product following a fixed number of periods; indicates the total number of expected billing periods
nextChargeCurrency string three-character ISO code of the currency to be used for the next charge
nextChargeDate integer date of the next upcoming charge, in milliseconds
nextChargeDateValue integer date of the next upcoming charge, in milliseconds (backward compatibility)
nextChargeDateInSeconds integer date of the next upcoming charge, in seconds
nextChargeDateDisplay string date of the next upcoming charge, formatted for display based on the language selected for the original subscription order
nextChargePreTax integer amount of the next upcoming charge without taxes
nextChargePreTaxDisplay string amount of the next upcoming charge without taxes, formatted for display based on the nextChargeCurrency
nextChargePreTaxInPayoutCurrency integer amount of the next upcoming charge without taxes, in the currency of your FastSpring disbursements
nextChargePreTaxInPayoutCurrencyDisplay string amount of the next upcoming charge without taxes, formatted for display in the currency of your FastSpring disbursements
nextChargeTotal number amount of the next upcoming charge, in the nextChargeCurrency
nextChargeTotalDisplay string amount of the next upcoming charge, formatted for display based on the nextChargeCurrency
nextChargeTotalInPayoutCurrency number amount of the next upcoming charge, in the currency of your FastSpring disbursements
nextChargeTotalInPayoutCurrencyDisplay string amount of the next upcoming charge, formatted for display in the currency of your FastSpring disbursements
nextNotificationType string type of next customer-facing email notification message: "TRIAL_REMINDER", "PAYMENT_REMINDER", "PAYMENT_OVERDUE"
nextNotificationDate integer date of the next customer-facing email notification message, in milliseconds
nextNotificationDateValue integer date of the next customer-facing email notification message, in milliseconds (backward compatibility)
nextNotificationDateInSeconds integer date of the next customer-facing email notification message, in seconds
nextNotificationDateDisplay string date of the next customer-facing email notification message, formatted for display based on the language of the original subscription order
trialReminder object defines the timing of the customer-facing reminder email message that FastSpring will send (if any) regarding the approaching end of a free trial period
trialReminder.intervalUnit string unit of time used in conjunction with trialReminder.intervalLength to determine how long before the date of the first subscription charge FastSpring will send the trial reminder message: "day", "week", "month", "year"
trialReminder.intervalLength integer number of trialReminder.intervalUnits before the date of the first subscription charge the trial reminder message will be sent
paymentReminder object defines the timing of the customer-facing reminder email message sent before each scheduled subscription billing
paymentReminder.intervalUnit string unit of time used in conjunction with paymentReminder.intervalLength to determine how long before the date of the first subscription charge the trial reminder message will be sent: "day", "week", "month", "year"
paymentReminder.intervalLength integer number of paymentReminder.intervalUnits before each scheduled subscription billing that FastSpring will send the payment reminder message
paymentOverdue object defines the timing of the customer-facing payment overdue notification message(s) sent when a scheduled billing has failed
paymentOverdue.intervalUnit string unit of time used in conjunction with paymentOverdue.intervalLength to determine how long after a failed subscription billing FastSpring will send a payment overdue notification (or how long after a prior payment overdue notification message has been sent): "day", "week", "month", "year"
paymentOverdue.intervalLength integer number paymentOverdue.intervalUnits following the failed subscription billing that FastSpring will send the first payment overdue notification – and the number of paymentOverdue.intervalUnits between subsequent payment overdue notifications, if any
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
cancellationSetting object defines the timing of automatic subscription cancellation in the event of a failed subscription billing
cancellationSetting.cancellation string event trigger used in determining the timing of automatic subscription cancellation, as configured for the subscription product: "AFTER_LAST_NOTIFICATION" or "AFTER_PAYMENT_FAILURE"
cancellationSetting.intervalUnit string unit of time used in conjunction with cancellationSetting.intervalLength and cancellationSetting.cancellation to determine when a subscription will be canceled as a result of a failed subscription billing
cancellationSetting.intervalLength integer number of cancellationSetting.intervalUnits following the cancellationSetting.cancellation event trigger that the subscription will be canceled due to a failed subscription billing
addons array array consisting of all subscription addons included in the subscription, if any (only appears if the subscription instance includes addons)
addons.product string product ID/product path of the current subscription addon product
addons.sku string optional internal SKU ID (e.g., your part number) for the current subscription addon product
addons.display string customer-facing Display name of the current subscription addon product
addons.quantity integer subscribed quantity of the current subscription addon product
addons.price number price per quantity of the current subscription addon product, in the base currency of the Store
addons.priceDisplay string price per quantity of the current subscription addon product, in the base currency of the Store, formatted for display
addons.priceInPayoutCurrency number price per quantity of the current subscription addon product, in the currency of your FastSping disbursements
addons.priceInPayoutCurrencyDisplay string price per quantity of the current subscription addon product, in the currency of your FastSping disbursements, formatted for display
addons.discount number amount of the coupon applied to the current subscription addon product (if any)
addons.discountDisplay string amount of the coupon applied to the current subscription addon product (if any), formatted for display
addons.discountInPayoutCurrency number amount of the coupon applied to the current subscription addon product (if any), in the currency of your FastSpring disbursements
addons.discountInPayoutCurrencyDisplay string amount of the coupon applied to the current subscription addon product (if any), formatted for display in the currency of your FastSpring disbursements
addons.subtotal number product of (addons.priceaddons.discount) * addons.quantity
addons.subtotalDisplay string product of (addons.priceaddons.discount) * addons.quantity, formatted for display
addons.subtotalInPayoutCurrency number product of (addons.priceaddons.discount) * addons.quantity, in the currency of your FastSpring disbursements
addons.subtotalInPayoutCurrencyDisplay string product of (addons.priceaddons.discount) * addons.quantity, formatted for display in the currency of your FastSpring disbursements
addons.discounts array array consisting of coupon codes applied to the current subscription addon product (Note: At this time, only one coupon can be applied to an order.)
discounts array information about the coupon applied to the subscription (if any)
discounts.totalDiscountValue number total amount of the discount that will be applied, based on discounts.discountValue multiplied by discounts.discountDuration (only present when the discount type is an amount rather than a percentage)
discounts.discountPath string coupon ID of the coupon applied to the subscription
discounts.discountDuration integer total number of billings, including the original order, to which the coupon discount will be applied
discounts.percentValue number percentage of the coupon discount applied to the subscription (only present when the discount type is a percentage rather than an amount)
discounts.discountValue number amount of the discount per billing period, in the currency (only present when the discount type is an amount rather than a percentage)
setupFee object provides details of the one-time setup fee associated with the subscription instance, if any
setupFee.price object indicates the currency and amount of the one-time setup fee associated with the subscription instance, if any (e.g., "USD": 5)
setupFee.title object indicates the language and description shown to the customer for the one-time setup fee associated with the subscription instance, if any (e.g. "en": "Setup Fee Description")
fulfillments object details of the fulfillments associated with the subscription instance
fulfillments.<fulfillment action name>.license string license key(s) associated with the subscription instances
fulfillments.<fulfillment action name>.display string customer-facing display name of the current fulfillment action (e.g., "License Key" or the filename of the download file or signed PDF file)
fulfillments.<fulfillment action name>.type string type of the current fulfillment action:  "license" or "file"
fulfillments.<fulfillment action name>.size integer when type = "file", indicates the file size in bytes
fulfillments.<fulfillment action name>.file string when type = "file", indicates the unique download URL for the fulfillment file
fulfillments.instructions string HTML text of the subscription product's Post Order Instructions
instructions array instructions for recurring billings
instructions.product string indicates the product id/product path for the current instructions
instructions.type string type of instructions for the current instruction object; 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.periodStartDate integer date of the beginning of the instruction period, in milliseconds
instructions.periodStartDateValue integer date of the beginning of the instruction period, in milliseconds (backward compatibility)
instructions.periodStartDateInSeconds integer date of the beginning of the instruction period, in seconds
instructions.periodStartDateDisplay string date of the beginning of the instruction period, formatted for display based on the language selected for the original subscription order
instructions.periodEndDate integer date of the end of the instruction period, in milliseconds
instructions.periodEndDateValue integer date of the end of the instruction period, in milliseconds (backward compatibility)
instructions.periodEndDateInSeconds integer date of the end of the instruction period, in seconds
instructions.periodEndDateDisplay string date of the end of the instruction period, formatted for display based on the language selected for the original subscription order
instructions.intervalUnit string unit of time used in conjunction with instructions.intervalLength to determine the duration of the current instruction period: "adhoc", "day", "week", "month", "year"
instructions.intervalLength integer duration of the current instruction period in instructions.intervalUnits
instructions.discountIntervalUnit string only appears when type = "discounted" or "trial"; unit of time used in conjunction with discountIntervalLength to determine the duration of the current discount period: "day", "week", "month", or "year"
instructions.discountIntervalLength integer only appears when type = "discounted" or "trial"; number of discountIntervalUnits in the current discount period
instructions.discountDuration integer only appears when type = "discounted" or "trial"; number of discountIntervalUnits remaining, excluding the current discount period
instructions.discountDurationUnit string only appears when type = "discounted" or "trial"; unit of time used in conjunction with discountDurationLength to determine the remaining discount duration, excluding the current discount period: "day", "week", "month", or "year" (backward compatibility)
instructions.discountDurationLength integer only appears when type = "discounted" or "trial"; number of discountDurationUnits remaining, excluding the current discount period (backward compatibility)
instructions.discountPercent integer percentage of the discount for the current instruction period
instructions.discountPercentValue integer percentage of the discount for the current instruction period (backward compatibility)
instructions.discountPercentDisplay string percentage of the discount for the current instruction period, formatted for display
instructions.unitDiscount number discount amount per unit for the current instruction period, in the currency
instructions.unitDiscountDisplay string discount amount per unit for the current instruction period, formatted for display in the currency
instructions.unitDiscountInPayoutCurrency number discount amount per unit for the current instruction period, in the currency of your FastSpring disbursements
instructions.unitDiscountInPayoutCurrencyDisplay string discount amount per unit for the current instruction period, formatted for display in the currency of your FastSpring disbursements
instructions.discountTotal number total amount of the discount for the current instruction period, in the currency
instructions.discountTotalDisplay string total amount of the discount for the current instruction period, formatted for display based on the currency
instructions.discountTotalInPayoutCurrency number total amount of the discount for the current instruction period, in the currency of your FastSpring disbursements
instructions.discountTotalInPayoutCurrencyDisplay string total amount of the discount for the current instruction period, formatted for display in the currency of your FastSpring disbursements
instructions.price number list price of the product before any discounts, in the currency
instructions.priceDisplay string list price of the product before any discounts, formatted for display in the currency
instructions.priceInPayoutCurrency number list price of the product before any discounts, in the currency of your FastSpring disbursements
instructions.priceInPayoutCurrencyDisplay string list price of the product before any discounts, formatted for display in the currency of your FastSpring disbursements
instructions.priceTotal number product of (instructions.price * quantity), in the currency, for the current instruction period
instructions.priceTotalDisplay string product of (instructions.price * quantity), formatted for display in the currency, for the current instruction period
instructions.priceTotalInPayoutCurrency number product of (instructions.price * quantity), in the currency of your FastSpring disbursements, for the current instruction period
instructions.priceTotalInPayoutCurrencyDisplay string product of (instructions.price * quantity), formatted for display in the currency of your FastSpring disbursements, for the current instruction period
instructions.unitPrice number effective unit price after any discount, for the current instruction period, in the currency
instructions.unitPriceDisplay string effective unit price after any discount, for the current instruction period, formatted for display in the currency
instructions.unitPriceInPayoutCurrency number effective unit price after any discount, for the current instruction period, in the currency of your FastSpring disbursements
instructions.unitPriceInPayoutCurrencyDisplay string effective unit price after any discount, for the current instruction period, formatted for display in the currency of your FastSpring disbursements
instructions.total number product of (instructions.unitPrice * quantity) for the current instruction period, in the currency
instructions.totalDisplay string product of (instructions.unitPrice * quantity) for the current instruction period, formatted for display in the currency
instructions.totalInPayoutCurrency number product of (instructions.unitPrice * quantity) for the current instruction period, in the currency of your FastSpring disbursements
instructions.totalInPayoutCurrencyDisplay string product of (instructions.unitPrice * quantity) for the current instruction period, formatted for display in the currency of your FastSpring disbursements
customReferenceID string an optional value that you can add to a subscription instance via the FastSpring API using POST /subscriptions

 

Example 1 – Webhook Expansion Disabled

subscription.updated webhook example (webhook expansion disabled)

 

Example 2 – Webhook Expansion Enabled

subscription.updated webhook example (webhook expansion enabled)

The PUT /quotes/{id} endpoint updates an existing quote with the attributes you provide in the request. You must include all attributes in the request, otherwise they will either be cleared or reset to default values.

You can only update a quote with the Open status.

Required Attributes

Attribute Type Description Constraint
coupon string A coupon code for the quote. (This is not a coupon ID) If a coupon is present, items will be updated as necessary. 

If the coupon is blank, null, or missing from the request, any previous coupon will be removed. 

currency string The three-letter ISO code of the currency of the quote If the currency is updated, items will be updated as necessary. 
expirationDateDays number Number of days after quote creation that it expires This will update the expires and expiresDisplay attributes. 
fulfillmentTerm string The fulfillment term for the quote  
items string The items included in the quote  
name string A descriptive name for the quote  
notes string Prospect-facing notes that will appear on the quote  
netTermDays integer The net terms days for the quote. 
When value is 0, payment is required immediately, prior to order acceptance.
Must be one of: 0, 1, 7, 14, 30, 45, 60, 90
recipient contact The quote recipient’s contact information, including: email address, first name, last name  
recipientAddress address The recipient’s address information, including: city, country, postal code, and region If the country attribute of recipientAddress is updated, items will be updated as necessary. 

If the postalCode attribute of recipientAddress is updated items will be updated as necessary.

tags object Key-value pairs for your internal tracking. Tags are invisible to your prospect. FastSpring does not utilize your tags  
taxId string A tax ID for the quote If a taxId is present, items will be updated as necessary. 

If the taxId is blank, null, or missing from the request, any previous taxId will be removed and items will be updated as necessary. 

UpdateQuote Responses

Successful Responses:

Error Responses:

Example: Update the Name

The example below updates quote with the ID number QU123XYZABC456DEF789GHI0123Q to fix a typo in the recipient’s last name.

Using query parameters, the GET /quotes {id} endpoint can retrieve a single quote by it’s ID or list a collection of existing quotes that meet the custom search criteria.

Request bodies are not provided for a Retrieve Quotes request. If a request body is provided, it will be ignored.

Example Response

Fail to Retrieve Quote by ID

The request below failed to retrieve a quote by ID.

Get Open all Quotes

The example below retrieves all quotes with a status of OPEN .

Get Quotes within a Specified Date Range

The example request below retrieves the 25 most recently created quotes within a specified date range. 

 

Retrieve Quote Responses

Successful Responses

Error Responses

The POST /quotes/{id}/cancel endpoint cancels a quote, and sets the status to CANCELED. After this, the quoteURL no longer displays the quote.

Request Bodies are not required for a DeleteQuote request. If a request body is provided, it will be ignored.

Example Response

Use the /quotes API endpoint to efficiently process and manage your B2B orders and billing capabilities, including quote creation, digital invoicing, and order management. With this endpoint, you can:

Unlike other FastSpring APIs, this API utilizes a POST request for creating resources, and a PUT request for updating resources.

Endpoints

For additional information regarding each endpoint, click on the link to access the corresponding documentation.

For information regarding the Address, Contact, and Items attributes, see /quotes – Additional Attributes.

Quote Response Contents

Attribute Type Description
id string A unique identifier for the quote
buyerGenerated boolean Flag to determine if the quote was generated by a prospect
coupon string A coupon code for the quote. (This is not a coupon ID)
created string Date the quote was created in the format: 
YYYY-MM-DD’T’HH:MM:SS
createdBy contact Contact information of the quote creator, including their first name, last name, and email
currency string The three-letter ISO code of the currency of the quote
discount number The total discount amount for the quote. This is the sum of all discounts on the quote
discountDisplay string The formatted display for the discount
discountInPayoutCurrency number The discount in the currency of the FastSpring payout
discountInPayoutCurrencyDisplay string The formatted display for the discountInPayoutCurrency
expirationDateDays number Number of days after quote creation that it expires
expires string The expiration date of the quote
YYYY-MM-DD’T’HH:MM:SS
fulfillmentTerm string The fulfillment term for the quote
items item[] The items included in the quote
name string A descriptive name for the quote
notes string Prospect-facing notes that will appear on the quote
netTermDays number The number of days an invoice is due by default. If 0, immediate payment is required before the order is accepted.
quoteURL string The URL of the quote. This is the URL that you send to the prospect.
recipient contact The quote recipient’s contact information, including: email address, first name, last name
recipientAddress address The recipient’s address information, including: city, country, postal code, and region
status string The status of the quote:
OPEN – the quote has been created
PENDING PAYMENT – the quote has been accepted, but not paid
COMPLETED – the prospect has paid the quote
CANCELED – the quote has been canceled
EXPIRED – the expiration date has passed with no payment
statusHistory statusHistory The status history of the quote
tags object Key-value pairs for your internal tracking. Tags are invisible to your prospect. FastSpring does not utilize your tags
tax number The total tax for the quote
taxDisplay string The formatted display for tax
taxId string A tax ID for the quote
taxInPayoutCurrency number The tax in the FastSpring payout currency
taxInPayoutCurrencyDisplay string The formatted display for taxInPayoutCurrency
total number The total for the quote
totalInPayoutCurrency number The total in the FastSpring payout currency
totalInPayoutCurrencyDisplay string the formatted display for the totalInPayoutCurrency 
updated number The date the quote was last updated. Format: YYYY-MM-DD’T’HH:MM:SS

Quote Response Example

 

Attribute DefaultValue

Most attributes in the /quotes API have a default value assigned from the preexisting settings, products, and coupons in your FastSpring Store.

The DefaultValue is used in POST request bodies (such as creating a quote), and PUT request bodies (such as updating a quote). Attributes with a store-defined default value will be marked in the Note section for the request attributes.

For example, In the CreateQuoteRequest object, the notes, expirationDateDays, and netTermDays attributes have default values set within your store-level settings.

All attributes that have a DefaultValue associated to them are always Optional Request Attributes and should be left out of the request body if you wish to use the default value. To override an attribute’s DefaultValue, include the optional attribute in the request with a valid value.

Example: Default Notes Value

This example demonstrates using the DefaultValue configured in your store for the notes attribute in a CreateQuote request.

// "notes" attribute is missing

 

// "notes" attribute set to null 

Example: Override the Default Value

The example below demonstrates overriding the DefaultValue configured in your store for the notes attribute in a CreateQuote request.

Example: Override the Default Value to an Empty String

The example below demonstrates overriding your Store’s DefaultValue for the notes attribute to an empty string.