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. 

Purpose

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

Use Case

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. 

Benefits

  • 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.

If creating a Sale Order, ensure there is available stock (Purchase Order is in allocated status). 
  • 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. 
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. 
If this is the first time creating an API Client for the Customer, it is highly recommended you create a sandbox customer first. Ensure you include the word sandbox in the name field when creating the sandbox customer. See the Prerequisites section of this article for more information. 
  • 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. 
If you do lose the credentials, please see the Generating New Credentials section of this article. 

  • 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). 
Using the Copy button next to the Client ID and Client Secret allows you to easily transfer the data to the API user. You can also do this from the Edit API Client page. 

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:

If you are creating a Sandbox Customer, ensure you provide the Sandbox Customer UUID for testing, and once testing is complete, you provide the live 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. 
Once the API Client is updated with the live Customer, you can track their usage (the number of API calls made) using the API Client Usage Report. Please see the API Client Usage Report page for more information. 

API Roles

RoleAccess
API Full Access 
  • Includes all TMS Create Jobs and WMS Create Jobs access.
  • Provides the ability to create new Transport Products

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
  • Add, view & search consignments
  • View available Transport Products
  • View Customers (only those the API client has access to)
  • View which Custom Fields exist
  • View Warehouses (only those the API client has access to)
WMS Create Jobs
  • Add, view, search Purchase Orders (Inbound)
  • Add, view, search Sale Orders (Outbound)
  • Add, edit, view Warehouse Products (Product Masters)
  • View Customers (only those the API client has access to)
  • Run Stock Reports
  • View Custom Fields
  • View Warehouses (only those the API client has access to)

Generating New Credentials

Note that the old credentials will become invalid if you generate new credentials, and any existing connections that use the old credentials will fail. 

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.

If you don't know the tenantUuid and/or customerUuid, you can find this out once you have a working Access Token by making requests to: https://api-docs.cartoncloud.com/#user and https://api-docs.cartoncloud.com/#list-customers respectively.

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"

Please note excessive API usage charges apply, click here for more information.