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": "jane.doe@company.com",
            "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": "john.doe@example.com",
        "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": "jane.doe@example.com"
}

Navigate this webhook

The return.created webhook payload includes details about a completed return, including account info, financials, refund context, and the original order. Use the cards below to jump directly to a section of the property reference.

Payload properties

All fields below are included in the return.created webhook payload. Fields are grouped into categories for easier navigation.

Name	Type	Description
Return Metadata
return	string	Unique identifier for the return
quote	string\|null	Associated quote ID when the return is tied to a quote
reference	string	Customer-facing reference for the return
completed	boolean	Whether the return has completed processing
changed	integer	Return creation timestamp in milliseconds
changedValue	integer	Duplicate of `changed` for backward compatibility
changedInSeconds	integer	Return creation timestamp in seconds
changedDisplay	string	User-friendly return creation date
changedDisplayISO8601	string	Return creation date in ISO 8601 format
live	boolean	Whether the return originated in live mode
Account Object
account.id	string	Customer account ID for the return
account.account	string	Duplicate of `account.id` for backward compatibility
account.contact.first	string	Account contact first name
account.contact.last	string	Account contact last name
account.contact.email	string	Account contact email address
account.contact.company	string\|null	Account contact company name
account.contact.phone	string	Account contact phone number
account.contact.subscribed	boolean	Whether the account contact is subscribed to updates
account.address.addressLine1	string	Account address line 1
account.address.addressLine2	string	Account address line 2
account.address.city	string	Account address city
account.address.country	string	Two-letter ISO country code
account.address.postal code	string	Postal or ZIP code
account.address.region	string	Region code for the account address
account.address.region custom	string	Human-readable region name
account.address.company	string	Company name on the account address
account.language	string	Two-letter ISO language code for the account
account.country	string	Two-letter ISO country code for the account
account.lookup.global	string	Public account lookup ID for portals
account.url	string	Account management URL
Financials
currency	string	Three-letter ISO currency code for the return
payoutCurrency	string	Three-letter ISO payout currency code
totalReturn	number	Total returned amount in transaction currency
totalReturnDisplay	string	Formatted total returned amount
totalReturnInPayoutCurrency	number	Total returned amount in payout currency
totalReturnInPayoutCurrencyDisplay	string	Formatted total returned amount in payout currency
tax	number	Refunded tax in transaction currency
taxDisplay	string	Formatted refunded tax
taxInPayoutCurrency	number	Refunded tax in payout currency
taxInPayoutCurrencyDisplay	string	Formatted refunded tax in payout currency
subtotal	number	Refunded subtotal in transaction currency
subtotalDisplay	string	Formatted refunded subtotal
subtotalInPayoutCurrency	number	Refunded subtotal in payout currency
subtotalInPayoutCurrencyDisplay	string	Formatted refunded subtotal in payout currency
totalRefundInPayoutCurrency	number	Total refunded in payout currency (overall)
Payment Method
payment.type	string	Payment method used for the original order (e.g., `test`, `creditcard`)
payment.cardEnding	string	Last four digits of the card when applicable
Refund Context
reason	string	Reason provided for the refund
note	string	Internal note associated with the return
type	string	Return type (e.g., `RETURN`)
refundPerformerType	string	Component that initiated the refund (e.g., `sellerApp`)
refundSourceComponent	string	Source of the refund request (e.g., `refund`)
refundPerformer	string	Identifier of the user or system that performed the refund
Original Order
original.id	string	Original order ID
original.order	string	Duplicate of `original.id` for backward compatibility
original.reference	string	Customer-facing reference for the original order
original.account	string	Account ID associated with the original order
original.currency	string	Original order currency
original.payoutCurrency	string	Original order payout currency
original.total	number	Original order total in transaction currency
original.totalDisplay	string	Formatted original order total
original.totalInPayoutCurrency	number	Original order total in payout currency
original.totalInPayoutCurrencyDisplay	string	Formatted original order total in payout currency
original.tax	number	Original order tax in transaction currency
original.taxDisplay	string	Formatted original order tax
original.taxInPayoutCurrency	number	Original order tax in payout currency
original.taxInPayoutCurrencyDisplay	string	Formatted original order tax in payout currency
original.subtotal	number	Original order subtotal in transaction currency
original.subtotalDisplay	string	Formatted original order subtotal
original.subtotalInPayoutCurrency	number	Original order subtotal in payout currency
original.subtotalInPayoutCurrencyDisplay	string	Formatted original order subtotal in payout currency
original.notes	array	Array of notes on the original order (may be empty)
Customer Object
customer.first	string	Customer first name
customer.last	string	Customer last name
customer.email	string	Customer email address
customer.company	string\|null	Customer company name
customer.phone	string	Customer phone number
customer.subscribed	boolean	Whether the customer is subscribed to updates
Items Array
items	array	Array of returned items
items.product	string	Product path or identifier
items.quantity	integer	Quantity returned
items.display	string	Display name of the returned product
items.sku	string	SKU of the returned product
items.refundType	string	Refund type applied (e.g., `Full Refund`)
items.subtotal	number	Refunded item subtotal in transaction currency
items.subtotalDisplay	string	Formatted refunded item subtotal
items.subtotalInPayoutCurrency	number	Refunded item subtotal in payout currency
items.subtotalInPayoutCurrencyDisplay	string	Formatted refunded item subtotal in payout currency
items.fulfillments	object	Fulfillment details for the returned item (empty when not applicable)
items.withholdings.taxWithholdings	boolean	Whether tax withholdings are applied to the returned item