{"_id":"55fdb124b652110d00758b70","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":18,"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..."},"parentDoc":null,"user":"556cbb50c14029190092d20f","updates":["58078bf66d47320f007a2fde"],"next":{"pages":[],"description":""},"createdAt":"2015-09-19T19:01:56.554Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":"/listings"},"isReference":true,"order":1,"body":"To create a listing, submit a request like this: The full list of params is available in [the swagger documentation.](https://reverb.com/swagger#!/listings/POST_listings_format_post_0) \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -XPOST -H \\\"Authorization: Bearer [oauth_token]\\\" -H \\\"Accept-Version: 3.0\\\" -H \\\"Content-Type: application/hal+json\\\" https://api.reverb.com/api/listings --data '\\n{\\n  \\\"make\\\": \\\"Fender\\\",\\n  \\\"model\\\": \\\"Stratocaster\\\",\\n  \\\"categories\\\": [{\\n    \\\"uuid\\\": \\\"get these values from /api/categories/flat\\\"\\n  }],\\n  \\\"condition\\\": {\\n    \\\"uuid\\\": \\\"get these from /api/listing_conditions\\n  },\\n  \\\"photos\\\": [\\n    \\\"http://i.stack.imgur.com/Sv4BC.png\\\"\\n  ],\\n  \\\"description\\\": \\\"Awesome guitar\\\",\\n  \\\"finish\\\": \\\"Sunburst\\\",\\n  \\\"price\\\": {\\n    \\\"amount\\\": \\\"5000.00\\\",\\n    \\\"currency\\\": \\\"USD\\n  },\\n  \\\"title\\\": \\\"my favorite fender stratocaster\\\",\\n  \\\"year\\\": \\\"1960s\\\",\\n  \\\"sku\\\": \\\"12345\\\",\\n  \\\"has_inventory\\\": true,\\n  \\\"inventory\\\": 5,\\n  \\\"handmade\\\": true,\\n  \\\"location\\\": { // will default to shop address if not passed in\\n    \\\"country_code\\\": \\\"USA\\\",\\n    \\\"region\\\": \\\"IL\\\",\\n    \\\"locality\\\": \\\"Chicago\\\"\\n  },\\n  \\\"shipping_profile_id\\\": 123, // instead of shipping rates\\n  \\\"shipping\\\": { // only use this if not using shipping profiles\\n    \\\"rates\\\": [\\n      {\\n        \\\"rate\\\": {\\n          \\\"amount\\\":\\\"10.00\\\"\\n          \\\"currency\\\": \\\"USD\\\"\\n        }, \\n        \\\"region_code\\\": \\\"US_CON\\\" // Continental US\\n      },\\n      {\\n        \\\"rate\\\": {\\n          \\\"amount\\\":\\\"20.00\\\"\\n          \\\"currency\\\": \\\"USD\\\"\\n        }\\\", //USD\\n        \\\"region_code\\\": \\\"XX\\\" // Everywhere Else\\n      },\\n    ]\\n    \\\"local\\\": true\\n  }  \\n}\\n'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Make, model, finish, year, etc...\"\n}\n[/block]\n* Reverb requires Make and Model to save a product draft\n* Reverb provides a Make and Model guesser - if you do not specify these fields, we will try to extract the fields from the title. \n* You are strongly encouraged to send structured make/model fields when they are available.\n* During sync, if Reverb cannot guess make & model, it will set the make/model to \"Unknown\"\n* The `year` field takes fuzzy language incuding ranges, like \"1980s\" or \"1979-1981\", \"mid 80s\" or exact years like \"1959\"\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Shipping Profiles and Shipping Rates\"\n}\n[/block]\nReverb provides two options to set shipping rates.\n1. Seller can set up Shipping Profiles on Reverb - specifying a default matrix of Rates\non a per-category basis, or reference the shipping profile on a per listing basis using `shipping_profile_name` or `shipping_profile_id`\n2. 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 (https://reverb.com/api/shipping/regions).\n\nYou are strongly encouraged to set up Shipping Profiles on Reverb and reference those by name `shipping_profile_name` or 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.\n\nYou can get a list of shipping profiles from the `/api/shop` endpoint\n\nYou can [set up shipping profiles here](https://reverb.com/my/selling/shipping_rates).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Categories\"\n}\n[/block]\nReverb categories should be retrieved at (https://reverb.com/api/categories/flat).\n\nYou 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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Condition\"\n}\n[/block]\nHere is the list of supported values for `condition`.\n\n* Non functioning\n* Poor\n* Fair\n* Good\n* Very good\n* Excellent\n* Mint\n* Like New\n* Brand New\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Location\"\n}\n[/block]\nThe `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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Inventory\"\n}\n[/block]\nThere are two flags that must be set:\n* `has_inventory` = true\n* `inventory` = [n]\n\n\fFor 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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Finding your listings\"\n}\n[/block]\nIn order to get the link to update one of your listings, first find it by SKU:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: Bearer [oauth_token]\\\" -H \\\"Accept-Version: 3.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]\nPlease note the use of the `state=all` filter, which enables you to find drafts. By default, the search will only find live listings.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"To update a listing\"\n}\n[/block]\nUpdating a listing takes the same parameters as the create, but uses a PUT request. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -XPUT -H \\\"Authorization: Bearer [oauth_token]\\\" -H \\\"Accept-Version: 3.0\\\" -H \\\"Content-Type: application/hal+json\\\" https://api.reverb.com/api/listings/[id] --data \\\"...\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"create-a-listing","type":"basic","title":"Create and Update Listings"}

Create and Update Listings


To create a listing, submit a request like this: The full list of params is available in [the swagger documentation.](https://reverb.com/swagger#!/listings/POST_listings_format_post_0) [block:code] { "codes": [ { "code": "curl -XPOST -H \"Authorization: Bearer [oauth_token]\" -H \"Accept-Version: 3.0\" -H \"Content-Type: application/hal+json\" https://api.reverb.com/api/listings --data '\n{\n \"make\": \"Fender\",\n \"model\": \"Stratocaster\",\n \"categories\": [{\n \"uuid\": \"get these values from /api/categories/flat\"\n }],\n \"condition\": {\n \"uuid\": \"get these from /api/listing_conditions\n },\n \"photos\": [\n \"http://i.stack.imgur.com/Sv4BC.png\"\n ],\n \"description\": \"Awesome guitar\",\n \"finish\": \"Sunburst\",\n \"price\": {\n \"amount\": \"5000.00\",\n \"currency\": \"USD\n },\n \"title\": \"my favorite fender stratocaster\",\n \"year\": \"1960s\",\n \"sku\": \"12345\",\n \"has_inventory\": true,\n \"inventory\": 5,\n \"handmade\": true,\n \"location\": { // will default to shop address if not passed in\n \"country_code\": \"USA\",\n \"region\": \"IL\",\n \"locality\": \"Chicago\"\n },\n \"shipping_profile_id\": 123, // instead of shipping rates\n \"shipping\": { // only use this if not using shipping profiles\n \"rates\": [\n {\n \"rate\": {\n \"amount\":\"10.00\"\n \"currency\": \"USD\"\n }, \n \"region_code\": \"US_CON\" // Continental US\n },\n {\n \"rate\": {\n \"amount\":\"20.00\"\n \"currency\": \"USD\"\n }\", //USD\n \"region_code\": \"XX\" // Everywhere Else\n },\n ]\n \"local\": true\n } \n}\n'", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Make, model, finish, year, etc..." } [/block] * 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" * The `year` field takes fuzzy language incuding ranges, like "1980s" or "1979-1981", "mid 80s" or exact years like "1959" [block:api-header] { "type": "basic", "title": "Shipping Profiles and Shipping Rates" } [/block] 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_name` or `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 (https://reverb.com/api/shipping/regions). You are strongly encouraged to set up Shipping Profiles on Reverb and reference those by name `shipping_profile_name` or 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 You can [set up shipping profiles here](https://reverb.com/my/selling/shipping_rates). [block:api-header] { "type": "basic", "title": "Categories" } [/block] Reverb categories should be retrieved at (https://reverb.com/api/categories/flat). 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. [block:api-header] { "type": "basic", "title": "Condition" } [/block] Here is the list of supported values for `condition`. * Non functioning * Poor * Fair * Good * Very good * Excellent * Mint * Like New * Brand New [block:api-header] { "type": "basic", "title": "Location" } [/block] 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. [block:api-header] { "type": "basic", "title": "Inventory" } [/block] 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. [block:api-header] { "type": "basic", "title": "Finding your listings" } [/block] In order to get the link to update one of your listings, first find it by SKU: [block:code] { "codes": [ { "code": "curl -H \"Authorization: Bearer [oauth_token]\" -H \"Accept-Version: 3.0\" -H \"Content-Type: application/hal+json\" https://api.reverb.com/api/my/listings?sku=[sku]&state=all", "language": "curl" } ] } [/block] Please note the use of the `state=all` filter, which enables you to find drafts. By default, the search will only find live listings. [block:api-header] { "type": "basic", "title": "To update a listing" } [/block] Updating a listing takes the same parameters as the create, but uses a PUT request. [block:code] { "codes": [ { "code": "curl -XPUT -H \"Authorization: Bearer [oauth_token]\" -H \"Accept-Version: 3.0\" -H \"Content-Type: application/hal+json\" https://api.reverb.com/api/listings/[id] --data \"...\"", "language": "curl" } ] } [/block]