Welcome to nShift!

nShift Go API is an API-first, cloud native and fully headless platform which allows e-commerce platforms and online B2C marketplaces to integrate shipping as a part of their own offering.

We reduce the complexity of shipping with one API connection that gives access to a thousand carriers.

API

Our user-friendly REST API allows you to oversee all your shipping requirements, eliminating the need to grapple with the intricacies of various carrier APIs and protocols. We take care of the challenging aspects, enabling you to concentrate on delivering an exceptional shipping experience to your customers at the most competitive rates.

Every feature of nShift Go can be utilized independently or synergistically to incorporate robust shipping capabilities into your application or service.

Read more about the the guidelines we follow when implementing our API.

Mission

Our mission is to empower European retailers with a sustainable, fully-integrable commerce and delivery management suite. We strive to simplify their operations, helping them focus on their core business and scale effortlessly. We're committed to driving innovation in retail, leading with sustainability.

What is nShift Go?

Elevate your platform with our tailor-made end-to-end delivery management solution, designed for seamless integration and revenue growth. Built to be built in.

• One platform for global deliveries with the largest compliant carrier library in the world.
• Serves shippers of all sizes.
• Tailored eCOM modules to drive top line revenue and end customer satisfaction (checkout, post-purchase, returns).
• Holistic solution that combines products and share modules. We are connecting products/stages (checkout to returns) in one company.

Account management

Onboard merchants or simply create data isolations seamlessly through account provisioning.

Carrier management

Lookup metadata about supported carriers and services to build a dynamic integration. Create definitions according to each shipping method.

Delivery options

Create delivery options based on zones and conditions for providing a shipping method selection. Display the selection in your checkout or (coming soon) use it to determined the best option based on carrier rates, popularity or ETA.

Shipment booking

Orchestrate booking of shipments by creating parcels and linking to relevant definitions using the worlds largest carrier library.

Order management (coming soon)

Import orders directly from your platform and fulfill them into shipment bookings based on the order details.

Label printing (coming soon)

Stable and reliable print service. Configure printer profiles according to what type of printers in use or what type of documents to print.

Signup and subscription models is managed using Stripe, for more details regarding Stripe please visit https://stripe.com/en-se/billing/features#subscription-management.

1. You will receive a link from us for a onboarding page displaying a subscription. If you have a prenegotiated model you will receive a unique link instead of our standard link.
2. Once you access the onboarding page you will see the available subscriptions and the pricing.
3. Select a subscription and provide the needed information to finish the process.
4. Once completed, you will find your unique client ID and client Secret (Save these credentials securely).

If you are new to REST APIs then have a look at our REST API Guidelines to get a good starting point. Below you will find some step-by-step tutorials to get you started.

As accounts, carrier definitions and shipment channels are prerequisites to booking shipments we recommend following the sections below in subsequent order.

Create accounts

First you need to create an account for your merchant:

Step 1: Create account

Create account using your client ID and client secret from the signup process.

Authentification for accounts need to be verified through a base64 encoded string of client_id:client_secret following OpenAPI's securitySchemes and basicAuth, more info on the Accounts page.

Step 2: Issue Token

The account ID received is used as sub using the Issue Token endpoint.

Grant type is always set to “client_credentials”.

Step 3: Receive Bearer token

Token returned is used as Bearer token (expiration time 4 h) in subsequent requests to other endpoints.

For each account you will need to do some initial configurations.

As a partner, you create at least one account for each of your clients to ensure data isolation. Once an account ID is obtained, it can be used to issue an access token for further API interactions. The account ID should be considered a secret between the partner and nShift and should not be exposed to your clients.

Setup carrier definition

In order to create shipments you need to add carriers to the account in question through carrier definitions.

Step 1: API Endpoint

• Endpoint: POST /v0/carrier-definitions
• Base URL: https://api.nshiftgo.com

Step 2: Request Body

The request body must include the necessary details for the carrier definition. Below is an example of the required and optional fields:

{
  "carrierId": "your-uuid-for-carrier",
  "name": "DHL Home Delivery",
  "serialDefinition": [
    {
      "level": "SHIPMENT",
      "recycle": {
        "afterDays": 30,
        "enabled": true,
        "expires": "2023-12-31T23:59:59Z",
        "group": "your-group",
        "iterations": 5
      },
      "start": "start-date",
      "stop": "stop-date",
      "type": "your-type"
    }
  ],
  "service": {
    "id": "your-uuid-for-service",
    "addons": [
      {
        "code": "DLVIN",
        "info": [
          {
            "key": "mobile",
            "value": "+467012367890"
          }
        ]
      }
    ]
  },
  "settings": [
    {
      "key": "api-key",
      "value": "your-api-key"
    }
  ]
} {
  "carrierId": "your-uuid-for-carrier",
  "name": "DHL Home Delivery",
  "serialDefinition": [
    {
      "level": "SHIPMENT",
      "recycle": {
        "afterDays": 30,
        "enabled": true,
        "expires": "2023-12-31T23:59:59Z",
        "group": "your-group",
        "iterations": 5
      },
      "start": "start-date",
      "stop": "stop-date",
      "type": "your-type"
    }
  ],
  "service": {
    "id": "your-uuid-for-service",
    "addons": [
      {
        "code": "DLVIN",
        "info": [
          {
            "key": "mobile",
            "value": "+467012367890"
          }
        ]
      }
    ]
  },
  "settings": [
    {
      "key": "api-key",
      "value": "your-api-key"
    }
  ]
} 

Step 3: Authentication Header

Add the following header for authentication:

Authorization: Bearer {token}

Replace {token} with your actual bearer token.

Step 4: Content Type

Ensure the Content-Type header is set to application/json to indicate the MIME type of the request body.

Step 5: Request

Using a tool like cURL, Postman, or any HTTP client library in your programming language, send the POST request constructed in the previous steps to the server.

Step 6: Response

A successful request will return HTTP status 201 Created with a JSON response containing the id of the newly created carrier configuration. Handle other HTTP status codes (like 400 Bad Request) appropriately based on the API documentation.

Setup shipment channel

Once you have configured the carrier you have to setup a shipment channel containing information about how shipment bookings are processed. Configuring a shipment channel involves setting up parameters that dictate how shipments are processed, including document rendering settings and unit measurements.

Create a New Shipment Channel

• Endpoint: POST https://api.nshiftgo.com/shipments/channels
• Content Type: application/json
• Required Headers: Authorization: Bearer {token} (optional)
• Request Body:

{
       "name": "Channel 1",
       "documentRendering": {
         "enabled": true,
         "settings": [
           {
             "contentType": "zpl",
             "documentType": "NODFL",
             "enabled": true,
             "mediaType": "laser-1a5",
             "offsetX": 0,
             "offsetY": 0,
             "options": {
               "mode": "DT"
             }
           }
         ]
       },
       "units": {
         "dimensions": "cm",
         "volume": "cm3",
         "weight": "kg"
       }
     } {
       "name": "Channel 1",
       "documentRendering": {
         "enabled": true,
         "settings": [
           {
             "contentType": "zpl",
             "documentType": "NODFL",
             "enabled": true,
             "mediaType": "laser-1a5",
             "offsetX": 0,
             "offsetY": 0,
             "options": {
               "mode": "DT"
             }
           }
         ]
       },
       "units": {
         "dimensions": "cm",
         "volume": "cm3",
         "weight": "kg"
       }
     } 

Update an Existing Shipment Channel

• Endpoint: PUT https://api.nshiftgo.com/shipments/channels/{channelId}
• Content Type: application/json
• Required Path Parameter: channelId (UUID of the Shipment Channel)
• Required Headers: Authorization: Bearer {token} (optional)
• Request Body: Similar to the creation, but include the channelId in the path and modify the settings as necessary.

Fetch Existing Shipment Channel

• Endpoint: GET https://api.nshiftgo.com/shipments/channels/{channelId}
• Content Type: application/json
• Required Path Parameter: channelId (UUID of the Shipment Channel)
• Required Headers: Authorization: Bearer {token} (optional)

Retrieve All Shipment Channels

• Endpoint: GET https://api.nshiftgo.com/shipments/channels
• Content Type: application/json
• Query Parameters: (optional)
• page: The page number of results.
• size: Number of items per page.
• Required Headers: Authorization: Bearer {token} (optional)

Prepare shipment booking

Once you have configured the shipment channel you can start booking shipments.

Step 1: Required Data

Before making a request to create a shipment booking, ensure you have the following information ready:

• Shipment Channel: You need the unique identifier of the Shipment Channel.
• Carrier Configuration: Details like the carrier code, carrier ID, and specific configurations for the carrier.
• Parcel Information: Details about the parcels including dimensions, weight, and any specific parcel items.
• Addresses and Parties: Information about parties involved such as sender, receiver, and any other relevant parties.

Step 2: Request Body

Create a JSON/ object that includes all necessary details. Here is a general structure based on the requirements:

{
  "parties": [
    {
      // Details about each party involved
  
    }
  ],
  "shipmentChannel": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851"  // Example UUID for Shipment Channel
  },
  "carrierConfiguration": {
    "carrierCode": "DHL",
    "carrierId": "uuid-of-carrier",
    "id": "bb5afd39-f289-4fc4-a14b-5ee89502799c",  // Example UUID for Carrier Configuration
    "name": "DHL Home Delivery",
    "service": {
      // Additional service details
    }
  },
  "parcels": [
    {
      "id": "uuid-of-existing-parcel",  // Optional
      "items": [
        {
          "product": {
            "description": "This is a product description",
            "isPhysical": true,
            "location": "location-of-product",
            "sku": "product-sku",
            "weight": 10.5,
            "weightUnit": "G"
          },
          "quantity": 2
        }
      ]
    }
  ]
} {
  "parties": [
    {
      // Details about each party involved
  
    }
  ],
  "shipmentChannel": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851"  // Example UUID for Shipment Channel
  },
  "carrierConfiguration": {
    "carrierCode": "DHL",
    "carrierId": "uuid-of-carrier",
    "id": "bb5afd39-f289-4fc4-a14b-5ee89502799c",  // Example UUID for Carrier Configuration
    "name": "DHL Home Delivery",
    "service": {
      // Additional service details
    }
  },
  "parcels": [
    {
      "id": "uuid-of-existing-parcel",  // Optional
      "items": [
        {
          "product": {
            "description": "This is a product description",
            "isPhysical": true,
            "location": "location-of-product",
            "sku": "product-sku",
            "weight": 10.5,
            "weightUnit": "G"
          },
          "quantity": 2
        }
      ]
    }
  ]
} 

Step 3: API Request

Send a POST request to the endpoint that handles shipment booking:

POST https://api.nshiftgo.com/shipment-booking

Include the JSON body you've constructed in the request. Ensure that the Content-Type header of your request is set to application/json.

Step 4: Response

The API will respond with details of the created shipment booking. Handle the response/ accordingly based on your application's logic. If successful, the response should contain information about the booked shipment, including any identifiers and status information.

Step 5: Errors

Always check the response for possible errors. Handle any errors by checking the status code and the error message returned by the API. This will help in troubleshooting issues like validation errors or server problems.

Example CURL Command

Here is an example CURL command to create a shipment booking:

curl -X POST https://api.nshiftgo.com/shipment-booking -H "Content-Type: application/json" -d '{
"parties": [...],
"shipmentChannel": {"id": "d290f1ee-6c54-4b01-90e6-d701748f0851"},
"carrierConfiguration": {...},
"parcels": [...]
}' curl -X POST https://api.nshiftgo.com/shipment-booking -H "Content-Type: application/json" -d '{
"parties": [...],
"shipmentChannel": {"id": "d290f1ee-6c54-4b01-90e6-d701748f0851"},
"carrierConfiguration": {...},
"parcels": [...]
}' 

Replace the placeholders and property values with actual data as per your requirements.

We use a set of definitions across our specifications in order to increase understanding and providing consistency.

What is a REST API?

A REST API (Representational State Transfer Application Programming Interface) is a protocol intended for building and interacting with web services. It leverages standard HTTP methods such as GET, POST, PUT, and DELETE to perform operations on resources. Each resource is accessed via a standard HTTP URL, and operations are performed in a stateless manner, where calls can be made independently of each other and each call contains all necessary data to complete the operation.

AOS 3.0 Specifications

The AOS 3.0 specifications act as a formal contract between the API integrator and the API itself, defining the expected request formats and the promised response behaviors. This contract ensures that both parties have a mutual understanding of the API's capabilities, limitations, and protocols, promoting a seamless integration and reliable operation.

Error Responses

Our API conforms to RFC 9457 (https://datatracker.ietf.org/doc/html/rfc9457) for reporting problems within HTTP responses.

This standard helps in structuring error messages consistently across our API, making it easier for clients to understand and diagnose issues.

Error responses will include a type URI for an error, a title, and optionally a detailed description of the error along with its HTTP status code.

This information aids developers in quickly identifying the problem and finding a resolution.

Syntactical Standards

We adhere to the JSON Schema Validation vocabulary to define the structure of our JSON data.

This approach ensures that all JSON data exchanged via our API meets the detailed syntactical standards established in our schema specifications, including required properties, property types, and other format validations.

By enforcing these standards, we maintain high data integrity and facilitate smooth data interchange between systems.

URL Definitions

Our API follows a set of URL design principles to ensure they are intuitive, consistent, and easily scalable:

• Resource names: Always use pluralized nouns for resources (e.g., /users).
• Resource identifiers: Use URL-friendly identifiers for resources, typically UUID values.
• Path segments: Utilize kebab-case for path segments (e.g., /new-orders).
• Property names: Property names in payloads are to be in camelCase (e.g., userName).
• Query parameters: Always use snake_case for query parameters (e.g., start_date).
• Normalized paths: URLs should be normalized, omitting empty path segments and trailing slashes.
• Verb-free URLs: Keep URLs focused on resources rather than actions.
• Null and absent properties: Treat null and absent properties with the same semantics. Avoid using null for boolean properties; instead, use true or false.
• Array names: Pluralize names of array properties to reflect multiple values (e.g., phoneNumbers).
• Enum values: Declare enum values using UPPER_SNAKE_CASE (e.g., STATUS_ACTIVE).
• Entity identifiers: Define identifiers of entities as UUID values to ensure uniqueness.
• Pagination: Implement cursor-based pagination to manage data retrieval efficiently and securely.

By adhering to these guidelines, our API provides a robust, predictable, and efficient interface for developers, facilitating ease of integration and consistency across various platforms and technologies.

An address provides a standardized data model used by our different services. This means that an address will appear the same whether it's used in an order or shipment booking. However, providing specific roles to addresses will limit them to the extent they can be used or by what processes they are used. Roles can also be composites of other roles.

You can create as many addresses as you need and store them for later usage. This way you only need to keep track of their identifiers when you want to use them.

Data about all supported carriers and their services can be fetched so that integrating becomes easier and changes implemented in carrier connectivity can be reflected directly in your integration. Necessary data that can be retrieved includes codes, valid routes, validation rules etc.

Before creating a shipment booking or delivery option you will need to create a carrier definition. This will contain carrier specific information such as credentials and service parameters.

Documents are generated by shipment bookings such as labels, waybills, invoices etc. In addition, a user is able to uploade their own documents as attachments to orders or additional customs documents that can be used if the carrier supports paperless customs handling.

Parcels are a level lower than shipments and contain information about packing types, item descriptions and options for dangerous goods handling.

Some carrier services use PUDO points where the consumer picks up or drops off parcels. These endpoints allow you to find PUDO points based on the consumer address information.

Before you start creating shipments you need to create a shipment channel that contains configurations for shipment processing e.g. how generated documents are rendered.

Shipment bookings contains information about everything associated with the delivery including addresses, carrier service codes, parcel information, customs declaration etc.

Service definitions are pre-configured settings for services, which allows you to quickly refer and use services from carriers without configuring parameters each call.