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

Build an E-Commerce Sync Integration

This document is designed to teach you the basics of building an integration with a third party E-Commerce platform. It is based on Reverb’s own plugins built for Shopify, Bigcommerce, and Magento.

There are typically two types of sync implementations:

  1. Those that run as a standalone application and are hosted outside of the customer’s purview. For example, Bigcommerce and Shopify apps are standalone apps. These apps are difficult to write because they must handle large volumes of data from multiple Reverb shops at the same time. However these apps are the easiest to maintain, since the developer has full control on updating them, getting insight into errors, etc.
  2. Plugin-based apps such as Magento, where the customer is self-hosting his e-
    commerce platform. These apps are only concerned with syncing one customer’s data at a time, and are thus simpler conceptually and from a scalability standpoint. However, it becomes much harder for developers of these apps to gain insight into errors customers are having, or to get customers to update such apps. Some type of self-update and debugging capabilities are highly recommended for customer- hosted plugins.

Before you begin

The seller must have a fully functional account set up on Reverb with billing information already entered and at least one live listing (we require people to do a manual listing prior to integrating). If this is not true, API will return error codes and the app should be able to direct seller to Reverb to finish his billing profile.

To set up billing on your sandbox account, use this fake credit card data Card number: 4111111111111111, Exp: 01/20, CVV: 123. If we create a sandbox account for you, this will already be done.

SKU Requirement: The seller is required to have SKU identifiers for all their listings on their platform as well as Reverb if they are using sync. If the seller already has listings on Reverb that do not have a SKU, listings from the platform may appear to duplicate when uploaded.

We've broken up the project into pieces based on our experience in delivering plugins for our customers. You may want to build or all of these as part of your plugin.

Configuration and authentication

Plugin configuration screen:

  • Please see How should I authenticate? and Apps for multiple users to learn about the authentication system.
  • Allows for setting up global default settings:
    • Auto-Sync - This setting enables or disables the automatic syncing upon
      saving
    • Auto-Publish - This setting determines whether we will pass "publish=true"
      in the POST request (see Phase 2)
  • Allows for setting up per-field sync settings. This is not a requirement but many customers want to sync only title but not price, or price and inventory but not description, etc.

Sync inventory changes to Reverb

Assumption: Seller already has SKUs imported to reverb using Reverb’s CSV import or manual entry

When an item is updated on the platform, we should first try to find the same listing on Reverb, using the SKU:

curl -H "Accept-Version: 2.0" -H "Content-Type: application/hal+json" https://api.reverb.com/api/my/listings?sku=[sku]&state=all

Make sure you include the state=all param, or you will see only live listings by default, so you will not be able to sync changes to drafts.

If an item is found, read its link from _links.self.href in the response. Send a PUT to that link using the Listing Create/Update API

If the item is not found, do nothing (for now). We will discuss creating new listings in the next section.

Things that should be treated as updates:

  • User updating the product inventory field directly
  • New order for the item (which would result in an inventory decrement)
  • Refund for an order (which would result in an inventory increment)

Build a sync log

After an item syncs, log the sync failure or success in the local database of your app and provide a screen to view it. (A screenshot of the same implementation for Shopify is at the bottom of this document.)

The sync screen should provide:

  • Item id / link to item on platform
  • Item SKU
  • Link to item on Reverb (if it's been synced)
  • Sync status (success/failure)
  • If failed, Sync message (from reverb_response["message"]
  • If failed, Sync error details (from reverb_response["errors"]) - this will be an array of hashes
  • Date of last sync attempt

This screen should be sorted by date first and should be paginated. Ideally it has ajax pagination but if that adds complexity, it's not a requirement.

Notes on Reverb behavior during syncing:

  • If a listing inventory goes to 0, the item will automatically be ended
  • If listing goes above 0, item will automatically be relisted
  • Listings cannot be deleted, except for drafts

Create new listings on Reverb

When a new item is posted on the platform:

  1. Look up listing in Reverb by SKU (same as Phase 1 update)
  2. If listing exists, just like update, grab the link and issue a PUT
  3. If listing does not exist, issue a POST

The plugin should set publish=false so that listings are saved on Reverb as Drafts by default. This setting can be overridden in the global settings screen.

You should provide make and model field if possible. If you don't provide them, they will be guessed from the title, but this is error prone.

For a full list of fields and explanations, please see Create and Update Listings

Mass sync all listings

Create a button to sync all listings

For initial sync or full resync, initiate batch syncing of listings. This should be done as a background job and its status reported to users on the plugin's page.

Please be advised that mass syncs should be discouraged as they are taxing on Reverb’s system. The plugin should do everything to prevent a user from launching multiple mass syncs at the same time. Your plugin may be rate-limited if a large amount of traffic is detected. Because of this, it's recommended that you build a queuing system that allows syncs to execute slowly over time.

Rate Limiting and Terms of Service

Sync inventory changes from Reverb

You may register for webhooks to know when Reverb inventory changes. Learn more about webhooks here. You are encouraged to register at minimum for product/updated and order/created webhooks.

Receive updates with webhooks

Sync orders from Reverb

Many sellers do not need Reverb orders in their other ecommerce platforms as it only confuses things. However, if this is the case, you can either use webhooks or periodic fetch to get orders from Reverb:

Retrieve/sync orders

Webhooks are more reliable will result in fewer headaches when a fetch fails and misses some orders.

Please keep in mind that if order sync is implemented, there are many other order “lifecycle” things that the seller needs to still do manually on Reverb. For example, purchasing shipping labels or entering tracking info, dealing with refund requests and approvals, etc. For this reason we do not recommend implementing order sync to external platforms.

Sync shipment/tracking info to Reverb

If order sync is implemented, it is highly recommended to also implement a way for customers to enter tracking info to sync back to Reverb. If customers are processing orders using their own shipping systems like ShipStation, it may also be good to have a look at our integration options there.

To post back shipping info, use the ship endpoint

Links to existing apps

You can see some of our existing integration apps at the bottom of the app store

Screenshots from Shopify Integration



Build an E-Commerce Sync Integration