FastSpring AppAPI ReferenceWebhooksFastSpring JSChangelogFastSpring.com
Developer Documentation
Sign In

Return or Refund an Order

return.created

Overview of the return.created webhook

When a return.created event is triggered, FastSpring sends a webhook payload containing details about the refund or return. This webhook fires only when a return or refund has been issued. It does not fire for:

  • Tax-only refunds
  • Manual credit adjustments that were not created as returns

If webhook expansion is enabled, the payload includes full account and product objects. Otherwise, the payload includes only the corresponding IDs.

This page provides:

  • A full sample payload showing a populated return.created webhook
  • A detailed table listing every payload property, including name, type, and description
  • Notes on when this webhook is triggered and which fields appear based on Webhook Expansion

Browse the table sections below or use the quick links to jump to a specific group of fields.

Tip: Not all fields are always included. Refer to the Payload properties table to understand when a field appears.

Webhook payload example (expansion enabled)

When a return.created event is triggered, the webhook sends the following JSON payload:

{
    "return": "aBCDE12fGH3iJkL4mNOpqr",
    "quote": null,
    "reference": "ABC1234567-8910-11121D",
    "completed": true,
    "changed": 1751896963416,
    "changedValue": 1751896963416,
    "changedInSeconds": 1751896963,
    "changedDisplay": "7/7/25",
    "changedDisplayISO8601": "2025-07-07",
    "live": false,
    "account": {
        "id": "abCdE1FGH2Hij3KLMnOpqR",
        "account": "abCdE1FGH2Hij3KLMnOpqR",
        "contact": {
            "first": "Jane",
            "last": "Doe",
            "email": "[email protected]",
            "company": "ABC Company",
            "phone": "5555555555",
            "subscribed": true
        },
        "address": {
            "addressLine1": "801 Garden St",
            "addressLine2": "Suite 201",
            "city": "Santa Barbara",
            "country": "US",
            "postal code": "93101",
            "region": "US-CA",
            "region custom": "California",
            "company": "ABC Company"
        },
        "language": "en",
        "country": "US",
        "lookup": { "global": "8x3FKfUESieeIgGoxHBRLg" },
        "url": "https://company.onfastspring.com/account"
    },
    "currency": "USD",
    "payoutCurrency": "USD",
    "totalReturn": 14.95,
    "totalReturnDisplay": "$14.95",
    "totalReturnInPayoutCurrency": 14.95,
    "totalReturnInPayoutCurrencyDisplay": "$14.95",
    "tax": 0.0,
    "taxDisplay": "$0.00",
    "taxInPayoutCurrency": 0.0,
    "taxInPayoutCurrencyDisplay": "$0.00",
    "subtotal": 14.95,
    "subtotalDisplay": "$14.95",
    "subtotalInPayoutCurrency": 14.95,
    "subtotalInPayoutCurrencyDisplay": "$14.95",
    "totalRefundInPayoutCurrency": 14.95,
    "payment": {
        "type": "test",
        "cardEnding": "4242"
    },
    "reason": "Duplicate Order",
    "note": "As requested by customer",
    "type": "RETURN",
    "refundPerformerType": "sellerApp",
    "refundSourceComponent": "refund",
    "original": {
        "id": "wvje2BeoQbyCRAbucnPrRw",
        "order": "wvje2BeoQbyCRAbucnPrRw",
        "reference": "ABC1234567-8910-11121D",
        "account": "abCdE1FGH2Hij3KLMnOpqR",
        "currency": "USD",
        "payoutCurrency": "USD",
        "total": 14.95,
        "totalDisplay": "$14.95",
        "totalInPayoutCurrency": 14.95,
        "totalInPayoutCurrencyDisplay": "$14.95",
        "tax": 0.0,
        "taxDisplay": "$0.00",
        "taxInPayoutCurrency": 0.0,
        "taxInPayoutCurrencyDisplay": "$0.00",
        "subtotal": 14.95,
        "subtotalDisplay": "$14.95",
        "subtotalInPayoutCurrency": 14.95,
        "subtotalInPayoutCurrencyDisplay": "$14.95",
        "notes": []
    },
    "customer": {
        "first": "John",
        "last": "Doe",
        "email": "[email protected]",
        "company": null,
        "phone": "5555555555",
        "subscribed": true
    },
    "items": [
     {
        "product": "furious-falcon",
        "quantity": 1,
        "display": "Furious Falcon",
        "sku": "SKU-12345",
        "refundType": "Full Refund",
        "subtotal": 14.95,
        "subtotalDisplay": "$14.95",
        "subtotalInPayoutCurrency": 14.95,
        "subtotalInPayoutCurrencyDisplay": "$14.95",
        "fulfillments": {},
        "withholdings": {
            "taxWithholdings": false
        }
     }
    ],
    "refundPerformer": "[email protected]"
}

Payload properties

The payload properties table outlines each property in the return.created event JSON payload, specifying their name, data type, and description.

Name Type Description
Return Metadata Back to top ↑
return string Unique identifier to reference a specific return.
quote string Quote identifier associated with the return, if any.
reference string Reference code for the return.
completed boolean Indicates whether the return process has been completed. true if the refund has been processed successfully; false if the return has not been processed, or was unsuccessful.
live boolean Indicates whether the order is live. Returns true if the order is live; false if it is a test order.
Timestamps Back to top ↑
changed integer Timestamp (in milliseconds) of the most recent update to the refund.
changedValue integer Duplicate of changed for backward compatibility.
changedInSeconds integer Timestamp (in seconds) of the most recent update to the refund.
changedDisplay string Formatted display string for the most recent refund update. The display is formatted based on the language of the original order.
changedDisplayISO8601 string ISO 8601 formatted timestamp for the last refund update.
Account Object Back to top ↑
id string Unique ID for the customer account.
account string Duplicate of account.id for backward compatibility.
contact object Contact details for the account.
contact.first string First name of the account contact.
contact.last string Last name of the account contact.
contact.email string Email address of the account contact.
contact.company string Company name of the account contact, if provided.
contact.phone string Phone number of the account contact, if provided.
contact.subscribed boolean true if the account contact is subscribed to updates; otherwise false.
address object Address details for the account.
address.address line 1 string Primary street address line.
address.address line 2 string Secondary street address line.
address.city string City of the account address.
address.country string 2-letter ISO country code for the address.
address.postal code string Postal or ZIP code of the address.
address.region string Region (state/province) for the address.
address.region custom string Custom region name, if not standard.
address.company string Company name associated with this address, if provided.
language string 2-letter ISO code of the account's preferred language.
country string 2-letter ISO country code of the account's location.
lookup object Lookup identifiers for the account.
lookup.global string Public account ID used in customer-facing portals.
url string URL to the account management page.
Pricing Back to top ↑
currency string 3 character ISO code of the order currency. The return currency is the same.
payoutCurrency string 3 character ISO code of your disbursement currency.
totalReturn number Total return amount in the original transaction's currency.
totalReturnDisplay string Formatted version of totalReturn.
totalReturnInPayoutCurrency number Total return amount in your disbursement currency.
totalReturnInPayoutCurrencyDisplay string Formatted version of totalReturnInPayoutCurrency.
tax number Tax amount returned, in the original transaction's currency.
taxDisplay string Formatted version of tax.
taxInPayoutCurrency number Tax amount returned, in your disbursement currency.
taxInPayoutCurrencyDisplay string Formatted version of taxInPayoutCurrency.
subtotal number Subtotal of the return (excludes tax), in the original transaction's currency.
subtotalDisplay string Formatted version of subtotal.
subtotalInPayoutCurrency number Subtotal of the return, in your disbursement currency.
subtotalInPayoutCurrencyDisplay string Formatted version of subtotalInPayoutCurrency.
totalRefundInPayoutCurrency string Formatted version of order.subtotalInPayoutCurrency.
Payment Method Back to top ↑
payment.type string Payment method used for the order. Example values: paypal, amazon, applepay, creditcard, kakaopay, test, bank, alipay, purchase-order, free, upi.
payment.variant string Returned when order.payment.type is upi. Indicates the buyer's UPI app or flow. Example values: upigpay, upiphonepe, upipaytm, upidesktop.
payment.creditcard string Returned when order.payment.type is creditcard. Type of credit or debit card used. Example values: visa, mastercard, amex, discover, jcb, carteblanche, dinersclub, unionpay, elo, hipercard.
payment.cardEnding string Returned when order.payment.type is creditcard. Last four digits of the card number used for the order.
payment.bank string Returned when order.payment.type is bank. Type of bank transfer used to pay for the order. Example values: wire, brazilwire, ideal, giropay, sofort, ecard, sepa, alipay.
Refund Details Back to top ↑
reason string Reason for the return or refund.
note string Optional note or comment provided when creating the return.
type string Type of return processed. Values include: RETURN, CHARGEBACK, PAYMENTRISK, PAYPAL.
refundPerformerType string Entity or component that performed the refund.
refundSourceComponent string Component that initiated the refund.
refundPerformer string Email or identifier of the person or system that issued the refund.
Original Order Details Back to top ↑
original object Details of the order session that is returned.
original.id string Unique identifier of the original order instance.
original.order string Duplicate of original.id for backward compatibility.
original.reference string Customer-facing reference code for the original order.
original.account string FastSpring-generated customer account ID associated with the original order.
original.currency string 3 character ISO currency code for the original order.
original.payoutCurrency string 3 character ISO currency code used for disbursements.
original.total number Total amount charged for the original order (before tax).
original.totalDisplay string Formatted display of original.total.
original.totalInPayoutCurrency number Total amount for the original order in the payout currency.
original.totalInPayoutCurrencyDisplay string Formatted display of original.totalInPayoutCurrency.
original.tax number Total tax amount for the original order.
original.taxDisplay string Formatted display of original.tax.
original.taxInPayoutCurrency number Tax amount in the payout currency.
original.taxInPayoutCurrencyDisplay string Formatted display of original.taxInPayoutCurrency.
original.subtotal number Subtotal before tax and discounts for the original order.
original.subtotalDisplay string Formatted display of original.subtotal.
original.subtotalInPayoutCurrency number Subtotal for the original order in the payout currency.
original.subtotalInPayoutCurrencyDisplay string Formatted display of original.subtotalInPayoutCurrency.
original.notes array Array of internal notes or comments on the original order (empty if none).
Customer Object Back to top ↑
customer object Details of the customer who placed the order.
customer.first string Customer’s first name.
customer.last string Customer’s last name.
customer.email string Customer’s email address.
customer.company string Customer’s company name, if provided.
customer.phone string Customer’s phone number, if provided.
customer.subscribed boolean true if the customer is subscribed to updates; otherwise false.
Items Array Back to top ↑
items array Array of item objects purchased in the order. Each object contains product, pricing, and subscription info.
product string ID of the product associated with the item.
quantity number Quantity of the product purchased.
display string Customer-facing name of the product.
sku string Product SKU assigned in your FastSpring catalog.
refundType string Type of refund applied. Example values: Full Refund or Partial Refund.
subtotal number Pre-tax subtotal for the item, in the transaction currency.
subtotalDisplay string Formatted subtotal for the item, in the transaction currency.
subtotalInPayoutCurrency number Subtotal for the item, in your payout currency.
subtotalInPayoutCurrencyDisplay string Formatted subtotal for the item, in your payout currency.
Fulfillments Object Back to top ↑
fulfillments.display string Display name of the downloadable file or fulfillment action.
fulfillments.size integer File size in bytes. Applies when the fulfillment type is file.
fulfillments.file string Secure URL for downloading the fulfillment file.
fulfillments.type string Fulfillment type. Example values: file, license.
Withholdings Object Back to top ↑
withholdings.amount number Total amount withheld from this item, in the transaction currency.
withholdings.amountDisplay string Formatted display of the withheld amount. Example: $12.00.
withholdings.amountInPayoutCurrency number Amount withheld in your payout currency.
withholdings.amountInPayoutCurrencyDisplay string Formatted withheld amount in payout currency. Example: $12.00.
withholdings.percentage number Percentage of the item's total that was withheld. Example: 15.
withholdings.taxWithholdings boolean Indicates whether this withholding is related to taxes. true if tax-related; otherwise false.
Back to top ↑