{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"964655c9-de32-45ff-ab8d-4e55c047eee7","name":"OnBuy API Documentation v2","description":"The OnBuy API allows external applications to securely communicate with the OnBuy platform. It is based on the [REST architecture](https://en.wikipedia.org/wiki/Representational_state_transfer).\n\nWith it, you can automate many tasks such as creating products, creating & updating listings and exporting orders.\n\n## Getting Started\n\nThe quickest way to get started with the OnBuy API is to click the **Run in Postman** button at the top of this page. All the endpoints documented here are available to run in the OnBuy Postman collection.\n\nPostman is a free tool to help developers run and debug API requests. Visit [https://www.getpostman.com/](https://www.getpostman.com/) to download.\n\n# Settings\n\nThe [API settings page](https://seller.onbuy.com/inventory/integrations/onbuy-api/) can be found in your Seller Control Panel. It details the information you will need in order to connect to the API (e.g. the API URL) and displays your daily usage statistics.\n\n> If you do not have access to this page, please contact the OnBuy Seller Team by creating a ticket. \n  \n\n## Connection Details\n\nThere are two sets of keys, Live and Test. You should use the Test keys when integrating with the API and switch to the Live Keys when you are ready to go live.\n\nData created in test is stored separately in your account. The switch at the top right of your account can be used to switch between live and test data. Test data is currently available for products, listings and orders.\n\n## Going Live\n\nGoing live should be a simple case of switching to use your Live Keys.\n\nFor product creation, you'll be unable to publish live products without first having live product creation enabled on your account. To get your account enabled for live product creation, you should first create the products using your live API keys. The products will then show in your Seller Control Panel under the 'Approve Products' [Approve Products Page](https://seller.onbuy.com/inventory/management/approve-products/) page. You will need to submit a support ticket and request that the OnBuy Support team review the products and approve your account. Once your account is approved you will be able to approve/publish your products to the live site.\n\n## Usage Limits\n\nEach request type (POST, GET, PUT and DELETE) has daily and hourly usage limits. These should be high enough for the requirements of most sellers. If you find you are hitting the limits on a regular basis we may be able to increase them. Please contact the OnBuy Seller Team by creating a ticket.\n\n## Requests\n\nWith each request (with the exception of requestToken) you will need to send the access_token as an Authorization header. See the Auth section below for details of how to obtain the access token.  \nEach endpoint specifies the request method to use. Allowed request methods are POST, GET, PUT, DELETE. As a general rule:\n\n- GET – Used when fetching items.\n    \n- POST – Used when adding items.\n    \n- PUT – Used when updating items.\n    \n- DELETE – Used when removing items.\n    \n\nHow parameters are passed varies depending on the method and endpoint being called. Most POST and PUT requests are sent as JSON.\n\n## Responses\n\nOur API uses standard HTTP response codes to inform users about the status of a request. Responses with 4xx & 5xx codes mostly specify errors related to missing keys, wrong authorisation or missing data, whilst 2xx response codes usually mean the request was successful.\n\n<table><tbody><tr><th>Code</th><th>Message / Error</th></tr><tr><td><div>200</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>OK Success</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>400</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Bad Request Invalid request mostly due to wrong data.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>401</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Unauthorised Missing Secret or Consumer Key, Authentication Failed, Bad Token.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>403</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Forbidden Account does not have permission to the accessed method.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>404</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Not Found The requested resource was not found.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>429</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Too Many Requests Usage limit has been exceeded.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>500</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Internal Server Error Internal error. Please contact us.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr></tbody></table>\n\nNote: Unless otherwise specified, all dates are in UTC.\n\n## Pagination\n\nMost browse methods support pagination. The results returned will contain a MetaData element with the following pagination fields:\n\n- limit – The limit applied to the result set.\n    \n- offset – The limit applied to the result set.\n    \n- total_rows – The total results available.\n    \n\nFilters and Sorting fields sent in the request will also be included in the meta data.  \nDifferent pages of results can be returned by changing the offset sent with the request. Some methods have a maximum limit value.\n\n## Variables\n\nThroughout the documents are a number of variables, shown as {{name}}. These need to be replaced with appropriate values when calling the endpoint. The table below details some of the more common variables and examples of values to include:\n\n<table><tbody><tr><th>Variable</th><th>Example</th></tr><tr><td><div>{{access_token}}</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>This is the access token received when you authenticate with the API</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>{{site_id}}</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>The OnBuy Regional site id e.g. 2000 for the UK</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>{{seller_id}}</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>This is your unique seller ID. You can find this on the API page of the SCP</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>{{entity_id}}</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>This is you unique trading entity ID. You can find this on the API page of the SCP</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>{{category_id}}</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>You can obtain a list of categories by using the `/v2/categories` method</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>{{opc}}</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>A unique code we assign to each product</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr></tbody></table>\n\n# Products\n\nThe OnBuy.com marketplace has a single entry for each product from a manufacturer with potentially multiple sellers listing the same product.\n\nAs a seller you can list an existing product with your own purchasing options or, if the product is not already in the OnBuy system, you can add it yourself giving the full manufacturer's description.\n\n# Creating a Product\n\nThere are two stages to creating a product on OnBuy using the API. The diagrams below highlight the processes involved for each stage.\n\n<img src=\"https://www.onbuy.com/files/external/postman/images/product-create-1.jpg\" alt=\"Product Create process #1\">\n\n<img src=\"https://www.onbuy.com/files/external/postman/images/product-create-2.jpg\" alt=\"Product Create process #2\">\n\n## Stage 1\n\nWe advise using the search function `GET /v2/products` to see if the product exists before trying to create a new one. If the product already exists the create listing method `POST /v2/products/{{onbuy_product_code}}/listings` can be used to add a new listing to it.\n\n> When using test API keys only products created in test are returned from the search and test listings can only be created on test products. \n  \n\nIf the product doesn’t already exist the create product method `POST /v2/products` can be used to add a new product. The product should be submitted as a JSON string.\n\nWe recommend uploading products in batches of up to **1,000 per POST request**. This helps prevent timeout failures and supports consistent, reliable processing.\n\nOn receiving the product OnBuy will validate the supplied data to ensure it meets the criteria needed. If there is anything not right an error will be returned containing details on what needs to be fixed. An error will be returned if any required parameters are missing.\n\nIf the product passes validation it is added to a queue to be created in the system. A queue ID is returned which can be used to check the status of the product creation. Multiple products can be queued for creation.\n\n## Stage 2\n\nThe queues methods `GET /v2/queues` can be used to get the status of the product creation. Multiple queue ID’s can be checked at once.\n\nEach queue has a status. If the status returned is pending then the product is still waiting to be processed. While queued products are normally processed within a few minutes, but at busy times they can take longer. We would suggest polling the queue with batches of ID’s periodically.\n\nOnce the queue has been processed the status will be changed to either Success if the product has been created or failed if there was a problem.\n\nWhen the status is failed an error message will be returned with details of what has failed. While most validation is done before the product is queued some checks can only be done during the save. An example is product images which often take time to download, so we only check the URL is valid initially, but process the images when the product is actually created.\n\nIf the status is success the OPC of the created product will be returned.\n\n## **Image Download Requirements**\n\nTo successfully create products, our media service must be able to download each image directly from the URL you provide in the payload.\n\nThe URLs must be fully accessible over the public internet and must not require authentication, IP allowlisting, expiring signatures or token based access.\n\nA reliable way to confirm this is to open the image URL in a browser. If it loads the image itself with no redirects, login prompts or errors, the file is reachable and should download correctly.\n\nIf our media service's requests to access the images are blocked, it prevents the product from being succesfully created, resulting in errors when the **queue_id** is called, such as:\n\n**Error downloading image** \"[https://cdn.onbuy.com/product/65b27dcc5e50f/990-990/large-dog-bed-in-tan-faux-fur-fleece-easipet.jpg\"](https://cdn.onbuy.com/product/65b27dcc5e50f/990-990/large-dog-bed-in-tan-faux-fur-fleece-easipet.jpg) - Connection to the host URL has been refused\n\nIn many cases, the issue is caused by IP address filtering. To resolve this, please ensure the following IP addresses are allowlisted:\n\n- 34.142.64.77\n    \n- 34.142.18.212\n    \n- 35.246.83.100\n    \n- 34.105.246.78\n    \n\nOther common reasons we see for image related errors are listed below.\n\n- Unsupported image formats are being used. Only JPG, JPEG, PNG and GIF are permitted.\n    \n- Image dimensions or file sizes fall outside the supported limits. We recommend 500 x 500 pixels for best results, with a maximum of 1,000 x 1,000 pixels and a maximum file size of 10MB.\n    \n- The image host is not supported. Imgur is no longer permitted, and any Imgur links will be rejected by the image service. Images should be hosted on your own servers or another publicly accessible provider.\n    \n\n## **Condition Requirements**\n\nOnBuy allows sellers to list items as either new or refurbished, so every product must fall under one of these condition types.\n\nIn most categories, items can be listed as `\"new\"` or `\"refurbished\"`.\n\nExample payload snippet:\n\n``` json\n\"listings\": {\n        \"new\": {\n            \"sku\": \"SKU1\",\n            \"price\": 299.99,\n            \"stock\": 1\n...\n\n ```\n\n``` json\n\"listings\": {\n        \"refurbished\": {\n            \"sku\": \"SKU2\",\n            \"price\": 199.99,\n            \"stock\": 2\n...\n\n ```\n\nIn some categories, a more detailed refurbished grading system is required that reflects the refurbished state of the item.\n\nThe API provides the available_condition_slugs for each category. You should read these directly from the `GET /categories` [endpoint ](https://docs.api.onbuy.com/?version=latest#7dfcc63e-ce64-4e54-ae12-13039d5de94a) and use only the values listed there. This ensures that your product data matches the expected condition format for each category.\n\nFor example, `\"Digital Cameras\"` only allow `\"new\"` or `\"refurbished\"` .\n\n``` json\n\"category_id\": 3251,\n\"name\": \"Digital Cameras\",\n...\n\"available_condition_slugs\": [\n    \"new\",\n    \"refurbished\"\n]\n\n ```\n\nWhereas `\"Laptops\"` requires a range of graded conditions and these must be used instead.\n\n``` json\n\"category_id\": 8345,\n\"name\": \"Laptops\",\n...\n\"available_condition_slugs\": [\n    \"new\",\n    \"diamond\",\n    \"platinum\",\n    \"gold\",\n    \"silver\",\n    \"bronze\"\n]\n\n ```\n\nBy reading the `available_condition_slugs` field for each category, you can ensure that you always submit the correct condition values for your listings.\n\n# Group Products/Variants\n\nWe’ve introduced a standardised way to handle product variants. All variants must be mapped to one of the following 8 fields:\n\nColour - e.g. Black, Blue, Red  \nSize - e.g. Small, Medium, Large, 10 cm  \nMaterial - e.g. Cotton, Plastic, Stainless Steel  \nCapacity - e.g. 500 ml, 1 L, 32 GB  \nStyle - e.g. Modern, Classic, Slim Fit  \nPack Quantity - e.g. Pack of 2, Set of 6  \nLength - e.g. 1 m, 30 cm, 10 ft  \nWidth - e.g. 5 cm, 40 in\n\nIf a variant type cannot be matched to one of these fields, the product will be created as a single item instead of a grouped variant.\n\nWe have an internal matching system that will try to map the submitted variant name to one of the eight supported fields. For example:\n\n```\n\"variant_1\": { \"name\": \"Sizes\" }\n\n ```\n\nThis will be recognised as the Size attribute. The product will then be created with size variants.\n\n**It is important to note that the matching tool is limited.** A name that seems to resemble a supported field does not guarantee a match. For example:\n\n```\n\"variant_1\": { \"name\": \"Shoe Size\" }\n\n ```\n\nEven though this contains the word Size, this exact phrase may not be one of the mappings we have created. In this case, the match may fail and the product would be created as a single item.\n\n**It is best practice to provide an exact match to one of the 8 standard variant names.**\n\nIf you rely on the automatic matching, the variant names must be as closely aligned as possible to these standard fields. This gives the mapping tool the best chance of identifying the correct option, but using the exact standard name is the most reliable way to ensure variants are created and displayed correctly.\n\n# **Stock and Price Handling on Product Create**\n\nThe [Product Create endpoint ](https://docs.api.onbuy.com/?version=latest#3e110bf0-305e-47b7-b3f7-ee27631110e3) `POST /v2/products/` includes a listings object, this enables the creation of a listing at the same time as the product.\n\nListings created through this method will be assigned a default stock value of 0 and a default price value of 0. This happens even when stock and price are supplied in the listings object. These values are not applied during product creation.\n\nThe listing will remain inactive until a separate stock and price update is submitted through the correct [Product Listings: Update by SKU](https://docs.api.onbuy.com/?version=latest#b4a5d9a4-1ab1-4be0-a44c-dea434141bd3) endpoint.\n\nAfter the update is processed, the listing will activate, normally within 30 minutes.\n\n**In summary, product creation can create a listing, but does not activate it. A subsequent stock and price update to the SKU is required to activate the listing.**\n\n# Stock and Price Update Requirements\n\nStock and price updates are required to be sent using the [Product Listings: Update by SKU](https://docs.api.onbuy.com/?version=latest#b4a5d9a4-1ab1-4be0-a44c-dea434141bd3) endpoint only, `PUT /v2/listings/by-sku`.\n\nWe recommend submitting stock and price updates in batches of up to **1,000 SKUs per PUT request**. This helps prevent timeout failures and supports consistent, reliable processing.\n\nRequests sent as `POST /v2/listings/` are for creating new listings only and will not update existing listing data.\n\nRepeated `POST /v2/products/` calls or `PUT /v2/products/` calls are another common error. These endpoints create or update product data, and place requests in a slower processing queue, which does not update listing stock or price.\n\n# API Usage Limit\n\n| Method | Hourly Limit | Daily Limit |\n| --- | --- | --- |\n| GET (Live) | 600 | 12,000 |\n| POST (Live) | 240 | 4,800 |\n| PUT (Live) | 240 | 4,800 |\n| DELETE (Live) | 240 | 4,800 |\n| GET (Test) | 600 | 12,000 |\n| POST (Test) | 240 | 4,800 |\n| PUT (Test) | 240 | 4,800 |\n| DELETE (Test) | 240 | 4,800 |\n\nAPI usage is controlled to maintain platform stability, with limits that vary by request method and environment.\n\nIf these limits are exceeded the API will return a 429 Too Many Requests error and no further requests can be made until the usage window resets.\n\n# Creating Test Products\n\nTest products can only be created via the API, using Test API keys.\n\nTest products follow the same JSON format as live products.\n\nLive and Test share the same database, so any SKU or barcode already used in one cannot be reused in the other.\n\nYou can toggle viewing **Live Account** and **Test Account** mode using the button at the top-right corner of the [Inventory page](https://seller.onbuy.com/gb/inventory/).\n\nStep 1:  \nEnable the OnBuy API via the [OnBuy API Integration page within the SCP](https://seller.onbuy.com/gb/inventory/integrations/onbuy-api/).\n\nStep 2:  \nUse your Test API keys to carry out authentication.\n\nStep 3:  \nCreate a Product using the `POST /v2/products` endpoint using the access_token generated by the Test API keys.\n\nWhen using the `GET /v2/products` Search endpoint, it will search the catalogue based on which keys you are using (Live or Test). For example, if you are using Test API keys, and search a GTIN, it will not check to see if it exists as a Live product. To do this, you'd need to use your Live API keys.\n\n# Creating Test Orders\n\nTest orders can be created via the [OnBuy API Integration page within the SCP](https://seller.onbuy.com/gb/inventory/integrations/onbuy-api/).\n\nSelect \"Create Test Order\" and fill in the fields, then submit. You must use a Test SKU that already exists in your Test Account inventory.\n\n**Unverified seller accounts cannot create test orders.**\n\nIf you are an integration partner and need a test account, please contact our team directly. We can arrange to skip your account through the verification steps so you can carry out API testing.\n\n# Partner Integrations\n\nIf you're a technology business offering order fulfillment, inventory management, or similar solutions to online sellers, [reach out to us](https://www.onbuy.com/gb/sell/?talktoteam=open). You may qualify to have your integration added to our Seller Control Panel.\n\nIf your integration is added, we'll provide you with a unique \"Provider-Token\" to include in the header of each API call.\n\n_Key: Provider-Token__Value: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX_\n\nThis ensures that any seller using the integration has the correct integration enabled in the SCP. We can then lock the integration. If a seller attempts to use API keys obtained for a different integration, but we detect your partner header, we'll return an error: _the integration specified in the header doesn't match the integration defined in the API token._\n\n# International Sites\n\nIf you choose to remain a UK-only seller, you do not need to make any changes. Your current integration will continue to work as it always has.\n\nFor sellers who wish to expand into new locations, there are several changes that will be needed to enable the API in these regions and to send product data to the additional sites.\n\n## Site IDs\n\nSite IDs are unique identifiers for each regional site. For example, OnBuy UK has a Site ID of 2000.\n\nWhen a new international site is enabled, API requests for that site must include the relevant Site ID. For instance, to retrieve orders for a specific location, you will need to make a separate API request with the corresponding Site ID.\n\nPlease note: Cross-country API requests are not currently supported.\n\nAvailable Site IDs will be listed on the [OnBuy API Integration page](https://seller.onbuy.com/inventory/integrations/onbuy-api/) within the Seller Control Panel. You will find them within the table of data that lists API keys.\n\nYou will also be able to retrieve the list of available Site IDs using the [Sites endpoint](https://docs.api.onbuy.com/#81ab6953-4fcf-4605-ba59-de5146636364).\n\nHere is the current list for reference:\n\n| Site ID | Country |\n| --- | --- |\n| 2000 | OnBuy UK |\n| 2001 | OnBuy France |\n| 2002 | OnBuy Germany |\n| 2003 | OnBuy Czech Republic |\n| 2004 | OnBuy Netherlands |\n| 2007 | OnBuy Austria |\n| 2008 | OnBuy Belgium |\n| 2011 | OnBuy Denmark |\n| 2013 | OnBuy Spain |\n| 2014 | OnBuy Finland |\n| 2015 | OnBuy Greece |\n| 2017 | OnBuy Hungary |\n| 2019 | OnBuy Ireland |\n| 2020 | OnBuy Italy |\n| 2026 | OnBuy Norway |\n| 2027 | OnBuy Poland |\n| 2028 | OnBuy Portugal |\n| 2029 | OnBuy Romania |\n| 2030 | OnBuy Sweden |\n| 2031 | OnBuy Switzerland |\n| 2033 | OnBuy Slovakia |\n\n## Seller Entity IDs\n\nSeller Entity IDs are unique identifiers for each seller on OnBuy. Your existing seller account already has a Seller Entity ID for OnBuy UK, and you will receive a new ID for each location you enable.\n\nThese IDs are associated with specific details, including your Trading Name, the particular Site ID, and any other information provided when onboarding the new site.\n\nSeller Entity IDs are listed on the [OnBuy API Integration page](https://seller.onbuy.com/inventory/integrations/onbuy-api/) within the Seller Control Panel. You will find them within the table of data that lists API keys.\n\nA list of all entities for a seller can also be found within the [Seller Entities endpoint](https://docs.api.onbuy.com/#f74202e4-7c18-4a84-810a-4c14c41e4f9f).\n\nThis will include the Entity ID, Site ID and Trading Name of the entity. here:\n\n## **Authentication**\n\nThe OnBuy API does not require sellers to authenticate on a site-by-site basis.\n\nExisting integrations utilising the request token endpoint will authenticate across all enabled sites.\n\n## **API Usage**\n\nAPI usage limits are applied on a site-by-site basis, so a request to retrieve orders for OnBuy UK will not impact API limits on any other site.\n\nIf an endpoint does not require a Site ID, the API usage will be attributed to the primary site of the account, which is currently Site ID 2000 (OnBuy UK).\n\n## **Product Creation**\n\nThe most significant change to the OnBuy API is how product creation is handled. While the request structure will remain the same, how OnBuy handles product creation has changed.\n\n### Localisation\n\nEach site has a default localisation that all products must be translated to. For instance, the default localisation for OnBuy UK is en-GB.\n\nThe API will return a default_localisation property via the [Sites endpoint](https://docs.api.onbuy.com/#e4957d82-1325-4b69-824f-fa2d13763e4b).\n\nWhen creating products for a specific site, the content **must** be in the correct language.\n\n**Please Note:** the request body should contain a locale parameter with the correct value, e.g. \"localisation\": \"fr-fr\" for site 2001.\n\n### Content Scope\n\nProduct content has been separated into 2 groups, as detailed in the table below:\n\n| Content Scope | Description |\n| --- | --- |\n| Global | This content is shared across all OnBuy sites, such as OnBuy UK, OnBuy FR, etc.  <br>  <br>This group will have the same content, including but not limited to, the brand name, main product image and features. |\n| Local | This content is specific to individual sites.  <br>  <br>This group represents the majority of product content. |\n\n| Data | Group | Example Content |\n| --- | --- | --- |\n| Brands | Global | Brand Name (e.g., Apple, Chanel, Dyson, Lego) |\n| Basic Details | Global | Product Type (e.g., Single or Group), MPN |\n| Features | Global | Colours, Sizes (e.g., S, M, L, etc.) |\n| Images | Global | Default and Additional Image URLs |\n| Product Category | Global | Category ID |\n| Product Codes | Global | GTIN/Barcode |\n| Videos | Local | Embedded Video URLs |\n| Documents | Local | PDF Attachment URLs |\n| Product Data | Local | Custom Labels and Values |\n| Product Content | Local | Name, Description, Summary Points |\n| Technical Details | Local | Measurements in Units (e.g., Width, Height, Length) |\n| Product Site | Local | RRP |\n\n## Update Rules\n\nOnBuy has revised the rules regarding when product content can be updated. These rules are based on the scopes outlined in the Content Scope section. The table below explains the new rules:\n\n| Content Group | Proposed Solution |\n| --- | --- |\n| Global | A seller can update global content if they are the only person listing a product across all sites.  <br>  <br>If multiple sellers are listing the same product, global content is locked and cannot be changed. |\n| Local | Any seller can create a product on a new site if they are the first to do so.  <br>  <br>Local content can be updated if that seller is the only one listing the product on that specific site.  <br>  <br>If multiple sellers are listing the product on the same site (e.g., OnBuy UK), the local content is locked and cannot be changed. |\n\n## Creation Process\n\n### By Sellers\n\nOnce you have enabled additional locations, the product creation process remains the same.\n\nTo create a product, you will need to make a request to the Product Create endpoint. This request must include the Site ID for the site where you wish to list the product. The structure of this request will be the same as before.\n\n**Note:** The category structure is consistent across all sites, so the same category ID will be used for all requests for a specific product, regardless of the site.\n\nYou **must** ensure that the content is provided in the correct localisation for the site you are integrating with. Please review the Localisation section of this document before creating products.\n\n### By OnBuy\n\nWhile the seller's product creation process remains the same, OnBuy has updated how it handles product creation requests.\n\nTo maintain a centralised catalogue, products displayed across different sites are the same, but they will have separate content for each localisation. Product creation requests will be reviewed and matched to existing products in the catalogue based on the provided product codes:\n\n- **If a product code is already in use on one site**, a request to create that product on another site will result in a single product being listed on both sites.\n    \n- **If a product code is not yet in use on any site**, a request to create that product will result in a single product listed only on the requesting site.\n    \n\nThis means that product creation requests are essentially treated as “upserts,” where the system will update an existing product if it exists or insert a new one if it does not.\n\n## Feedback Loop\n\nThe feedback loop at the queue endpoints has been expanded as per the Update Rules above. This means:\n\n1. The queue endpoint will now contain a permitted_write_levels property\n    \n2. This property indicates the level of write access granted to the request\n    \n\n### **Structure of permitted_write_levels property:**\n\n`\"permitted_write_levels\": {`\n\n`\"global_product\": true,`\n\n`\"local_product\": true,`\n\n`}`\n\nEach value in this structure specifies whether that level of write access is allowed (true) or not (false).\n\nYou can find more details about the [Queues endpoint](https://docs.api.onbuy.com/#1ee1d135-111f-4d1a-82c2-b81029693326).\n\n# Currency\n\nAll prices must be provided in the local currency for each site, as listed in the table below. This ensures accurate pricing for sales in each country.\n\n| Site ID | Country | Currency |\n| --- | --- | --- |\n| 2000 | OnBuy UK | GBP |\n| 2001 | OnBuy France | EUR |\n| 2002 | OnBuy Germany | EUR |\n| 2003 | OnBuy Czech Republic | CZK |\n| 2004 | OnBuy Netherlands | EUR |\n| 2007 | OnBuy Austria | EUR |\n| 2008 | OnBuy Belgium | EUR |\n| 2011 | OnBuy Denmark | DKK |\n| 2013 | OnBuy Spain | EUR |\n| 2014 | OnBuy Finland | EUR |\n| 2015 | OnBuy Greece | EUR |\n| 2017 | OnBuy Hungary | HUF |\n| 2019 | OnBuy Ireland | EUR |\n| 2020 | OnBuy Italy | EUR |\n| 2026 | OnBuy Norway | NOK |\n| 2027 | OnBuy Poland | PLN |\n| 2028 | OnBuy Portugal | EUR |\n| 2029 | OnBuy Romania | RON |\n| 2030 | OnBuy Sweden | SEK |\n| 2031 | OnBuy Switzerland | CHF |\n| 2033 | OnBuy Slovakia | EUR |\n\nExample: Setting a product price for the German site.\n\n``` json\n{\n  \"site_id\": 2002,\n  \"listings\": [\n  {\n    \"sku\": \"examplesku\",\n    \"price\": 19.99\n  }\n ]\n}\n\n ```\n\nIn this example, the site ID 2002 corresponds to Germany, so the price given will be listed in euros (EUR). If you were setting a price for the UK site, the given price is listed in pounds sterling (GBP) instead.\n\n# API Change Log\n\n<table><tbody><tr><th>Date</th><th>Description</th></tr><tr><td><div>April 15th, 2026</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Resolved an issue where GET Carriers: Browse returned a 500 error when called with non UK site IDs.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>January 29th, 2026</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Fixed errors in the <code>GET /v2/listings/check-winning </code>Example Request.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>January 21st, 2026</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Stock and Price Handling on Product Create, and Stock and Price Update Requirements, sections added</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>December 19th, 2025</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Group Products/Variants section added</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>September 24th, 2025</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Additional Sites added to International Sites, Currency section added</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>July 10th, 2024</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Changes to Order Functionality:<br><br>Modified Timestamp: Previously, retrieving the order updated the modified timestamp. Now, it updates only when the order is modified.<br><br>Previously Exported Flag: Fixed an issue where the first integration to pull the order set the exported flag. Now, this flag is unique to each integration.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>May 3rd, 2024</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Example requests added for all endpoints.<br>New section to include details for creating test products.<br>Removed documentation for GET Categories Variants: Browse.<br>Removed documentation for GET Orders: Tracking-providers</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>May 7th, 2021</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Fixed some errors in the documentation.<br></div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>August 1st, 2019</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Added 'Delete Listing By SKU' Method<br></div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>March 20th, 2019</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Added Products: Update<br><br>Added Products: Update Batch<br><br>Added new options for listings: <code>return_time</code>, <code>free_returns</code> and <code>warranty</code></div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>October 24th, 2018</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Added new endpoint: orders/tracking-providers This will give an up to date list of tracking<br>providers in place of the list previously provided in this document.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>October 4th, 2018</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Added quantity_dispatched per item to view/browse orders</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>July 30th, 2018</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Fixed bug that affected any rrp over £999</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>July 20th, 2018</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div><br>Added group_sku to product listings<br><br>Added sales fee to Orders: browse/view<br><br>Added refund data to Orders: browse/view<br><br>Added Orders:Refund<br><br>Added Orders:Cancel<br><br>Updated Orders:Dispatch<br><br>Updated Sellers:Deliveries<br></div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>June 26th, 2018</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Added 'Collect+' to dispatch tracking options</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>June 6th, 2018</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Add buyer's IP address when displaying orders</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>May 17th, 2018</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Added Filter[can_list_in] for Categories:browse</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>April 19th, 2018</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Added 'RRD' to dispatch tracking options</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>March 16th, 2018</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Added product URL to browse queues and view queue</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>February 9th, 2018</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Return condition notes and handling_time when browsing listings</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>January 30th, 2018</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Added more courier services to dispatch tracking options.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>January 18th, 2018</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Added 'handling_time' option for listings. Expects number of days.<br>Applicable to Listings: Create[/batch] and Products: Create[/batch].</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>January 17th, 2018</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Add groups to product_data in create product.<br><br>Added 'GLS' to dispatch tracking options<br><br>Added URL to product search result.<br><br>Added filter[status] for Queues: Browse<br><br>Replaced 'live' flag with 'publish' in product: create<br><br>Added product batch create<br><br>Added listings batch create<br></div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>November 28th, 2017</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Order dispatch method updated to support partially dispatching orders.</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr></tbody></table>\n\n# API Methods","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"11486560","collectionId":"964655c9-de32-45ff-ab8d-4e55c047eee7","publishedId":"TzeRqAj9","public":true,"publicUrl":"https://docs.api.onbuy.com","privateUrl":"https://go.postman.co/documentation/11486560-964655c9-de32-45ff-ab8d-4e55c047eee7","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.1","publishDate":"2021-06-24T07:51:20.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"Onbuy API V2 Live.template","id":"3186e529-28a5-809a-f3ee-c338dcfccb5e","owner":"1949361","values":[{"key":"host","value":"https://api.onbuy.com/v2","enabled":true},{"key":"secret_key","value":"{{secret_key}}","enabled":true},{"key":"consumer_key","value":"{{consumer_key}}","enabled":true},{"key":"token","value":"{{access_token}}","enabled":true},{"key":"access_token","value":"4E7DREERR2189-A943-4697-C295-fCA434558518","enabled":true},{"key":"queue_id","value":"123","enabled":true,"type":"default"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":"https://onbuy.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Onbuy API V2 Live.template","value":"1949361-3186e529-28a5-809a-f3ee-c338dcfccb5e"}],"canonicalUrl":"https://docs.api.onbuy.com/view/metadata/TzeRqAj9"}