Based on simple REST principles, our API endpoints return data in JSON format for products, pricing, stock information, orders, payments and contacts.
The base address of the API is https://api.cin7.com/api. There are several endpoints at that address, each with its own path.
You will need to have access to a Cin7 Omni account and be logged in to setup an API connection before you can make API calls.
You can access our Swagger page here (BETA).
You can view our OpenAPI specification (JSON) here (BETA).
Cin7 Omni API uses "Basic Authentication" over HTTPS. The service will check the credentials on each request and return the response accordingly; in case of invalid credentials, the service responds with 401 error code i.e. unauthorized.
To authorize your requests, include a header with the key "Authorization" and the value being your credentials.
Example
| Key | Value |
|---|---|
| Authorization | Basic dGVzdGFwaXVzZXJuYW1lOnRlc3RhcGlrZXk= |
Calls are limited to 3 per second, 60 per minute and 5000 per day. If you exceed this rate limit, you will receive an HTTP 429 (Too Many Requests) response.
We recommend saving data to a database and only making requests for records whose modified date is higher than the last poll time. Note that it may take some time to extract large amounts of data.
Therefore, we recommended that an application is structured to schedule or queue this function, so there is no expectation of an immediate response.
All dates are UTC format "yyyy-MM-ddTHH:mm:ssZ". Example: 2010-12-04T11:58:00Z
All parameter values should be URL encoded.
| Parameter | Description |
|---|---|
| fields |
Comma separated list of fields to return. By default all fields are returned. The fields parameter filters the API response so that it only includes a specific set of fields. For example, if you want to retrieve sales order ID, InvoiceDate and SKU for each line item in a sales order, append the following fields parameter to the URL ?fields=id,invoicedate,lineitems(code) |
| where |
Where statement to filter the records. Any field in a parent object can be used in the where statement. Operands: (=|<>|>|<|<=|>=|IS|IS NOT|LIKE|NOT LIKE|IN) Example: SalesOrders?where=modifieddate>='2020-12-31T00:00:00Z' In the URL, encode '%' as '%25'. Example: Products/?where=categoryIdArray LIKE '%25363%25' |
| order |
Comma separated list of fields to order the returned records Sort Direction: By default fields are sorted highest to lowest. To reverse append "ASC" to the end of the field Example: CreatedDate ASC |
| page |
To utilise paging, append a page parameter to the URL e.g. ?page=1. If there are 50 records in the response you will need to check if there is any more data by fetching the next page e.g ?page=2 and continuing this process until no more results are returned. Recent records appear first, to change the sort order, append an order by parameter e.g. ?order=createddate asc |
| rows | The number of rows to return in a page. |
A summary of HTTP Response Codes returned by the Cin7 Omni API is shown below.
| HTTP Code | Summary | Description |
|---|---|---|
| 200 | OK | Successful API call. |
| 400 | Bad Request | A bad request or a validation exception has occurred. |
| 401 | Unauthorized | Invalid authorization credentials. |
| 403 | Forbidden | Connection doesn't have permission to access the resource. |
| 404 | Not Found | The resource you have specified cannot be found. |
| 429 | Too Many Requests | The API rate limit for your application has been exceeded. |
| 500 | Internal Server Error | An unhandled error with the Cin7 Omni API. Contact the Cin7 Omni API team if problems persist. |
| 503 | Service Unavailable | API is currently unavailable, typically due to a scheduled outage, try again soon. |
| Endpoint | Description |
|---|---|
| GET api/v1/Adjustments |
Get a list of Adjustments. |
| POST api/v1/Adjustments |
Create a list of Adjustments. |
| PUT api/v1/Adjustments |
Update a list of Adjustments. |
| GET api/v1/Adjustments/{id} |
Get an Adjustment. |
V2
| Endpoint | Description |
|---|---|
| GET api/v2/BomMasters |
Get a list of BOM Masters. |
| GET api/v2/BomMasters/{id} |
Get a Bom Master. |
V1
Endpoints for retrieving information about BOM Masters.
| Endpoint | Description |
|---|---|
| GET api/v1/BomMasters |
Get a list of BOM Masters. |
| GET api/v1/BomMasters/{id} |
Get a Bom Master. |
Endpoints for retrieving information about Branches.
| Endpoint | Description |
|---|---|
| GET api/v1/Branches |
Get a list of Branches. |
| POST api/v1/Branches |
Create a list of Branches. |
| PUT api/v1/Branches |
Update a list of Branches. |
| GET api/v1/Branches/{id} |
Get a Branch. |
| Endpoint | Description |
|---|---|
| GET api/v1/BranchTransfers |
Get a list of Branch Transfers. |
| POST api/v1/BranchTransfers |
Create a list of Branch Transfers. |
| PUT api/v1/BranchTransfers |
Update a list of Branch Transfers. |
| GET api/v1/BranchTransfers/{id} |
Get a Branch Transfer |
| Endpoint | Description |
|---|---|
| GET api/v1/Cartons/{id} |
Get the Carton details for a Sales Order. |
| PUT api/v1/Cartons/{id} |
Replace the list of Cartons for a Sales Order. |
Endpoints for retrieving information about Contacts.
| Endpoint | Description |
|---|---|
| GET api/v1/Contacts |
Get a list of Contacts. |
| POST api/v1/Contacts |
Create a list of Contacts. |
| PUT api/v1/Contacts |
Update a list of Contacts. |
| DELETE api/v1/Contacts/{id} |
Delete a Contact. |
| GET api/v1/Contacts/{id} |
Get a Contact. |
Endpoints for retrieving information about Credit Notes.
| Endpoint | Description |
|---|---|
| GET api/v1/CreditNotes |
Get a list of Credit Notes. |
| POST api/v1/CreditNotes |
Create a list of Credit Notes. |
| PUT api/v1/CreditNotes |
Update a list of Credit Notes. |
| GET api/v1/CreditNotes/{id} |
Get a Credit Note. |
Endpoints for retrieving information about Cin7 Pay payment fees and payouts. Use the where parameter to filter by date.
| Endpoint | Description |
|---|---|
| GET api/v1/PaymentFeesAndPayouts/Fees |
Get a list of payment fees. |
| GET api/v1/PaymentFeesAndPayouts/Payouts |
Get a list of payouts. |
Endpoints for retrieving information about payments.
| Endpoint | Description |
|---|---|
| GET api/v1/Payments |
Get a list of Payments |
| POST api/v1/Payments |
Create a list of Payments. |
| PUT api/v1/Payments |
Update a Payments. |
| DELETE api/v1/Payments/{id} |
Delete a Payment. |
| GET api/v1/Payments/{id} |
Get a Payment. |
Endpoints for retrieving information about Products Categories.
| Endpoint | Description |
|---|---|
| GET api/v1/ProductCategories |
Get a list of Product Categories |
| POST api/v1/ProductCategories |
Creates new Product Categories. |
| PUT api/v1/ProductCategories |
Updates Product Categories. |
| GET api/v1/ProductCategories/{id} |
Get a Product Category |
| Endpoint | Description |
|---|---|
| POST api/v1/ProductImages |
No documentation available. |
Endpoints for retrieving information about Production Jobs.
| Endpoint | Description |
|---|---|
| GET api/v1/ProductionJobs |
Get a list of Production Jobs. |
| POST api/v1/ProductionJobs |
Create a list of Production Jobs. |
| PUT api/v1/ProductionJobs |
Update a list of Production Jobs. |
| GET api/v1/ProductionJobs/{id} |
Get a Production Job. |
Endpoints for retrieving information about product options.
| Endpoint | Description |
|---|---|
| GET api/v1/ProductOptions |
Get a list of Product Options. |
| POST api/v1/ProductOptions |
Create a list of ProductOptions |
| PUT api/v1/ProductOptions |
Update a list of ProductOptions |
| GET api/v1/ProductOptions/{id} |
Get a Product Option. |
Endpoints for retrieving information about products.
| Endpoint | Description |
|---|---|
| GET api/v1/Products |
Get a list of Products. |
| POST api/v1/Products |
Creates a list of Products. Duplicated style codes or product option code in the request will cause the request to be rejected with a 400. If a product with the same style code or product option code already exists, it will be skipped and not created. |
| PUT api/v1/Products |
Updates a list of Products. If a product with the same style code or product option code already exists, it will be skipped and not updated. Leave fields empty to clear them, leave fields null to not update them. |
| GET api/v1/Products/{id} |
Get a Product. |
Endpoints for retrieving information about purchase orders.
| Endpoint | Description |
|---|---|
| GET api/v1/PurchaseOrders |
Get a list of Purchase Orders. |
| POST api/v1/PurchaseOrders |
Create a list of Purchase Orders. |
| PUT api/v1/PurchaseOrders |
Update a list of Purchase Orders. |
| GET api/v1/PurchaseOrders/{id} |
Get a Purchase Order. |
Endpoints for retrieving information about quotes
| Endpoint | Description |
|---|---|
| GET api/v1/Quotes |
Get a list of Quotes |
| POST api/v1/Quotes |
Create a list of Quotes |
| PUT api/v1/Quotes |
Update a list of Quotes |
| GET api/v1/Quotes/{id} |
Get a Quote |
Endpoints for retrieving information about sales orders
| Endpoint | Description |
|---|---|
| GET api/v1/SalesOrders |
Get a list of Sales Orders. |
| POST api/v1/SalesOrders |
Create a list of Sales Orders. |
| PUT api/v1/SalesOrders |
Update a list of Sales Orders. |
| GET api/v1/SalesOrders/{id} |
Get a Sales Order. |
| Endpoint | Description |
|---|---|
| GET api/v1/SalesOrdersWithCartons |
Get a list of Sales Orders with their Carton details. |
| GET api/v1/SalesOrdersWithCartons/{id} |
Get a Sales Order with it's Carton details. |
Endpoints for retrieving information about Serial Numbers.
| Endpoint | Description |
|---|---|
| GET api/v1/SerialNumbers |
Get a list of Serial Numbers. |
| GET api/v1/SerialNumbers/{id} |
Get a Serial Number. |
| Endpoint | Description |
|---|---|
| GET api/v1/SizeRanges |
Get SizeRange |
| GET api/v1/SizeRanges/{id} |
Get SizeRange |
Endpoints for retrieving information about stock.
| Endpoint | Description |
|---|---|
| GET api/v1/Stock |
Get a list of Stock Units. |
| GET api/v1/Stock/{barcode} |
Get a Stock Unit. |
Endpoints for retrieving information about users. Users may take up to 2 hours to appear in the API.
| Endpoint | Description |
|---|---|
| GET api/v1/Users |
Get a User. |
| GET api/v1/Users/{id} |
Get a User. |
Endpoints for retrieving information about vouchers.
| Endpoint | Description |
|---|---|
| GET api/v1/Voucher |
Get a list of Vouchers |
| GET api/v1/Voucher/{code} |
Get a Voucher. |