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

NameTypeDescription
account objectCustomer account information.
If you have enabled webhook expansion, see Account Contents for expanded contents.
subscriptionsstring or objectSubscription information. If you have enabled webhook expansion, see Subscription Contents for expanded contents.
subtractions objectDetails of deductions from the total amount that will be disbursed to you for this transaction.
   taxobjectTax applied to this transaction.
      currencystring3 character ISO code of the currency in which subtractions.tax.amount is rendered.
      amountnumberTax rendered for this transaction.
      percentageintegerTax percentage applied to this transaction.
   fastspringobjectFastSpring processing fee associated with this transaction.
      currencystring3 character ISO code of the currency in which the subtraction amount is rendered.
      amountnumberAmount of the FastSpring processing fee associated with this transaction.
      percentageintegerPercentage of the FastSpring processing fee associated with this transaction.
   subtractionsarrayTaxes, withholdings, and fees deducted from purchase proceeds.
      withholdingsobjectInformation regarding tax withholdings.
          withholdings       booleanTrue: Proceeds are subject to tax withholdings.
False: Proceeds are not subject to tax withholdings.
         currencystring3 character ISO code of the payout currency.
         amountnumberAmount that FastSpring will withhold.
         percentage              numberWithholding percentage provided on Form W-8.
payouts arrayInformation regarding the disbursement you will receive for this transaction.
   payeestringRecipient name.
   currencystring3 character ISO code of the currency in which your payout is rendered.
   payoutstringAmount to be paid to the payee in the configured currency.
   subtotalnumberAmount of all payouts. This will be the same for each payee.
   totalstringTotal order amount, including subtractions.

Orders

NameTypeDescription
orderID string or objectInternal order ID. If you have enabled webhook expansion, see Order Contents for the full payload.
reference stringCustomer-facing order reference.
live stringFalse for test orders.
order string
object
Internal order id. If webhook expansion is enabled, the full order object, including the [items object] (https://developer.fastspring.com/reference/webhook-expansion#item-contents) 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

NameTypeDescription
return string
object
Internal return ID (expansion disabled). Returns object with all return details (expansion enabled).
   return stringReturn ID.
   reference stringCustomer-facing return reference.
   completed booleanTrue for a completed return.
   changed integerDate of the most recent update to the return record, in milliseconds.
   changedValue integerDate of the most recent update to the return record, in milliseconds.
(backward compatibility)
   changedInSeconds integerDate of the most recent update to the return record, in seconds.
   changedDisplay stringDate of the most recent update to the return record, formatted for display based on the language in which the order was processed.
   live booleanFalse for returns on a test order.
   account stringFastSpring-generated customer account ID.
   currency string3 character ISO code of the return currency.
   payoutCurrency string3 character ISO code of currency in which your disbursements are made.
   totalReturn numberTotal return amount.
   totalReturnDisplay stringTotal return amount, formatted for display in return.currency.
   totalReturnInPayoutCurrency numberTotal return amount, in the currency in which your disbursements are made.
   totalReturnInPayoutCurrencyDisplay stringTotal return amount, formatted for display in the currency in which your disbursements are made.
   tax numberTax amount.
   taxDisplay stringTax amount, formatted to display in the transaction's currency.
   taxInPayoutCurrency numberTax amount in the your disbursement currency.
   taxInPayoutCurrencyDisplay stringTax amount, formatted for display in your disbursement currency.
   subtotal numberReturn subtotal.
   subtotalDisplay stringReturn subtotal formatted for display.
   subtotalInPayoutCurrency numberReturn subtotal in your disbursement currency.
   subtotalInPayoutCurrencyDisplay stringReturn subtotal formatted for display in your disbursement currency.
   totalRefundInPayoutCurrency numberTotal refund amount, in the currency in your disbursement currency.
   payment objectPayment method used for the order, and the refund.
      type stringPayment method used for the order.
      creditcard stringType of credit or debit card used for the order.
      cardEnding stringLast four digits of the card number used for the order.
      bank stringType of bank transfer used to pay for the order.
   reason stringPre-defined return reason. This is selected when you process the return in the app.
   note stringComment or note entered while processing the return.
   original objectOriginal order information.
      id stringInternal order ID.
      order stringInternal order ID.
      reference stringCustomer-facing order reference.
      account stringFastSpring-generated customer account ID.
      currency stringCurrency of the original order.
      payoutCurrency stringDisbursement currency, at the time of the order.
      total numberOrder total in the transaction's currency.
      totalDisplay stringOrder total, formatted for display in the transaction's currency.
      totalInPayoutCurrency numberOrder total in your disbursement currency.
      totalInPayoutCurrencyDisplay stringOrder total, formatted for display in your disbursement currency.
      tax numberTax amount.
      taxDisplay stringTax amount, formatted for display in the transaction's currency.
      taxInPayoutCurrency numberTax amount in your disbursement currency.
      taxInPayoutCurrencyDisplay stringTax amount, formatted for display in your disbursement currency.
      subtotal numberOrder subtotal in the transaction's currency.
      subtotalDisplay stringOrder subtotal, formatted for display in the transaction's currency.
      subtotalInPayoutCurrency numberOrder subtotal in your disbursement currency.
      subtotalInPayoutCurrencyDisplay stringOrder subtotal, formatted for display in your disbursement currency.
      notes stringInternal note(s) entered for the original order.
   customer objectInformation of the customer receiving the refund.
   first stringCustomer's first name.
      last stringCustomer's last name.
      email stringCustomer's email address.
      company stringCustomer's company name.
      phone stringCustomer's phone number.
   items arrayOn 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"
    }
  ]
}