Sign in

nShift Help Center

Getting started with nShift Checkout API

Avatar
Malene Tidemann
Updated

nshift-checkout-label.png


nShift Checkout API is an integration service for communication between nShift Checkout and your webshop. The nShift Checkout API uses a REST API framework for communication with JSON as data carrier offering several functions.

To get started using the API, you need to go through the following steps:

  1. Create Client ID and secret
  2. Request a token
  3. Create a session
  4. Call shipping options endpoint
  5. Create a partial shipment
  6. API Documentation

 

1. Create Client ID and secret

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

  1. Log into nShift Portal with your owner user.

  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.

    add-clients-api.png

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

    client-id.png

  6. Choose Public checkout 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.

    client-secret.png
  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. 

 

 

2. 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://account.nshiftportal.com/idp/connect/token 


Sample:
POST https://account.nshiftportal.com/idp/connect/token
Cache-Control: no-cache
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-dskjfhsuijkdhfgjkasjdgfhqoeiefoiknsoidfgvoiltgjvpdrofjmwpkldujrftvoifgkhbnilsakjprotglijkqp2owrlfjkvmowrifgho2qw9ouejifpe9rodtuj3-0porfij9odtujgw0etioyh",
    "expires_in": 3600,
    "token_type": "Bearer"
}

The bearer token is valid for one hour.

 

 

3. Create a session

Use the bearer token to call the nShift Checkout session endpoint. Make a POST request to:

https://www.nshiftportal.com/checkout/options/v1/sessions/{checkoutConnectionId}

 

Use the Connection ID as the path parameter. Go to Connections in the top menu and find your Connection ID on the list. (Read more about Connections here).

connection-id.png


The POST call will create a session valid for 4 hours unless used during that time. The session will contain information from your checkout configuration, e.g. sender details. If you wish to change which Checkout configuration you use for getting shipping options, you can simply change which configuration the connection ID points to.

 

To change which Checkout configuration a connection ID points to, go to Connections in the top menu and click on the connection you want to change. Choose another Checkout in the Configuration drop-down list and click Save.

change-config.png

 

 

4. Call shipping options endpoint

Using the session ID, you can make a POST call to the shipping options endpoint:


https://www.nshiftportal.com/checkout/options/v1/shipping-options/{sessionId}

 

The request body of the shipping options endpoint contains information about the receiver, the package(s), and other additional data that might impact available shipping options. The response contains a list of available shipping options. If you use the nShift Checkout widget, this data should be supplied to the correct method to display the shipping options.

 

 

5. Create a partial shipment

When your end customer has selected a shipping option you can create a partial shipment in your Book and Print platform (nShift Delivery, nShift Ship, or nShift Transsmart).

 

Make a POST call to:

https://www.nshiftportal.com/checkout/shipments/v1/shipments


For more information, see the API documentation.

 

The request body of this call contains the session ID, the selected shipping option ID, and other information about the shipment, such as the order ID which will be the unique identifier you use to find the partial shipment in the Book and Print platform. The request body also contains information about the receiver. You may change some of the receiver details (some values such as postal code are non-changeable due to their effect on available shipping options).

The call will result in a created partial shipment in the Book and Print platform for the selected shipping option. To transform the partial shipment into an actual shipment, you must call the associated endpoints in the respective Book and Print platforms.

 

 

API Documentation

Our technical API documentation is available here:

Go to the API documentation

Related articles