{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"d6d629b1-b4d7-4d09-9698-d143ee8afe97","name":"RetailBox API Engine","description":"### Welcome to the Retailr API Engine!\n\nHere, data flows seamlessly to power your retail and supply chain operations. With Retailr, you can access a world of retail management tools built for simplicity. We hope you enjoy integrating Retailr as much as we enjoyed building it.\n\nP.S.: Just a quick note—Retailr is a **Retail Management System (RMS)**, not just an inventory management system. It’s designed to help you manage everything from your store's operations to its supply chain. Get it right!\n\nKeep in mind that **all data you create on Retailr can be exported for free at any time**, so there's no risk of vendor lock-in.\n\n---\n\n### Quick Tips:\n\n1. ``` json\n      {\n      \"status\": \"success\" | \"error\",\n      \"message\": \"A brief description of the response\",\n      \"data\": { /* The payload data for successful requests */ },\n      \"error\": \"Technical error details, if applicable\",\n      \"ignored_fields\": [ /* List of fields that were ignored during create/update operations */ ],\n      \"ignored_params\": [ /* List of query parameters that were ignored during list/get operations */ ]\n      }\n    \n     ```\n    \n    - **status**: Indicates whether the request was successful (\"success\") or failed (\"error\").\n        \n    - **message**: A short, user-friendly explanation of the response.\n        \n    - **data**: The content returned for successful operations. This will be `null` if the request fails.\n        \n    - **error**: Relevant error details when the request fails. This will be `null` for successful requests.\n        \n    - **`ignored_fields`**: This field is included in the response when handling `POST`, `PUT`, or `PATCH` methods (create/update/edit operations).It lists the fields from the request payload that were ignored, helping users identify invalid or unsupported fields they might have included.\n        \n    - **`ignored_params`**: This field is included in the response when handling `GET` or `LIST` methods.It lists any query parameters that were ignored during the request, allowing users to refine their API usage.\n        \n2. **Pagination in List Responses**  \n    For all list-based endpoints, the `data` property in the response will always contain paginated data, even if no explicit pagination query parameter is included. This is because datasets can be quite large, and we avoid sending the entire dataset in a single request. The response structure for paginated data is as follows:\n    \n    ``` json\n                       {\n                         \"count\": 1234,  // Total number of items available in the dataset\n                         \"next\": \"https://api.retailr.com/resource?page=2\",  // URL for the next page of results\n                         \"previous\": null,  // URL for the previous page of results, null if on the first page\n                         \"results\": [ /* Array of data objects for the current page */ ]\n                       }\n    \n     ```\n    \n    - **count**: Total number of items in the dataset.\n        \n    - **next**: URL pointing to the next page of results (if available).\n        \n    - **previous**: URL pointing to the previous page of results (if available).\n        \n    - **results**: An array of data objects for the current page.\n        \n\n```\n**Note**: You can control the number of items per page by using the `page_size` query parameter in your request. The default page size is 42, and the maximum allowed is 100.\n\n ```\n\n1. **Authorization**  \n    Aside from the sign-in and sign-up endpoints, the **Authorization** header is mandatory for all requests to ensure that the user has the right access level.\n    \n2. **Content Type**  \n    Unless otherwise stated, the content type for all requests and responses will be **JSON**.\n    \n3. **Dev Managed vs Custom Resources**  \n    Some resources in Retailr are designated as **Dev Managed**, meaning they cannot be modified by users. These resources are maintained internally by the Retailr team and typically refer to **General Resources**.\n    \n    When a store or branch customises a **General Resource**, it becomes a **Custom Resource**. This allows the resource to be adjusted for specific store or branch needs without affecting the shared general version.\n    \n    **Example**:\n    \n    - **Tax**: A General resource containing a comprehensive list of taxes across the system.\n        \n    - **BranchTax**: A Custom resource derived from Tax. This links a General Tax to a specific branch and allows customisation, such as assigning a branch-specific tax value.\n        \n4. **Resource Access and Permissions**  \n    All endpoints are secured with a permission layer. Resources can only be accessed by authorised individuals with the appropriate permissions granted by the team or management controlling the resource. For example, viewing branch details requires explicit permission.\n    \n    There are two primary ways to gain access to a resource:\n    \n    - **Team Membership**: Becoming a member of the team that manages or controls the resource. There are 2 ways to give a team member permission; either by assigning an employee role to them, or by creating an explicit Branch Permission rule. The former is easier.\n        \n    - **Ownership**: Owning the resource, either by being the creator or having ownership transferred to you.\n        \n5. **Rate Limiting**  \n    Certain endpoints that are expected to have frequent traffic are rate-limited to ensure fair usage and to maintain server performance. If you make more than 10 requests to a rate-limited endpoint within a 60-second window, you will be temporarily restricted from making further requests for 1 minute. This helps maintain server stability for all users.\n    \n6. **Authentication: API Keys vs JWT**  \n    For authentication, you can choose between **API keys** and **JWT tokens**:\n    \n    - **API Keys**: These provide long-term access without the need for frequent renewal. However, they may incur additional costs. More information can be found on the pricing page.\n        \n    - **JWT Tokens**: These require periodic refreshing (typically every 30 minutes) to maintain session validity.\n        \n\n7\\. It is important to always append a trailing slash.\n\n8\\. **Protected Fields and \"NIL\" Values in Responses**\n\nIn certain scenarios, especially when retrieving user or resource details via the API, sensitive data may be excluded or obfuscated for privacy and security reasons. These fields are considered **protected** and will not be included in their original form when the request context indicates that the requestor is external or does not have the necessary permissions.\n\n9\\. Querying and Filtering Resources  \nWhen you list resources via the API, the response will always include all resources from every branch or store you are affiliated with. To make your results more specific, you can filter the data by adding query parameters. Here's how filtering works:\n\n1. **Passing IDs Directly**  \n    You can pass a list of IDs to retrieve specific resources in one go. For example:\n    \n    ``` plaintext\n                 ?ids=1,2,3\n    \n     ```\n    \n    This will return the resources with IDs 1, 2, and 3.\n    \n2. **Using Filterable Fields**  \n    Each endpoint specifies fields or parameters that you can query to filter results further. For instance:\n    \n    ``` plaintext\n                 ?status=active&category=beverages\n    \n     ```\n    \n    This retrieves all active resources under the \"beverages\" category.\n    \n\n**Note:** Always check the documentation for the endpoint to see the available filterable fields and how to use them effectively.\n\n**Got a problem?**  \nIf you encounter any issues on our end, feel free to reach out to us directly at:  \n📧 [<b>awesome@retailr.co</b>](https://null)  \nOr join the conversation on Telegram:  \n🔗 [https://t.me/retailr_co/](https://t.me/retailr_co/)","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"39947662","team":6568131,"collectionId":"d6d629b1-b4d7-4d09-9698-d143ee8afe97","publishedId":"2sB2cd4Hzu","public":true,"publicUrl":"https://postman.retailbox.co","privateUrl":"https://go.postman.co/documentation/39947662-d6d629b1-b4d7-4d09-9698-d143ee8afe97","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2025-06-04T23:35:44.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"Production","id":"b555f177-a737-4768-91a7-6f1be915f076","owner":"39947662","values":[{"key":"baseUrl","value":"https://api.retailbox.co","enabled":true},{"key":"token","value":"<JSON_WEB_TOKEN>","enabled":true}],"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/edaf5b84287e06ac80ce808285f78c3e180b3bccd5910baef2f2ea84d5a60f2f","favicon":"https://retailbox.co/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":"Production","value":"39947662-b555f177-a737-4768-91a7-6f1be915f076"}],"canonicalUrl":"https://postman.retailbox.co/view/metadata/2sB2cd4Hzu"}