New Orders and Returns

payoutEntry.created

FastSpring sends the payoutEntry.created webhook when an order or return is created. When Webhook Expansion is enabled, the payoutEntry.created event includes the entire order, account, and subscription objects. If Webhook Expansion is not enabled, the account ID is returned, along with either the subscription ID, order ID or return ID depending on the payout triggering event.

Contents of Event Payload

The contents of the payload depend on whether the triggering event is an order or return.

  • Order: The order ID or object appears in the payload.
  • Return: The return ID or object appears in the payload.

All returns include the account ID or object.

Account

Name

Type

Description

account

object

Customer account information.
If you have enabled webhook expansion, see Account Contents for expanded contents.

subscriptions

string or object

Subscription information. If you have enabled webhook expansion, see Subscription Contents for expanded contents.

subtractions

object

Details of deductions from the total amount that will be disbursed to you for this transaction.

   tax

object

Tax applied to this transaction.

      currency

string

3 character ISO code of the currency in which subtractions.tax.amount is rendered.

      amount

number

Tax rendered for this transaction.

      percentage

integer

Tax percentage applied to this transaction.

   fastspring

object

FastSpring processing fee associated with this transaction.

      currency

string

3 character ISO code of the currency in which the subtraction amount is rendered.

      amount

number

Amount of the FastSpring processing fee associated with this transaction.

      percentage

integer

Percentage of the FastSpring processing fee associated with this transaction.

   subtractions

array

Taxes, withholdings, and fees deducted from purchase proceeds.

      withholdings

object

Information regarding tax withholdings.

          withholdings       

boolean

True: Proceeds are subject to tax withholdings.
False: Proceeds are not subject to tax withholdings.

         currency

string

3 character ISO code of the payout currency.

         amount

number

Amount that FastSpring will withhold.

         percentage              

number

Withholding percentage provided on Form W-8.

payouts

array

Information regarding the disbursement you will receive for this transaction.

   payee

string

Recipient name.

   currency

string

3 character ISO code of the currency in which your payout is rendered.

   payout

number

Amount to be paid to the payee in the configured currency.

   subtotal

number

Amount of all payouts. This will be the same for each payee.

   total

number

Total order amount, including subtractions.

Orders

Name

Type

Description

orderID

string or object

Internal order ID. If you have enabled webhook expansion, see Order Contents for the full payload.

reference

string

Customer-facing order reference.

live

string

False for test orders.

order

string
object

Internal order id. If webhook expansion is enabled, the full order object, including the items object returns.

Orders Example

{
  "orderId": "0dMiVgpdRK-SEzCMMFCZXg",
  "quote": null,
  "reference": "REFERENCE18F18978Y7",
  "live": false,
  "order": {
    "order": "0dMiVgpdRK-SEzCMMFCZXg",
    "id": "0dMiVgpdRK-SEzCMMFCZXg",
    "reference": "REFERENCE18F18978Y7",
    "buyerReference": null,
    "ipAddress": null,
    "completed": true,
    "changed": 1630600975802,
    "changedValue": 1630600975802,
    "changedInSeconds": 1630600975,
    "changedDisplay": "9/2/21",
    "language": "en",
    "live": false,
    "currency": "USD",
    "payoutCurrency": "USD",
    "quote": null,
    "invoiceUrl": "https://storefront.test.onfastspring.com/popup-storefront/account/order-number/invoice-number/,
    "account": "pg5sktRVSDawpsRaVhlbFA",
    "total": 1.96,
    "totalDisplay": "$1.96",
    "totalInPayoutCurrency": 1.96,
    "totalInPayoutCurrencyDisplay": "$1.96",
    "tax": 0,
    "taxDisplay": "$0.00",
    "taxInPayoutCurrency": 0,
    "taxInPayoutCurrencyDisplay": "$0.00",
    "subtotal": 1.96,
    "subtotalDisplay": "$1.96",
    "subtotalInPayoutCurrency": 1.96,
    "subtotalInPayoutCurrencyDisplay": "$1.96",
    "discount": 1.48,
    "discountDisplay": "$1.48",
    "discountInPayoutCurrency": 1.48,
    "discountInPayoutCurrencyDisplay": "$1.48",
    "discountWithTax": 1.48,
    "discountWithTaxDisplay": "$1.48",
    "discountWithTaxInPayoutCurrency": 1.48,
    "discountWithTaxInPayoutCurrencyDisplay": "$1.48",
    "billDescriptor": "YourExampleStore",
    "payment": {
      "type": "test"
    },
    "customer": {
      "first": "Jon",
      "last": "Tewes",
      "email": "[email protected]",
      "company": null,
      "phone": null,
      "subscribed": true
    },
    "address": {
      "city": "Lincoln",
      "regionCode": "NE",
      "regionDisplay": "Nebraska",
      "region": "Nebraska",
      "postalCode": "68510",
      "country": "US",
      "display": "Lincoln, Nebraska, 68510, US"
    },
    "recipients": [
      {
        "recipient": {
          "first": "First Name",
          "last": "Last Name",
          "email": "[email protected]",
          "company": null,
          "phone": null,
          "subscribed": true,
          "account": "pg5sktRVSDawpsRaVhlbFA",
          "address": {
            "city": "Lincoln",
            "regionCode": "NE",
            "regionDisplay": "Nebraska",
            "region": "Nebraska",
            "postalCode": "68510",
            "country": "US",
            "display": "Lincoln, Nebraska, 68510, US"
          }
        }
      }
    ],
    "notes": [],
    "items": [
      {
        "product": "0-base-subscription",
        "quantity": 1,
        "display": "$0 base subscription",
        "sku": "MC2.0",
        "imageUrl": null,
        "subtotal": 0.48,
        "subtotalDisplay": "$0.48",
        "subtotalInPayoutCurrency": 0.48,
        "subtotalInPayoutCurrencyDisplay": "$0.48",
        "discount": 0.36,
        "discountDisplay": "$0.36",
        "discountInPayoutCurrency": 0.36,
        "discountInPayoutCurrencyDisplay": "$0.36",
        "subscription": "DjBeYqgGSOi5cDRR1MymcQ",
        "fulfillments": {
          "0-base-subscription_license_2": [
            {
              "license": "8657615304",
              "display": "License Key",
              "type": "license"
            }
          ]
        }
      },
      {
        "product": "add-on-1",
        "quantity": 4,
        "display": "Add-on 1",
        "sku": "",
        "imageUrl": null,
        "subtotal": 1.48,
        "subtotalDisplay": "$1.48",
        "subtotalInPayoutCurrency": 1.48,
        "subtotalInPayoutCurrencyDisplay": "$1.48",
        "discount": 1.12,
        "discountDisplay": "$1.12",
        "discountInPayoutCurrency": 1.12,
        "discountInPayoutCurrencyDisplay": "$1.12",
        "fulfillments": {}
      }
    ]
  },
  "account": {
    "id": "pg5sktRVSDawpsRaVhlbFA",
    "account": "pg5sktRVSDawpsRaVhlbFA",
    "contact": {
      "first": "First Name",
      "last": "Last Name",
      "email": "[email protected]",
      "company": null,
      "phone": null,
      "subscribed": true
    },
    "address": {
      "address line 1": null,
      "address line 2": null,
      "city": "Lincoln",
      "company": "US",
      "postal code": "68510",
      "region": "US-NE",
      "region custom": null
    },
    "language": "en",
    "country": "US",
    "lookup": {
      "global": "53LH-y67S9-FenVdyMtkqw"
    },
    "url": "https://yourexamplestore.onfastspring.com/account"
  },
  "subscriptions": [
    {
      "id": "DjBeYqgGSOi5cDRR1MymcQ",
      "quote": null,
      "subscription": "DjBeYqgGSOi5cDRR1MymcQ",
      "active": true,
      "state": "active",
      "changed": 1628085270239,
      "changedValue": 1628085270239,
      "changedInSeconds": 1628085270,
      "changedDisplay": "8/4/21",
      "live": false,
      "currency": "USD",
      "account": "pg5sktRVSDawpsRaVhlbFA",
      "product": "0-base-subscription",
      "sku": "MC2.0",
      "display": "$0 base subscription",
      "quantity": 1,
      "adhoc": false,
      "autoRenew": true,
      "price": 12.99,
      "priceDisplay": "$12.99",
      "priceInPayoutCurrency": 12.99,
      "priceInPayoutCurrencyDisplay": "$12.99",
      "discount": 0,
      "discountDisplay": "$0.00",
      "discountInPayoutCurrency": 0,
      "discountInPayoutCurrencyDisplay": "$0.00",
      "subtotal": 52.99,
      "subtotalDisplay": "$52.99",
      "subtotalInPayoutCurrency": 52.99,
      "subtotalInPayoutCurrencyDisplay": "$52.99",
      "tags": {
        "irclickid": "XaVxe2zQdwsEWhNRJk03ET-MUkBU6zzc0000000"
      },
      "next": 1630713600000,
      "nextValue": 1630713600000,
      "nextInSeconds": 1630713600,
      "nextDisplay": "9/4/21",
      "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": 1,
      "periods": null,
      "remainingPeriods": null,
      "begin": 1628035200000,
      "beginValue": 1628035200000,
      "beginInSeconds": 1628035200,
      "beginDisplay": "8/4/21",
      "intervalUnit": "month",
      "intervalLength": 1,
      "nextChargeCurrency": "USD",
      "nextChargeDate": 1630713600000,
      "nextChargeDateValue": 1630713600000,
      "nextChargeDateInSeconds": 1630713600,
      "nextChargeDateDisplay": "9/4/21",
      "nextChargePreTax": 52.99,
      "nextChargePreTaxDisplay": "$52.99",
      "nextChargePreTaxInPayoutCurrency": 52.99,
      "nextChargePreTaxInPayoutCurrencyDisplay": "$52.99",
      "nextChargeTotal": 52.99,
      "nextChargeTotalDisplay": "$52.99",
      "nextChargeTotalInPayoutCurrency": 52.99,
      "nextChargeTotalInPayoutCurrencyDisplay": "$52.99",
      "nextNotificationType": "PAYMENT_REMINDER",
      "nextNotificationDate": 1630108800000,
      "nextNotificationDateValue": 1630108800000,
      "nextNotificationDateInSeconds": 1630108800,
      "nextNotificationDateDisplay": "8/28/21",
      "paymentReminder": {
        "intervalUnit": "week",
        "intervalLength": 1
      },
      "paymentOverdue": {
        "intervalUnit": "week",
        "intervalLength": 1,
        "total": 6,
        "sent": 0
      },
      "cancellationSetting": {
        "cancellation": "AFTER_LAST_NOTIFICATION",
        "intervalUnit": "week",
        "intervalLength": 1
      },
      "addons": [
        {
          "product": "add-on-1",
          "sku": "",
          "display": "Add-on 1",
          "quantity": 4,
          "price": 10,
          "priceDisplay": "$10.00",
          "priceInPayoutCurrency": 10,
          "priceInPayoutCurrencyDisplay": "$10.00",
          "discount": 0,
          "discountDisplay": "$0.00",
          "discountInPayoutCurrency": 0,
          "discountInPayoutCurrencyDisplay": "$0.00",
          "subtotal": 40,
          "subtotalDisplay": "$40.00",
          "subtotalInPayoutCurrency": 40,
          "subtotalInPayoutCurrencyDisplay": "$40.00",
          "discounts": []
        }
      ],
      "fulfillments": {
        "0-base-subscription_license_2": [
          {
            "license": "8657615304",
            "display": "License Key",
            "type": "license"
          }
        ]
      },
      "instructions": [
        {
          "product": "0-base-subscription",
          "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": 12.99,
          "priceDisplay": "$12.99",
          "priceInPayoutCurrency": 12.99,
          "priceInPayoutCurrencyDisplay": "$12.99",
          "priceTotal": 12.99,
          "priceTotalDisplay": "$12.99",
          "priceTotalInPayoutCurrency": 12.99,
          "priceTotalInPayoutCurrencyDisplay": "$12.99",
          "unitPrice": 12.99,
          "unitPriceDisplay": "$12.99",
          "unitPriceInPayoutCurrency": 12.99,
          "unitPriceInPayoutCurrencyDisplay": "$12.99",
          "total": 12.99,
          "totalDisplay": "$12.99",
          "totalInPayoutCurrency": 12.99,
          "totalInPayoutCurrencyDisplay": "$12.99"
        }
      ]
    }
  ],
  "subtractions": {
    "tax": {
      "currency": "USD",
      "amount": 0,
      "percentage": 0
      
    },
    "fastspring": {
      "currency": "USD",
      "amount": 1.0872,
      "percentage": 55.47
    
    },
    "withholdings": {
        "withholdings": true,
        "currency" "USD",
        "amount": 23.34,
        "percentage": 15
    
    }
  },
  "payouts": [
    {
      "payee": "solisinc",
      "currency": "USD",
      "payout": "0.88",
      "subtotal": 0.88,
      "total": "1.96"
    }
  }
   
    }
  ]
}

Returns

Name

Type

Description

return

string
object

Internal return ID (expansion disabled). Returns object with all return details (expansion enabled).

   return

string

Return ID.

   reference

string

Customer-facing return reference.

   completed

boolean

True for a completed return.

   changed

integer

Date of the most recent update to the return record, in milliseconds.

   changedValue

integer

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

   changedInSeconds

integer

Date of the most recent update to the return record, in seconds.

   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.

   live

boolean

False for returns on a test order.

   account

string

FastSpring-generated customer account ID.

   currency

string

3 character ISO code of the return currency.

   payoutCurrency

string

3 character ISO code of currency in which your disbursements are made.

   totalReturn

number

Total return amount.

   totalReturnDisplay

string

Total return amount, formatted for display in return.currency.

   totalReturnInPayoutCurrency

number

Total return amount, in the currency in which your disbursements are made.

   totalReturnInPayoutCurrencyDisplay

string

Total return amount, formatted for display in the currency in which your disbursements are made.

   tax

number

Tax amount.

   taxDisplay

string

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

   taxInPayoutCurrency

number

Tax amount in the your disbursement currency.

   taxInPayoutCurrencyDisplay

string

Tax amount, formatted for display in your disbursement currency.

   subtotal

number

Return subtotal.

   subtotalDisplay

string

Return subtotal formatted for display.

   subtotalInPayoutCurrency

number

Return subtotal in your disbursement currency.

   subtotalInPayoutCurrencyDisplay

string

Return subtotal formatted for display in your disbursement currency.

   totalRefundInPayoutCurrency

number

Total refund amount, in the currency in your disbursement currency.

   payment

object

Payment method used for the order, and the refund.

      type

string

Payment method used for the order.

      creditcard

string

Type of credit or debit card used for the order.

      cardEnding

string

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

      bank

string

Type of bank transfer used to pay for the order.

   reason

string

Pre-defined return reason. This is selected when you process the return in the app.

   note

string

Comment or note entered while processing the return.

   original

object

Original order information.

      id

string

Internal order ID.

      order

string

Internal order ID.

      reference

string

Customer-facing order reference.

      account

string

FastSpring-generated customer account ID.

      currency

string

Currency of the original order.

      payoutCurrency

string

Disbursement currency, at the time of the order.

      total

number

Order total in the transaction's currency.

      totalDisplay

string

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

      totalInPayoutCurrency

number

Order total in your disbursement currency.

      totalInPayoutCurrencyDisplay

string

Order total, formatted for display in your disbursement currency.

      tax

number

Tax amount.

      taxDisplay

string

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

      taxInPayoutCurrency

number

Tax amount in your disbursement currency.

      taxInPayoutCurrencyDisplay

string

Tax amount, formatted for display in your disbursement currency.

      subtotal

number

Order subtotal in the transaction's currency.

      subtotalDisplay

string

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

      subtotalInPayoutCurrency

number

Order subtotal in your disbursement currency.

      subtotalInPayoutCurrencyDisplay

string

Order subtotal, formatted for display in your disbursement currency.

      notes

string

Internal note(s) entered for the original order.

   customer

object

Information of the customer receiving the refund.

   first

string

Customer's first name.

      last

string

Customer's last name.

      email

string

Customer's email address.

      company

string

Customer's company name.

      phone

string

Customer's phone number.

   items

array

On object for each product returned. For full contents, see Items Contents.

Return Example:

{
  "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"
    }
  ]
}

Did this page help you?