Sign in
nShift Help Center

Getting started with Delivery Cloud API

Avatar
Malene Tidemann
Updated

Are you looking to consolidate all your shipping data in one centralized location, even when using multiple book and print solutions? With nShift's Delivery Cloud API, you can use Shadow Booking to add shipments booked outside nShift directly to nShift Portal, without booking them again. This allows you to manage and track all your shipments in one place while benefiting from comprehensive reporting and advanced tracking tools, giving you better visibility across your entire shipping process.

 

Content in this article:

 

Main use cases

Our customers have many different setups and solutions, creating various use cases for the Delivery Cloud API. Here are a few examples of the main use cases:

 

Use Case 1: Multiple shipping flows

The customer might use an nShift book and print solution together with nShift Track but also have a dropshipping flow that uses another book and print solution. With the Delivery Cloud API, the customer can send shipments from the dropshipping flow into the nShift Portal and use Track for all shipments. 

 

Use Case 2: Emissions tracker

The customer wants to use the nShift Emissions Tracker, but not all of their shipments are created using an nShift book and print product. Using the Delivery Cloud API, they can send in all shipments and get emissions calculations. 

 

Use Case 3: Using a non-nShift book and print solution

The customer uses a non-nShift book and print solution but wants to buy nShift Track. Using the Delivery Cloud API, they can send in all shipments booked in another system and benefit from nShift Track. This is also referred to as Shadow booking.

 

 

Create a Delivery Cloud organization

Start by creating an Organization and a Member Account Name in nShift Portal. This is the location where the shipments will be created. Please note that you must create an Organization Unit and a Member account specifically for Delivery Cloud, even if you have another exisiting member account in nShift Portal. 

  1. Log in to nShift Portal and click on Settings in the top left corner.
     
  2. Choose Company Management > Delivery Cloud Configuration. (If you do not see this option, you need to contact nShift Customer Service to get it activated).


     
  3. Click Create and click Add Organization Unit.


     
  4. Enter an Organization Unit Name and a Member Account Name.


     
  5. Click Save.
     
  6. Remember to copy and store your Organization ID and Member Account ID since these values are needed for the API requests. Choosing Copy ID will copy the value to your clipboard.



 

Create Client ID and secret

The Delivery Cloud API requires using tokens (Client IDs and Client Secrets). 

Start by creating the Client ID and secret needed for the authentication. 

  1. Log in to nShift Portal. (If you are not using an Owner account you may need to request access from the Owner/Admin).
     
  2. Click on Settings in the top right corner.

    nav-settings.png
     
  3. Choose API Configuration > Clients in the left side menu.
     
  4. On the Clients page, click the Add button.
     
  5. Fill in Display name and Description. Choose a name and a description that will make it easier to identify the token later on. Check the Enable box to enable the token right away. (You may enable or disable the token at any time after it has been created).

    deliverycloud-client.png
     
  6. Choose Portal Shipment Data API under Allowed Scopes which are the APIs you need access to. 
     
  7. Click Save. Your Client ID and Client Secret will now be generated and displayed on the screen. Important: The Client Secret will not be available after you close the popup, so make sure to copy it.
     
  8. Click Close. The Client ID will now be listed on the Clients page. You can click on a Client ID at any time to edit or delete it or to enable/disable it. 

 

 

Request a token

The Delivery Cloud API uses OAuth 2.0. Use your Client ID and Client Secret to generate an access token. This is done by making a POST request to the following endpoint:
 

  • Production: https://account.nshiftportal.com/idp/connect/token
  • Test: https://account.qa.nshiftportal.dev/idp/connect/token


Set the Content-Type header to application/x-www-form-urlencoded, and send these values in the body:

  • grant_type: client_credentials
  • client_id: your client ID
  • client_secret: your client secret

 

If the request is valid and the client is configured correctly, you will get back a JSON response:

{
    "access_token": "some-real-token-data-dskjfhsuijkdhfgjkasjdgfhqoeiefoiknsdfgvoiltgjvp...",
    "expires_in": 3600,
    "token_type": "Bearer"
}

 

Using the access token

All requests must have the token in the Authorization header. Send the returned access_token in the Authorization header of each request: Authorization: Bearer {access_token}.

 

The bearer token is valid for one hour. Request a new token when the current one expires.

 

 

Using the Delivery Cloud API

Once authenticated, you are ready to start using the Delivery Cloud API. Start by getting the list of all the carriers. Identify the carrier you are going to use and get the services and addons for that carrier. Once you have the correct IDs for the carrier, service, and addons, you are ready to create the shipment.

 

Overview of the methods and steps needed to add your shipments to nShift Portal:

  1. Get a list of all carriers and identify the ID of the carrier you need.

    GET /metadata/carriers

    Note: organizationId used in this request is the ID you copied and stored after Creating the Organization Unit. 
     

  2. Get an overview of the services of a carrier. Use the carrier ID you obtained from the list of carriers.

    GET /metadata/carriers/{carrierId}/services

     

  3. Get an overview of addons available for a carrier. Use the carrier ID you obtained from the list of carriers. Addons are not always used, so this step is optional if your shipments do not have addons.

    GET /metadata/carriers/{carrierId}/addons

     

  4. Create shipments using the carrier ID, service ID, and addon ID.

    PUT /shipments

    Note: the accountId used in this request is the Member Account UUID that you copied and stored after Creating the Organization Unit and Member Account. Remember to use the Member Account ID and not the Organization ID. 
     

Go to the technical API documentation

 

Related articles