Please note, to be able to create API Clients you need to have the Administrator role enabled and the 'Allow this user to edit other Users' option selected.
CartonCloud provides an API to facilitate integrations with third-party systems.
To use this API, you must first create an API Client in CartonCloud.
For more technical and detailed information on the CartonCloud API and how to use it, please see the API Documentation.
Your Customer may wish to use the API to send and receive data from their internal system to CartonCloud. Data could include:
- Sending inbound and outbound orders (Purchase Orders and Sale Orders) to CartonCloud.
- Updating inbound and outbound orders in CartonCloud.
- Sending transport jobs (Consignments) to CartonCloud.
- Updating transport jobs (Consignments) in CartonCloud.
- Sending new or updating existing Products in CartonCloud.
- Retrieve stock on hand report from CartonCloud.
- Allows users with the technical skills and knowledge to create their own integrations between CartonCloud and third-party systems.
- Enables the user to send data into CartonCloud from another system and retrieve information from CartonCloud.
- Greater control over data retrieved and sent between the two systems.
- Have access to the return messages to troubleshoot if issues do occur.
- You do not have to wait for a particular trigger to send and receive information, as you have the freedom to do so at any time.
Sandbox Customer Testing (Optional)
It is highly recommended that before using the API Client on a live Customer you create a Sandbox Customer first to test the API.
A sandbox is a testing environment utilised to test API calls that will not impact the live Customer's account and data.
To create a Sandbox Customer:
- Duplicate the Customer you are giving API access to. See Adding and Duplicating Customers for instructions on how to duplicate a Customer.
- Ensure the name of the Customer includes the word Sandbox to avoid confusion. For example, 'Coastal Coffee Company Sandbox'.
- Provide the API user with Customer access to the Sandbox Customer. See Creating or Inviting New Users for instructions on how to add a new user.
- Provide the API user with the Sandbox Customer UUID, Tenant UUID and Warehouse UUID (if more than one warehouse). See the UUID section of this article for more information.
- Optionally, you can create Products in the Sandbox Customer. See Exporting and Importing Products for instructions on how to create new products in bulk.
You can then create test orders to ensure the structure used to send the data to CartonCloud is correct.
- Once testing is complete, you will update the API Client with access to the live Customer. See the Going Live with the API Client section of this article before updating the API Client with access to the live Customer.
How to add an API Client
- Navigate to Contacts>API Clients.
- Select +Add API Client in the top left corner.
- Fill in the Name field with a descriptive name relating to the client.
- Select the Customers and Warehouses you wish to give the API access to.
- Select an API Role for the API Client. See API Roles for more information.
If the Customer only uses the Transport system, enable TMS Create Jobs.
If the Customer only uses the Warehouse system, enable WMS Create Jobs.
If the Customer uses both the Transport and Warehouse systems, you will need to select both TMS Create Jobs and WMS Create Jobs (as demonstrated in the image below).
Do not use API Full Access for Customers.
See API Roles for more information.
- Slide the INACTIVE toggle to ACTIVE.
- Select Save.
- A pop-out window will be prompt you with information regarding generating credentials.
- Once you have read the information, tick both boxes and select Generate Credentials.
- The Client ID and Client Secret will be displayed. Remember to store these credentials securely and don't lose them. You will need to provide these to the API user.
- In addition to the above information, you will also need to provide the API user with the Customer UUID, Tenant UUID, and, if applicable, the Warehouse UUID (if more than one warehouse).
Universally Unique Identifier (UUID)
The Universally Unique Identifier identifies certain information in a computer system. It ensures that data is being sent and received from the correct Customer, Tenant and Warehouse.
You will need to provide the API user with the;
- Customer UUID (during testing, you will need to provide the Sandbox Customer UUID and then later the live Customer UUID).
- Tenant UUID
- Warehouse UUID (only if you have more than one warehouse)
To locate the Customer UUID:
- Navigate to the Customers page, Contacts>Customers.
- Select the applicable Customer.
- The UUID is within the Details box at the bottom of the screen.
To locate the Tenant UUID:
- Navigate to Organisation Settings, More>Organisation Settings.
- Navigate to the Organisation tab.
- The UUID is within the Basic Organisation Information box at the bottom of the screen.
To locate the Warehouse UUID:
- Navigate to the Warehouses page by typing Warehouses into the Search for anything bar.
- Use the UUID column to find the UUID for the relevant Warehouse.
Going Live with the new API Client
If you tested the API Client with a Sandbox Customer, follow the below steps before going live with the new API Client:
- Delete all of the sandbox customers orders/consignments in CartonCloud.
- Deactivate the sandbox customer in CartonCloud.
- Edit the API Client and remove the sandbox customer and add the live customer.
- Provide the user with the live Customer UUID.
|API Full Access|
In the future there will be endpoints added which would not be suitable for Customer access. For this reason we do not recommend providing API Full Access to any API Clients given to a customer.
|TMS Create Jobs|
|WMS Create Jobs|
Generating New Credentials
If credentials of an existing API Client are misplaced, you can generate new credentials.
- Navigate to the API Clients page, Contacts>API Clients.
- Select the API Client.
- Select Generate Credentials.
- Carefully read the information provided before generating new Credentials, as creating new credentials will destroy the old credentials, which can break existing integrations.
- Once confirming you wish to proceed, the new Client ID and Client Secret will be displayed. Remember to store these credentials securely and don't lose them.
- The developer will also need the Tenant UUID and Customer(s) UUID when advising of credentials.
Postman Setup for API Access
You can access our CartonCloud API Postman Collection here: https://www.getpostman.com/collections/f8efd52a0c0d1a82d197
Once imported into postman, you'll need to setup collection variables and then get an API token.
Clicking on the collection in postman will bring up the collection settings.
First, navigate to the "Variables" tab, and insert your tenantUuid, customerUuid, authClientId and AuthClientSecret into the "Current Value" column.
For more help with Variables refer to the Postman Documentation
With these variables filled out, jump to the "Authorization" tab and you'll be able to Get New Access Token:
With the access token generated, click "Use Token"