Create Listings

Create a Listing

To create a listing, submit a request like this:

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/listings 
-d '{
    "make": "Fender",
    "model": "Stratocaster",
    "categories": [{
        "uuid": "get these values from /api/categories/flat"
    }],
    "condition": {
        "uuid": "get these from /api/listing_conditions"
    },
    "photos": [
        "http://i.stack.imgur.com/Sv4BC.png",
        "http://i.stack.imgur.com/foo.png"
    ],
   "videos": [{
            "link": "https://www.youtube.com/watch?v=FptlwukVz2w"
  }],
    "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,
    "shipping_profile_id": // enter your shipping profile here instead of shipping rates if applicable
    "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 sandbox.reverb.com/api endpoint. More information about testing on sandbox can be found on Testing on Sandbox.

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 and 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 can obtain a full list of regions with the following request:
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/shipping/regions

You are strongly encouraged to set up Shipping Profiles on Reverb and reference those by id using 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 set up shipping profiles here. You cannot create Shipping Profiles via API or modify the profiles via API. These actions need to be done manually direction on Reverb. You can only assign the profiles to the listings once the profiles have been manually created.

Once you're shipping profiles are created, you can get a list of shipping profiles from the /api/shop endpoint (example below)

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

Response example:

{
    "description": "This shop is amazing",
    "name": "The Gear Barn",
    "id": "123",
    "shipping_profiles": [
        {
            "name": "Test Profile",
            "id": "456"
        }
    ],
}

Categories

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 below:

curl -XGET 
-H 'Accept-Version: 3.0'
-H 'Content-Type: application/hal+json'
https://api.reverb.com/api/categories/flat

Condition

curl -XGET  
-H 'Accept-Version: 3.0' 
-H 'Content-Type: application/hal+json'
https://api.reverb.com/api/listing_conditions

Certain conditions like B-Stock and Mint (with inventory) are only able to be used if your account is enabled for these conditions. To identify which listing conditions you're able to use, use the associated Shop's API token for Authorization and perform the same call above to see a full list of conditions you can use.

NameUUID
Non functioningfbf35668-96a0-4baa-bcde-ab18d6b1b329
Poor6a9dfcad-600b-46c8-9e08-ce6e5057921e
Fair98777886-76d0-44c8-865e-bb40e669e934
Goodf7a3f48c-972a-44c6-b01a-0cd27488d3f6
Very Goodae4d9114-1bd7-4ec5-a4ba-6653af5ac84d
Excellentdf268ad1-c462-4ba6-b6db-e007e23922ea
Mintac5b9c1e-dc78-466d-b0b3-7cf712967a48
Mint (with inventory)6db7df88-293b-4017-a1c1-cdb5e599fa1a
B-Stock9225283f-60c2-4413-ad18-1f5eba7a856f
Brand New7c3f45de-2ae0-4c81-8400-fdb6b1d74890

Location

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. However, we recommend completing the initial general shop setup directly on Reverb.com when you are configuring your shop.

Inventory

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:

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

Price

Pricing involves pushing an amount and currency parameter, such as:

{
"price": {
    "amount": "5000.00",
    "currency": "USD"
  }
}

To see the possible currencies you can use for a listing:

curl -XGET 
https://api.reverb.com/api/currencies/listing
-H "Content-Type: application/hal+json" 
-H "Accept: application/hal+json" 
-H "Accept-Version: 3.0" 
-H "Authorization: Bearer [personal_token]"