Skip to content
  • There are no suggestions because the search field is empty.

API Clients

Table of Contents


Purpose

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. 

Screen Shot 2021-07-27 at 3.11.10 pm.png

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 and Benefits

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. 

  • Sending transport jobs (Consignments) to 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)

Before using the API Client on a live Customer, it is highly recommended that 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 Customers 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 Steps

How to add an API Client

  • Navigate to Contacts>API Clients. 

  • Select +Add API Client in the top left corner. 

Screen Shot 2021-07-08 at 2.35.32 pm.png

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

image2022-8-12_14-19-27.png


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

Screen Shot 2021-08-25 at 9.30.35 am.png

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



Screen Shot 2021-08-25 at 9.30.55 am.png

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



image2022-8-12_14-19-55.png
 

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. 

Screen Shot 2021-07-26 at 10.55.16 am.png
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. 

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

image2022-8-12_14-20-27.png


image2021-7-27_13-31-42.png

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

Screen Shot 2021-08-25 at 9.30.55 am (1).png

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

image2021-8-4_11-49-50.png

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:

    image2021-8-4_11-52-17.png
  • With the access token generated, click Use Token. 

    image2021-8-4_11-56-58.png

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