Guides & Tutorials

Manage Refund Requests

Suggest Edits

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.

Filter by Create Date Range

curl -XGET 
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"
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

Filter by Update Date Range

curl -XGET 
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"
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

Filter by Refund State

curl -XGET 
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"
https://api.reverb.com/api/my/refund_requests/selling?state[]=approved&state[]=conditionally_approved

curl -XGET 
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"
https://api.reverb.com/api/my/refund_requests/selling?state=approved

Filter by Order Number

curl -XGET 
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"
https://api.reverb.com/api/my/refund_requests/selling?order_number=123

Paginate through Refund Request responses

curl -XGET 
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"
https://api.reverb.com/api/my/refund_requests/selling?page=1&per_page=1

Response Example

The response format includes a list of refund requests and its associated orders:

{  
   "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

How to conditionally approve a refund, including a note to the buyer:

curl -XPUT 
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"
https://api.reverb.com/api/my/refund_requests/selling/[refund_request_id]
-d '{
"state":"conditionally_approved",
"note_to_buyer":"hello"
}' \

How to approve a refund:

curl -XPUT 
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"
https://api.reverb.com/api/my/refund_requests/selling/[refund_request_id]
-d '{
"state":"approved"
}' \

How to deny a refund:

curl -XPUT 
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"
https://api.reverb.com/api/my/refund_requests/selling/[refund_request_id]
-d '{
"state":"denied"
}' \

Creating a Seller-Initiated Refund Request

curl -XPOST 
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"
https://api.reverb.com/api/my/orders/selling/[order_number]/refund_requests
-d '{
"state":"conditionally_approved",
"reason":"sold_elsewhere",
"refund_amount":{"amount":"10.00","currency":"USD"}
}' \

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
  • shipping_adjustments

Updated 4 months ago