{"_id":"56aac68aac665d0d00af76b0","project":"556cd8aec14029190092d292","version":{"_id":"556cd8aec14029190092d295","__v":14,"project":"556cd8aec14029190092d292","createdAt":"2015-06-01T22:11:58.756Z","releaseDate":"2015-06-01T22:11:58.756Z","categories":["556cd8afc14029190092d296","55ca5a55241e790d004f47ea","55dc9fdb4f535537007da1b2","55dc9fdfc755b63700dc843c","55fdb08c4bebdf17004130d4","560ef4c2a36c610d00e7013e","5613db296a092921004c30c2","56156581dc8aea0d002475e8","56169d1ee98f5517005627a8","5622fde7de7dc01700c6dd5f","56cf75f3336aa60b0086a495","5818f3c02093901b00bcf91a","582f7ff88ea0800f0035639a","583f30c110448a2500dd990f"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":27,"parentDoc":null,"user":"556cbb50c14029190092d20f","category":{"_id":"55fdb08c4bebdf17004130d4","project":"556cd8aec14029190092d292","version":"556cd8aec14029190092d295","__v":11,"pages":["55fdb124b652110d00758b70","55fdb2a956d6990d00a6caca","55fdb38856d6990d00a6cacc","55ff6c519e7ccf0d000a1d7f","5613db97acd4343500088079","5616d7b9cf2a1e0d00247971","56196204fa2a6d0d002a1352","5622f2c906481c0d00e5315c","569526b8caa32519009c411e","569fbbcbbeb79a17009f8f89","56aac68aac665d0d00af76b0"],"sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-09-19T18:59:24.105Z","from_sync":false,"order":4,"slug":"how-to","title":"How To..."},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-29T01:55:22.911Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":0,"body":"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.\n\nThere are typically two types of sync implementations:\n\n1. 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.\n2. Plugin-based apps such as Magento, where the customer is self-hosting his e-\ncommerce 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. \n\n# Before you begin\n\nThe 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.\n\nTo 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](doc:sandbox) for you, this will already be done.\n\n\fSKU 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.\n\nWe'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.\n\n# Configuration and authentication\n\nPlugin configuration screen:\n* Please see [How should I authenticate?](doc:how-should-i-authenticate) and [Apps for multiple users](doc:build-a-multi-user-app-with-oauth) to learn about the authentication system.\n* Allows for setting up global default settings:\n  * Auto-Sync - This setting enables or disables the automatic syncing upon\nsaving\n  * Auto-Publish - This setting determines whether we will pass \"publish=true\"\nin the POST request (see Phase 2)\n* 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.\n\n# Sync inventory changes to Reverb\n\n\fAssumption: Seller already has SKUs imported to reverb using Reverb’s CSV import or manual entry\n\nWhen an item is updated on the platform, we should first try to find the same listing on Reverb, using the SKU:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Accept-Version: 2.0\\\" -H \\\"Content-Type: application/hal+json\\\" https://api.reverb.com/api/my/listings?sku=[sku]&state=all\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nMake 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.\n\nIf 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](doc:create-a-listing) \n\nIf the item is not found, do nothing (for now). We will discuss creating new listings in the next section.\n\nThings that should be treated as updates:\n * User updating the product inventory field directly\n * New order for the item (which would result in an inventory decrement)\n * Refund for an order (which would result in an inventory increment)\n\n\n# Build a sync log\n\nAfter 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.)\n\nThe sync screen should provide:\n* Item id / link to item on platform\n* Item SKU\n* Link to item on Reverb (if it's been synced)\n* Sync status (success/failure)\n* If failed, Sync message (from reverb_response[\"message\"]\n* If failed, Sync error details (from reverb_response[\"errors\"]) - this will be an array of hashes\n* Date of last sync attempt\n\nThis 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.\n\n**\fNotes on Reverb behavior during syncing:**\n* If a listing inventory goes to 0, the item will automatically be ended\n* If listing goes above 0, item will automatically be relisted\n* Listings cannot be deleted, except for drafts\n\n\n# Create new listings on Reverb\n\n**When a new item is posted on the platform:**\n1. Look up listing in Reverb by SKU (same as Phase 1 update) \n2. If listing exists, just like update, grab the link and issue a PUT \n3. If listing does not exist, issue a POST\n\nThe 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.\n\nYou _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.\n\nFor a full list of fields and explanations, please see [Create and Update Listings](doc:create-a-listing) \n\n\n# Mass sync all listings\n\n**Create a button to sync all listings **\n\nFor 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.\n\nPlease 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.\n\n[Rate Limiting and Terms of Service](doc:rate-limiting-and-terms-of-service) \n\n\n# Sync inventory changes from Reverb\n\nYou 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.\n\n[Receive updates with webhooks](doc:receive-updates-with-webhooks) \n\n\n# Sync orders from Reverb\n\nMany 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:  \n\n[Retrieve/sync orders](doc:syncing-orders) \n\nWebhooks are more reliable will result in fewer headaches when a fetch fails and misses some orders.\n\nPlease 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.\n\n# Sync shipment/tracking info to Reverb\n\nIf 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.\n\nTo post back shipping info, use the [ship endpoint](https://reverb.com/swagger#!/my/post_my_orders_selling_id_ship)\n\n# Links to existing apps\n\nYou can see some of our existing integration apps [at the bottom of the app store](https://reverb.com/apps)\n\n# Screenshots from Shopify Integration\n![](\f\fhttp://i.imgur.com/wFMv0rN.png)\n![](\f\fhttp://i.imgur.com/5ZQ3avk.png)\n![](\f\fhttp://i.imgur.com/NEXl3tR.png)","excerpt":"","slug":"build-an-e-commerce-sync-integration","type":"basic","title":"Build an E-Commerce Sync Integration"}

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](doc:sandbox) 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?](doc:how-should-i-authenticate) and [Apps for multiple users](doc:build-a-multi-user-app-with-oauth) 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: [block:code] { "codes": [ { "code": "curl -H \"Accept-Version: 2.0\" -H \"Content-Type: application/hal+json\" https://api.reverb.com/api/my/listings?sku=[sku]&state=all", "language": "curl" } ] } [/block] 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](doc:create-a-listing) 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](doc:create-a-listing) # 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](doc: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](doc: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](doc:syncing-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](https://reverb.com/swagger#!/my/post_my_orders_selling_id_ship) # Links to existing apps You can see some of our existing integration apps [at the bottom of the app store](https://reverb.com/apps) # Screenshots from Shopify Integration ![]( http://i.imgur.com/wFMv0rN.png) ![]( http://i.imgur.com/5ZQ3avk.png) ![]( http://i.imgur.com/NEXl3tR.png)