Test a Cin7 Omni API connection
Overview
Use Postman to test your Cin7 Omni API connection and practice making simple calls, such as:
GET: Read data (sales orders, products, specific fields, specific number of results, searching, combinations)
Your Cin7 Omni API connection enables you to read, update, create, and delete data in Cin7 Omni from third-party applications.
For example, you can create new sales orders when you make a sale, or create credit notes to handle returns. You can also mark a purchase order as received and much more.
But, before you implement your connection within your real workflow, we suggest using Postman to practice making basic calls to Omni.
First sign up for Postman. Then, to authorize its connection to Omni, add your Cin7 Omni API connection’s username and key into the Username and Password fields on the Authorization tab in Postman.
Now use the following examples to test your connection – each example specifies the call’s type, endpoint, and body, which you must copy into Postman, along with a video demo.
POST: Create a sales order
Demo:Create a sales order via Cin7 Omni API
Type: POST
Endpoint: https://api.cin7.com/api/v1/SalesOrders
Body:
[{
"memberId": 41,
"lineItems":
[{
"code": "ProductZ",
"qty": 1.0
}]
}]
POST and PUT: Create a credit note
You make three calls to create an approved credit note:
Create the credit note
Add a payment
Approve the credit note
1. Create the credit note
Type: POST
Endpoint: https://api.cin7.com/api/v1/CreditNotes
Body:
[{
"IsApproved": false
"memberId": 25,
"SalesReference":"ABC-123",
"lineItems":
[{
"Code":"apron",
"qty": -1.0
}]
}]
2. Add the payment
Type: POST
Endpoint: https://api.cin7.com/api/v1/Payments
Body:
[{
"createdDate": "2020-03-10T21:29:36Z",
"modifiedDate": "2020-03-10T21:29:36Z",
"paymentDate": "2020-03-10T21:29:36Z",
"amount": 400.0,
"method": "Credit Card",
"orderId": 105,
"IsAuthorized":true
}]
3. Approve the credit note
Type: PUT
Endpoint: https://api.cin7.com/api/v1/CreditNotes
Body:
[{
"Id":105,
"IsApproved": true
}]
PUT: Update a sales order
Demo:Update a sales order via Cin7 Omni API
Type: PUT
Endpoint: https://api.cin7.com/api/v1/SalesOrders
Body:
[{
"id": 244,
"Mobile":"321892318929138",
"dispatchedDate": "2022-05-10T13:05:23.3054125+12:00”
}]
GET: Read data
When writing GET requests, we suggest using the Parameters tab to construct your request more easily.
Basic GET
This is the simplest GET call:
Type: GET
Endpoint: https://api.cin7.com/api/v1/SalesOrders/
Read a sales order
In this example, “101” is the sales order’s ID:
Type: GET
Endpoint: https://api.cin7.com/api/v1/SalesOrders/101
Read a product
In this example, “101” is the product’s ID:
Type: GET
Endpoint: https://api.cin7.com/api/v1/Products/120
Read specific fields of a sales order
In this example, the fields being read are “isapproved” and “company” only:
Type: GET
Endpoint: https://api.cin7.com/api/v1/SalesOrders?fields=isapproved,company
Read a specific number of sales orders
You can read either a specific number of sales orders (rows):
Type: GET
Endpoint: https://api.cin7.com/api/v1/SalesOrders?rows=5
Or a specific number of pages (200 rows per page):
Type: GET
Endpoint: https://api.cin7.com/api/v1/SalesOrders?page=2
Search for sales orders
You can search for sales orders that meet a condition:
Type: GET
-
Find sales orders with references beginning with “CLOT”
Endpoint: https://api.cin7.com/api/v1/SalesOrders?where=reference LIKE 'CLOT%'
-
Find sales orders with references equal to “CLOT”
Endpoint: https://api.cin7.com/api/v1/SalesOrders?where=reference='CLOT'
-
Find sales orders with a member IDs equal to “20”
Endpoint: https://api.cin7.com/api/v1/SalesOrders?where=memberId > 20
-
Find sales orders with member IDs that equal either “21”, “24”, or “543”
Endpoint: https://api.cin7.com/api/v1/SalesOrders?where=memberId IN (21,24,543)
Or you can search for sales order that meet multiple conditions – this example finds sales orders with references beginning with “CLOT” and member IDs great than 20:
Type: GET
Endpoint: https://api.cin7.com/api/v1/SalesOrders?where=memberId > 20 AND reference LIKE 'CLOT%'
Combining functions
You can search for sales orders that meet conditions and read only specific fields – this example finds sales orders with reference beginning with “CLOT” and member IDs greater than 20 and returns the “memberid”, “reference”, and “company” fields only:
Type: GET
Endpoint: https://api.cin7.com/api/v1/SalesOrders?where=memberId > 20 AND reference LIKE 'CLOT%'&fields=memberId, reference, company
Or you can search for sales orders, return specific fields only, and limit and order the results – this example finds two pages of sales order, returns the fields “memberid” and “reference” only, and orders the results by ascending date created:
Type: GET
Endpoint: https://api.cin7.com/api/v1/SalesOrders?fields=memberId, reference, company&order=CreatedDate ASC&page=2
Foreign currency transactions
When you create (POST) or update (PUT) a foreign currency transaction, always denominate the transaction in the foreign currency, not your local currency.
But, when you read (GET) a foreign currency transaction, you’ll be given the local currency values. You’ll be given the current exchange too, though, so you can easily calculate the equivalent values in the foreign currency (that is, multiple the local currency values by the exchange rate).
LogisticsStatus
The LogisticsStatus key corresponds to the 3PL Status field of a transaction. The value of this key will be an integer, which will correspond to a status:
0 – Transfer To 3PL Upon Completion
1 – Transfer to 3PL Now
180 – Transfer Return Notification to 3PL Now
2 – Transferred to 3PL for Picking
3 – Transfer Purchase Order to 3PL Now EDI Only
4 – Transfer Purchase Order Change to 3PL Now EDI Only
943 – Stock Transfer Shipment to 3PL Now EDI Only
-1 – Transferred to 3PL with ERRORS
9 – Do Not Transfer to 3PL
10 – Picked by 3PL Successfully
11 – Partially picked by 3PL
-2 – Picked by 3PL with ERRORS
202 – Transferred to 3PL for Picking - Acknowledged
210 – Picked by 3PL Successfully - Acknowledged
5 – Cancelled by 3PL
429 too many requests error
When you exceed the Cin7 Omni API rate limit, you will receive the 429 Too Many Requests error. You can check the response header for the Retry-After time period (in seconds). Your API request will work if you try again after that period of time.