Manage Refund Requests
Refund Request Lifecycle
After an order has been placed, the buyer may initiate a refund, which creates a refund request in a pending_seller_response
state.
The seller may respond via Reverb's API by updating the refund request with one of the following states:
conditionally_approved
: Approve the refund after the item has been returned. The refund request is still active and will need to be approved at a later time.approved
: Approve the refund immediately, typically after the item has been returned. This will immediately credit the buyer and debit the seller. Once approved, the refund request is completed and no further action is needed.denied
: Deny the refund, which will complete the refund request without crediting the buyer or debiting the seller. Once denied, the refund request is completed and no further action is needed.
When responding to a refund request by approving or conditionally approving, the seller may also change the amount to be refunded.
A single order can have multiple refund requests, as long as the order has not been fully refunded.
Getting a List of Refund Requests
By default, refund requests with an active state (pending_seller_response
or conditionally_approved
) are returned. These can be filtered by created date range or updated date range:
curl \
-XGET \
-H "Authorization: Bearer [oauth_token]" \
-H "Content-Type: application/hal+json" \
-H "Accept-Version: 3.0" \
https://api.reverb.com/api/my/refund_requests/selling?created_start_date=2017-10-01T12:00-00:00&created_end_date=2017-10-31T12:00-00:00
curl \
-XGET \
-H "Authorization: Bearer [oauth_token]" \
-H "Content-Type: application/hal+json" \
-H "Accept-Version: 3.0" \
https://api.reverb.com/api/my/refund_requests/selling?updated_start_date=2017-10-01T12:00-00:00&updated_end_date=2017-10-31T12:00-00:00
Refund requests can also be filtered to an individual state, a list of states, order number, and paginated through:
curl \
-XGET \
-H "Authorization: Bearer [oauth_token]" \
-H "Content-Type: application/hal+json" \
-H "Accept-Version: 3.0" \
https://api.reverb.com/api/my/refund_requests/selling?state=approved
curl \
-XGET \
-H "Authorization: Bearer [oauth_token]" \
-H "Content-Type: application/hal+json" \
-H "Accept-Version: 3.0" \
https://api.reverb.com/api/my/refund_requests/selling?order_number=123
curl \
-XGET \
-H "Authorization: Bearer [oauth_token]" \
-H "Content-Type: application/hal+json" \
-H "Accept-Version: 3.0" \
'https://api.reverb.com/api/my/refund_requests/selling?state[]=approved&state[]=conditionally_approved'
curl \
-XGET \
-H "Authorization: Bearer [oauth_token]" \
-H "Content-Type: application/hal+json" \
-H "Accept-Version: 3.0" \
https://api.reverb.com/api/my/refund_requests/selling?page=1&per_page=1
The response format includes a list of refund requests and its associated order:
{
"total":2,
"current_page":1,
"per_page":1,
"total_pages":2,
"_links":{
"next":{
"href":"https://api.reverb.com/api/my/refund_requests/selling?page=2&per_page=1&state=conditionally_approved"
}
},
"refund_requests":[
{
"id":47,
"state":"conditionally_approved",
"amount":{
"amount":"87.00",
"amount_cents":8700,
"currency":"USD",
"symbol":"$",
"display":"$87"
},
"refund_type":"full",
"reason":"buyer_return",
"initiated_by":"buyer",
"note_to_buyer":"",
"created_at":"2017-05-12T09:56:03-05:00",
"updated_at":"2017-05-12T09:56:03-05:00",
"order":{
"buyer_id":"1651",
"order_number":"290",
"paid_at":"2017-05-12T09:54:25-05:00",
"quantity":1,
"shipping_address":{
"region":"IL",
"locality":"Chicago",
"country_code":"US",
"display_location":"Chicago, IL, United States"
},
"shipping_date":"2017-05-12",
"shipped_at":"2017-05-12T09:55:15-05:00",
"shipping_provider":"USPS",
"shipping_code":"9410836897846109604096",
"shipping_method":"shipped",
"local_pickup":false,
"status":"shipped",
"product_id":"637",
"order_bundle_id":"162",
"created_at":"2017-05-12T09:54:23-05:00",
"amount_product":{
"amount":"77.00",
"amount_cents":7700,
"currency":"USD",
"symbol":"$",
"display":"$77"
},
"amount_product_subtotal":{
"amount":"77.00",
"amount_cents":7700,
"currency":"USD",
"symbol":"$",
"display":"$77"
},
"shipping":{
"amount":"10.00",
"amount_cents":1000,
"currency":"USD",
"symbol":"$",
"display":"$10"
},
"amount_tax":{
"amount":"0.00",
"amount_cents":0,
"currency":"USD",
"symbol":"$",
"display":"FREE"
},
"total":{
"amount":"87.00",
"amount_cents":8700,
"currency":"USD",
"symbol":"$",
"display":"$87"
},
"fully_refundable_amount":{
"amount":"87.00",
"amount_cents":8700,
"currency":"USD",
"symbol":"$",
"display":"$87"
}
},
"_links":{
"self":{
"href":"https://api.reverb.com/api/my/refund_requests/selling/47"
}
}
}
]
}
Responding to Buyer-Initiated Refund Requests
Conditionally approving a refund, including a note to the buyer:
curl \
-XPUT \
-H "Authorization: Bearer [token]" \
-H "Content-Type: application/hal+json" \
-H "Accept-Version: 3.0" \
-d '{"state":"conditionally_approved","note_to_buyer":"hello"}' \
https://api.reverb.com/api/my/refund_requests/selling/[Refund Request ID]
Approving a refund:
curl \
-XPUT \
-H "Authorization: Bearer [token]" \
-H "Content-Type: application/hal+json" \
-H "Accept-Version: 3.0" \
-d '{"state":"approved"}' \
https://api.reverb.com/api/my/refund_requests/selling/[Refund Request ID]
Denying a refund:
curl \
-XPUT \
-H "Authorization: Bearer [token]" \
-H "Content-Type: application/hal+json" \
-H "Accept-Version: 3.0" \
-d '{"state":"denied"}' \
https://api.reverb.com/api/my/refund_requests/selling/[Refund Request ID]
Creating a Seller-Initiated Refund Request
curl \
-XPOST \
-H "Authorization: Bearer [token]" \
-H "Content-Type: application/hal+json" \
-H "Accept-Version: 3.0" \
-d '{"state":"conditionally_approved","reason":"buyer_no_like","refund_amount":{"amount":"10.00","currency":"USD"}}' \
https://api.reverb.com/api/my/orders/selling/[Order Number]/refund_requests
The reason
parameter is required and must be one of the following values:
buyer_return
lost_shipment
shipping_damage
sold_elsewhere
accidental_order
change_shipping_address
Updated 6 months ago