/returns
Overview
This article provides information about the /returns endpoint of the FastSpring API. Using this endpoint, you can retrieve return details or create full order returns.
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"
}
]
}