The iStockist API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.
\nAuthenticate your account when using the API by including your API key and password in the request. You can manage your API keys in the Dashboard. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.
\nAuthentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value and your API secret as the basic auth password value.
\nAll API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
\niStockist uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with iStockist's servers (these are rare).
\nNot all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g., an order is declined), we return a 402 error code. To understand why an order is declined, refer to the list of codes in the documentation.
\nHTTP status code summary
\nARGUMENTS
\nOur API libraries raise exceptions for many reasons, such as a failed orders, invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.
\nThe API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create an order fails due to a network connection error, you can retry the request with the same universally unique identifier (uuid) to guarantee that only a single order is created.
\nWe recommend using V4 UUIDs. We recommend that every POST request has unique identifiers.
\nTo help you get started with generating uuids for test purposes, here's an article on generating universally unique ids providing links to libraries in various server-side languages here.
\nWhen we make backwards-incompatible changes to the API, we release new, dated versions. The current version is 2021-03-15.
\nRead our API upgrades guide to see our API changelog and to learn more about backwards compatibility.
\nAll requests will use your account API settings, unless you override the API version. The changelog lists every available version. Note that events generated by API requests will always be structured according to your account API version.
\nTo set the API version on a specific request, send a iStockist-Version header.
\nYou can visit your Dashboard to upgrade your API version. As a precaution, use API versioning to test a new API version before committing to an upgrade.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"API Reference","slug":"api-reference"},{"content":"Authentication","slug":"authentication"},{"content":"Errors","slug":"errors"},{"content":"Handling errors","slug":"handling-errors"},{"content":"Idempotent Requests","slug":"idempotent-requests"},{"content":"Versioning","slug":"versioning"}],"owner":"107212","collectionId":"e43510f9-842a-4ce0-9c74-b07aeddc7733","publishedId":"Tz5s5ck7","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2021-03-16T16:14:08.000Z"},"item":[{"name":"Customers","item":[{"name":"Create/update customer - min fields","id":"50313271-2e2c-4082-b96f-d5d371a2942f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{customer_key}}"},{"key":"password","value":"{{customer_secret}}"}],"advancedConfig":[{"key":"saveHelperData","value":"Creates a new customer object.
\nSee Customer defintion above and sample data in 'Create a customer - full definition'
\nThe required data to create a customer is
\nYou can also send a uuid for this customer to track the create customer request.
\nUnique identifier: Once the the customer is created in iStockist, you'll get back an _id field in the response which you can use to track the customer in iStockist.
\nARGUMENTS
\nReturns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.
\nAn array that contains the filtered list of customers. Each entry in the array is a separate customer object. If no more customers are available, the resulting array will be empty. This request should never raise an error.
\n","urlObject":{"protocol":"https","path":["api","v1","companies"],"host":["api","istockist","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"fbe43e54-d0e2-4719-a10f-5846a49281ed"}],"id":"8d44c1a6-62c6-495e-a056-ab63b25cabbf","description":"Customer objects allow you to perform recurring orders and track multiple orders that are associated with the same customer. The API allows you to create your customers. You can retrieve individual customers as well as a list of all your customers.
\nYou can create/update the list of users who can purchase on behalf of the customer. For each contact, inside customer.contacts, please send in the email as a mandatory field, and you can also send in the firstName, lastName as optional fields.
\nYou can create/update the list of delivery/billing addresses for the customer. For each one, inside customer.addresses, please send in the street address, city and country as mandatory fields. You can also send in the zipCode, state, and address name as optional fields.
\n","_postman_id":"8d44c1a6-62c6-495e-a056-ab63b25cabbf"},{"name":"Products","item":[{"name":"Create/update products - min. fields","id":"e09d6d51-92bb-40e6-b6bd-5fb223ae8b5c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{customer_key}}"},{"key":"password","value":"{{customer_secret}}"}],"advancedConfig":[{"key":"saveHelperData","value":"Creates a new product.
\nThe required data to create a product is
\nYou can also send a uuid for this product to track the create product request.
\nUnique identifier: Once the the customer is created in iStockist, you'll get back an _id field in the response which you can use to track the customer in iStockist.
\nARGUMENTS
\nReturns a list of your products. The products are returned sorted by creation date, with the most recent products appearing first.
\nAn array that contains the filtered list of products. Each entry in the array is a separate product object. If no more products are available, the resulting array will be empty. This request should never raise an error.
\n","urlObject":{"protocol":"https","path":["api","v1","items"],"host":["api","istockist","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"6a2052b1-cce0-4561-9829-5b03a7ef940c"}],"id":"951ef645-5a1e-4210-9a98-e459dc11927f","description":"Products objects allow you to perform recurring orders and track multiple orders that are associated with the same product. The API allows you to create your products. You can retrieve individual products as well as a list of all your products.
\nObject. You can add/edit the category for each product.
\nArray. You can currently only send in one image file. (In the future you'll be able to post more than one image per product)
\nFor each store or template, send in the name of the store or template and the price for that store.
\nFor each warehouse, please send in the name of the warehouse, the stock on hand and allocated stock for that warehouse. If allocated stock is not provided, we will assume that none of the stock on hand is allocated.(That allocated stock = 0). The stock available for customers to purchase is the stock on hand value minus the allocated stock.
\nYou can add as many product attributes as you need for each product
\nFor each store or template, please send in the name of the store and the price for that store.
\n","event":[{"listen":"prerequest","script":{"id":"47470957-6acb-4103-854b-e398a65eae21","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"66b41917-889d-4a1a-95e3-769e0a8346ef","type":"text/javascript","exec":[""]}}],"_postman_id":"951ef645-5a1e-4210-9a98-e459dc11927f"},{"name":"Sales Orders","item":[{"name":"Create a sales order","id":"d71b46fe-5248-4838-84d8-e00e458dc89c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{customer_key}}"},{"key":"password","value":"{{customer_secret}}"}],"advancedConfig":[{"key":"saveHelperData","value":"To make a sales order, you create an Order object.
\nThe required data to create an order is
\nIdempotent request identifier: You can send a uuid for each customer object to track the create customer request.
\nUnique identifier: Once the the order is created in iStockist, you'll get back an _id in the response which you can use to track the order in iStockist.
\nThe order object:
\nReturns a list of sales orders created. The orders are returned in sorted order, with the most recent orders appearing first.
\nARGUMENTS
\n","urlObject":{"protocol":"https","path":["api","v1","orders"],"host":["api","istockist","com"],"query":[{"key":"from","value":"2022-03-01"},{"key":"to","value":"2022-03-28"}],"variable":[]}},"response":[],"_postman_id":"75110cd3-8638-4c38-8efd-5a487fdc97c0"}],"id":"0793d24a-38e7-4d81-8a70-623691f54c6f","description":"To make a sales order, you create an order object. You can retrieve and update individual sales orders as well as list all sales orders.
\nThe order object:
\n