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