Sign in

nShift Help Center

Getting started with DeliveryCloud API

Avatar
Malene Tidemann
Updated

Are you looking to consolidate all your shipping data in one centralized location, even though you are working with multiple book and print products? With nShift's DeliveryCloud API, you can integrate all your shipments into nShift Portal. This allows you to easily manage and track your shipments while taking advantage of comprehensive reporting and advanced tracking tools, ensuring 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 DeliveryCloud 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 DeliveryCloud 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 DeliveryCloud 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 DeliveryCloud API, they can send in all shipments booked in another system and benefit from nShift Track.

 

 

Create a DeliveryCloud organization

Start by creating an Organisation and a Member Account Name in nShift Portal. This is the location where the shipments will be created. 

  1. Log in to nShift Portal and click on Settings in the top left corner.

  2. Choose Organization Config. (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.



Create Client ID and secret

The DeliveryCloud 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

Use your Client ID and Client Secret to generate an access token. This is done by making a POST request to the following endpoint:

https://api.nshiftportal.com/delivery-cloud/idp/connect/token 


Sample:
POST https://api.nshiftportal.com/delivery-cloud/idp/connect/token
Cache-Control: no-cache
Host: www.nshiftportal.com 
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials

 

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"
}

The bearer token is valid for one hour. All requests must have the token in the Authorization header.

 

 

Using the DeliveryCloud API

Once authenticated, you are ready to start using the DeliveryCloud 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

     

  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

     

Go to the technical API documentation

Related articles