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

Create and Update Listings

To create a listing, submit a request like this:

curl -XPOST -H "Authorization: Bearer [oauth_token]" -H "Accept-Version: 3.0" -H "Content-Type: application/hal+json" --data '
    "make": "Fender",
    "model": "Stratocaster",
    "categories": [{
        "uuid": "get these values from /api/categories/flat"
    "condition": {
        "uuid": "get these from /api/listing_conditions"
    "photos": [
    "description": "Awesome guitar",
    "finish": "Sunburst",
    "price": {
        "amount": "5000.00",
        "currency": "USD"
    "title": "my favorite fender stratocaster",
    "year": "1960s",
    "sku": "12345",
    "upc": "885978110803", //this string value can also be an EAN
    "upc_does_not_apply": "false", //Use 'true' in cases where the item does not come with a UPC
    "has_inventory": true,
    "inventory": 5,
  "offers_enabled": true, // can be either true or false
    "handmade": true,
    "exclusive_channel": "none", // for Reverb Sites customers only. Set to   "seller_site", "reverb", or "none" or leave blank
    "shipping_profile_id": 123, // instead of shipping rates
    "shipping": { // only use this if not using shipping profiles
        "rates": [{
                "rate": {
                    "amount": "10.00",
                    "currency": "USD"
                "region_code": "US_CON" // Continental US
                "rate": {
                    "amount": "20.00",
                    "currency": "USD"
                "region_code": "XX" // Everywhere Else
        "local": true

Please note that this is intended to create a draft on your live Reverb account - creating a draft in your sandbox would entail using the endpoint.

Make, model, finish, year, etc...

  • Reverb requires Make and Model to save a product draft
  • Reverb provides a Make and Model guesser - if you do not specify these fields, we will try to extract the fields from the title.
  • You are strongly encouraged to send structured make/model fields when they are available.
  • During sync, if Reverb cannot guess make & model, it will set the make/model to "Unknown" and the listing cannot be published
  • The year field takes fuzzy language incuding ranges, like "1980s" or "1979-1981", "mid 80s" or exact years like "1959"
    *You can enable offers by passing true into the "offers_enabled" parameter. This is especially important for sellers that have MAP restrictions on certain instruments.

Shipping Profiles and Shipping Rates

Reverb provides two options to set shipping rates.

  1. Seller can set up Shipping Profiles on Reverb - specifying a default matrix of Rates
    on a per-category basis, or reference the shipping profile on a per listing basis using shipping_profile_id
  2. Seller can send individual rates with each listing (strongly discouraged) by using the shipping_rates field. You may obtain a full list of regions from the regions api (

You are strongly encouraged to set up Shipping Profiles on Reverb and reference those by id shipping_profile_id instead of specifying rates for every listing. This is more manageable, and you can even set up Reverb to automatically assign your shipping profiles to listings based on their category.

You can get a list of shipping profiles from the /api/shop endpoint (example below)

You can set up shipping profiles here.

curl -X GET -H 'Accept-Version: 3.0' -H 'Authorization: Bearer [oauth_token]' -H 'Content-Type: application/hal+json'
    "description": "This shop is amazing",
    "name": "The Gear Barn",
    "id": "123",
    "shipping_profiles": [
            "name": "Test Profile",
            "id": "456"


Reverb categories should be retrieved at (

You may submit up to two subcategories or one root category and two subcategories by submitting data to the category_uuids field as an array of uuids retrieved from the API above.

curl -X GET -H 'Accept-Version: 3.0' -H 'Content-Type: application/hal+json'


Non functioningfbf35668-96a0-4baa-bcde-ab18d6b1b329
Very Goodae4d9114-1bd7-4ec5-a4ba-6653af5ac84d
Like New9225283f-60c2-4413-ad18-1f5eba7a856f
Brand New7c3f45de-2ae0-4c81-8400-fdb6b1d74890


The location object can be used to set the address for your shop. Note that this only works for your first listing and cannot be used to update your shop address. See the shop API if you want to update your shop address.


There are two flags that must be set:

  • has_inventory = true
  • inventory = [n]

For most cases, we should be using has_inventory=true for sellers who are selling retail items that have inventory. If you are selling a unique item, you can set has_inventory=false and the inventory field will be ignored. If you specify inventory=0 for any item, regardless of whether it supports inventory, this will end the listing. The following are some inventory cases you can use for reference:

ExcellentYes0Will show as draft with inventory 0 until we add inventory to 1 or more, then will go live
ExcellentYes1Will show live with inventory 1. Will be sold after it sells. Will relist after additional inventory is added
B-Stock (has_inventory parameter = true)Yes0Will show as draft with inventory 0 until we add inventory to 1 or more, then will go live
B-Stock (has_inventory parameter = true)No0Will show as draft with inventory 0 and stay draft if inventory is added

Finding your listings

In order to get the link to update one of your listings, first find it by SKU:

curl -H "Authorization: Bearer [oauth_token]" -H "Accept-Version: 3.0" -H "Content-Type: application/hal+json"[sku]&state=all

Please note the use of the state=all filter, which enables you to find drafts. By default, the search will only find live listings.


Pricing involves pushing an amount and currency parameter, such as:
"price": {
"amount": "5000.00",
"currency": "USD"

To update a listing

Updating a listing takes the same parameters as the create, but uses a PUT request.

curl -XPUT -H "Authorization: Bearer [oauth_token]" -H "Accept-Version: 3.0" -H "Content-Type: application/hal+json"[id] --data "..."

Image Updating

In order to override existing images, you can use the following PUT request to swap existing image URLs (do note that the image URLs have to be the exact original URLs you originally uploaded to Reverb):

curl -X PUT \ \
  -H 'Accept-Version: 3.0' \
  -H 'Authorization: Bearer [oauth_token]' \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: df652f61-e982-4e2e-8d9a-fbef9003acf9' \
  -H 'cache-control: no-cache' \
  -d '{
  "photos": [
  "photo_upload_method": "override_position"

The example above would swap the second image with the third, changing the image order from Image 1, Image 2, Image 3, to Image 1, Image 3, Image 2.

To add images to a listing, you would send a PUT request with the new image URLs you wish to add.

In order to delete an image, you would use a DELETE request with the following endpoint, substituting your listing ID and the image ID:{listing_id}/images/{image_id}

To find Image IDs, they can be called upon with a GET request and will be displayed in the JSON with IDs as shown below:[listing_id]/images/

... "id": 87485553,
            "url": ",t_supersize/v1594674306/mjxfct2ffn6oicsn8arm.png",...

Updated 24 days ago

Create and Update Listings

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.