Reverb

Welcome to the Reverb API

Welcome to the Reverb developer hub. You'll find comprehensive guides and documentation to help you start working with Reverb as quickly as possible, as well as support if you get stuck.

Get Started

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:

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?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?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?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?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?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?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/1

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/1

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/1

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/1/refund_requests

The reason parameter is required and must be one of the following values:

  • buyer_change_of_heart
  • buyer_no_like
  • buyer_return
  • lost_shipment
  • shipping_damage
  • sold_elsewhere
  • item_defective
  • other