Build an E-Commerce Sync Integration

Introduction

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, you can use 4111 1111 1111 1111 for the card number, 03/2030 for expiration, 737 for the CVC, and 60657 for the zip code.

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 some or all of these as part of your plugin.

Configuration and authentication

Plugin configuration screen:

  • Please see Create a Personal Token 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: 3.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 third-party 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 and time 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 in the conditions Brand New, B-Stock or Mint (with inventory) that was previously sold goes above 0, item will automatically be relisted
  • Only conditions Brand New, B-Stock and Mint (with inventory) can have an inventory number higher than 1. These conditions can be relisted after they sell out. Anything below, such as Excellent or Good, etc...is considered to be a Used one of a kind item that requires its own pictures to show its particular blemishes or modifications. Because of this, the system only allows a quantity of 1. Once that 1 piece is sold, the listing is locked in an Ordered status, since there are not 2 Used items that are the same. Therefore, these can't be relisted once ordered. If you have more than 1 of the same item in a used condition, these should be individual listings on Reverb, each with its own pictures.
  • Listings previously published cannot be deleted from your account. Drafts can be deleted.

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 should be able to 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.

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

Inventory changes can be accessed through the /listings endpoints.

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 periodically fetch to get orders from Reverb:

Retrieve/sync 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, such as purchasing Reverb shipping labels, for example. Please make sure that every step of the order fulfillment process is accounted for in your workflow.

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 the third-party integration options there.

Links to existing apps

You can see Reverb-built and third-party integrations here

Screenshots from Shopify Integration