nshiftgo

Getting Started

Features

Signup

Onboarding

Terminology

REST API Guideline

Accounts

Creates a new account that can be used to interact with the nShift Go APIs.  As a [Partner](https://docs.nshiftgo.com/getting-started/terminology), you create at least one [Account](https://docs.nshiftgo.com/getting-started/terminology) for each one of your clients. This ensures data isolation for your clients. 

Once you have an `accountId`, it can be used to [issue an Access Token](#tag/Accounts/operation/IssueToken), which can be used to call the nShift Go APIs. 

The `accountId` should be considered a **SECRET** between the Partner and nShift, and should not be exposed to your clients.

Create Account

To interact with the nShift Go APIs, you need an Access Token for the Account you intend to act as. To issue such a token, call this endpoint with the `accountId` of the Account returned from the [Create Account](#tag/Accounts/operation/CreateAccount) endpoint as the `sub` parameter. All Access Tokens are valid for 4 hours, and then need to be renewed by calling this endpoint again.

Issue Token For Account

Updates the details of an existing Account. The `accountId` is returned from the [Create Account](#tag/Accounts/operation/CreateAccount) endpoint.

Update Account

Returns the details of a specific account. The `accountId` is the unique identifier for the account.

Fetch Account

Returns a list of all accounts that have been created by the Partner. This can be used to get a list of all clients that the Partner has onboarded.

List Accounts

Addresses

Create new addresses that can be used through Orders or Shipment Bookings by referencing their unique identifiers.
When defining an Address you need to provide suitable roles. Each role corresponds to how the address can be used in the system e.g. an Address with both 'SENDER' and 'RECEIVER' roles can be used both for dispatching and delivery addresses. The role definitions differ according to which API endpoints you use as e.g. 'SELLER' may not correspond to where the Shipment Booking is actually sent from etc.

Create Address

Update an existing Address with new information. Note that changes made to an Address may not be reflected on already processed entities such as Orders and Shipment Bookings.

Update Address

Remove an existing Address. Note that changes made to an Address may not be reflected on already processed entities such as Orders and Shipment Bookings.

Delete Address

Fetch an existing Address by using its unique identifier.

Fetch Address

Lists all existing Addresses stored on the account.

List Addresses

Carriers

Fetch Carrier

Fetch a specific carrier service by `serviceId`.

Fetch Carrier Service

This endpoint will list all available carriers and provide rudimentary information about each. Once this information is acquired further requests can be made to discover more data about each carrier and service.

List Carriers

List all available services for a specific `carrierId`. For route-specific validation information, specify `routeFrom` and `routeTo`.

List Carrier Services

List all available services. For route-specific validation information, specify `routeFrom` and `routeTo`.

List Services

List Serials

Carrier Definitions

This endpoint creates a new Carrier Definition, with needed information to use a specific Carrier, on your account.

Create Carrier Definition

This endpoint updates an existing Carrier Definition on your account.

Update Carrier Definition

This endpoint deletes an existing Carrier Definition on your account.

Delete Carrier Definition

This endpoint will fetch an existing Carrier Definition on your account.

Fetch Carrier Definition

This endpoint will list all the existing Carrier Definitions on your account.

List Carrier Definitions

Documents

Fetch the meta data and Base64-encoded content of a document using its unique identifier documentId.

Fetch Document

Retrieve the raw binary data of a document based on its content type using the document's unique identifier documentId.

Fetch Document Data

Fetch the meta data of a specific document using its unique identifier documentId.

Fetch Document Meta Data

Retrieve meta data for all documents associated with a specific account. Optionally, filter the results by `groupId` to include only documents related to a particular entity, such as a Shipment Booking.

List Document Meta Data

Parcels

Creates a new Parcel in the system with the provided specifications.

Create Parcel

Modifies an existing Parcel identified by its unique ID with the provided data.

Update Parcel

Removes a Parcel from the system based on its unique identifier.

Delete Parcel

Retrieves a specific Parcel by its unique identifier.

Fetch Parcel

Retrieves a paginated list of all Parcels associated with the authenticated account.

List Parcels

Creates a new Parcel Item in the system with the provided specifications.

Create Parcel Item

Modifies an existing Parcel Item identified by its unique ID with the provided data.

Update Parcel Item

Removes a Parcel Item from the system based on its unique identifier.

Delete Parcel Item

Retrieves a specific Parcel Item by its unique identifier.

Fetch Parcel Item

Retrieves a paginated list of all Parcel Items associated with the authenticated account.

List Parcel Items

PUDO Points

Using this endpoint will list any PUDO Points that fall within the proximity of the provided address information.

Query PUDO Points

If you need to fetch a specific PUDO Point you can request it by providing the PUDO Point ID.

Fetch PUDO Point

Shipping Quotes

A Shipping Quote stores information about a specific Delivery Option, the evaluated price and cart information.
This endpoint will evaluate existing Deliver Options and generate corresponding Shipping Quotes. You can then use a Shipping Quote and transform it into an Order or Shipment Booking directly.

Create Shipping Quotes

If you need to fetch a specific Shipping Quote you can request it by providing the Shipping Quote ID.

Fetch Shipping Quote

Using this endpoint will list any existing Shipping Quotes filtered by provided reference.

Fetch Shipping Quotes

Lists all existing Shipping Quotes stored on the account,

List Shipping Quotes

Shipment Channels

Create a new Shipment Channel containing information about how an associated Shipment Booking is processed.

Create Shipment Channel

Update an existing Shipment Channel containing information about how an associated Shipment Booking is processed.

Update Shipment Channel

Delete an existing Shipment Channel by using its unique identifier.
Note that Shipment Channels are required to create Shipment Bookings and removing a used Shipment Channel might cause an integration to stop working.

Delete Shipment Channel

Fetch an existing Shipment Channel by using its unique identifier.

Fetch Shipment Channel

List all existing Shipment Channels stored on the account.

List Shipment Channels

Shipment Bookings

Create a new Shipment Booking containing information about associated Shipment Channel, Carrier Configuration and Addresses etc.
Parcel information is also provided or optionally pulled from associated Parcel objects that you define before hand.

Create Shipment Booking

Fetch an existing Shipment Booking by using its unique identifier.

Fetch Shipment Booking

Lists all existing Shipment Bookings stored on the account.

List Shipment Bookings

Service Definitions

This endpoint creates a new Service Definition, with needed information to use a specific Service, on your account.

Create Service Definition

This endpoint updates an existing Service Definition on your account.

Update Service Definition

This endpoint deletes an existing Service Definition on your account.

Delete Service Definition

This endpoint will fetch an existing Service Definition on your account.

Fetch Service Definition

This endpoint will list all the existing Service Definitions on your account.

List Service Definitions

Using this endpoint allows you to retrieve a list of serial numbers based on the carrier configuration ID.

List Serial Numbers

Serial Definitions

This endpoint creates a new Serial Definition.

Create Serial Definition

This endpoint updates a Serial Definition.

Update Serial Definition

This endpoint deletes a Serial Definition.

Delete Serial Definition

This endpoint returns a Serial Definition.

Fetch Serial Definition

This endpoint will list all available Serial Definitions.

List Serial Definitions

Default

nShift Go API

nShift Go Documentation

Production

<h2 class="slate-h2 " >Welcome to nShift! </h2><p class="slate-p " >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. </p><p class="slate-p " >We reduce the complexity of shipping with one API connection that gives access to a thousand carriers.</p><p class="slate-p " ></p><h2 class="slate-h2 " >API</h2><p class="slate-p " >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.</p><p class="slate-p " >Every feature of nShift Go can be utilized independently or synergistically to incorporate robust shipping capabilities into your application or service.</p><p class="slate-p " >Read more about the the <a href="https://docs.nshiftgo.com/getting-started/rest-api-guideline" target="_top">guidelines we follow</a> when implementing our API.</p><p class="slate-p " ></p><h2 class="slate-h2 " >Mission</h2><p class="slate-p " >Our mission is to empower European retailers with a sustainable, fully-integrable commerce and <strong class="slate-bold">delivery management </strong>suite. We strive to simplify their operations, helping them focus on their core business and scale effortlessly. We&apos;re committed to driving innovation in retail, leading with <strong class="slate-bold">sustainability</strong>.</p><p class="slate-p " ></p><h2 class="slate-h2 " >What is nShift Go?</h2><p class="slate-p " >Elevate your platform with our tailor-made end-to-end <strong class="slate-bold">delivery management</strong> solution, designed for <strong class="slate-bold">seamless integration</strong> and revenue growth. <strong class="slate-bold">Built to be</strong> <strong class="slate-bold">built in</strong>.</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">One platform for global deliveries with the <strong class="slate-bold">largest compliant carrier library </strong>in the world.</div></li><li class="slate-li " ><div style="position:relative">Serves shippers <strong class="slate-bold">of all sizes</strong>.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Tailored eCOM modules</strong> to drive top line revenue and end customer satisfaction (checkout, post-purchase, returns).</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Holistic solution that combines products</strong> and share modules. We are connecting products/stages (checkout to returns) in one company.</div></li></ul><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p>

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.

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.

Our mission is to empower European retailers with a sustainable, fully-integrable commerce and 

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 

Elevate your platform with our tailor-made end-to-end 

<p class="slate-p " ><a href="https://docs.nshiftgo.com/accounts" target="_top"><strong class="slate-bold">Account management</strong></a></p><p class="slate-p " >Onboard merchants or simply create data isolations seamlessly through account provisioning.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ><a href="https://docs.nshiftgo.com/carriers" target="_top"><strong class="slate-bold">Carrier management</strong></a></p><p class="slate-p " >Lookup metadata about supported carriers and services to build a dynamic integration. Create definitions according to each shipping method.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ><a href="https://docs.nshiftgo.com/delivery-options" target="_top"><strong class="slate-bold">Delivery options</strong></a></p><p class="slate-p " >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.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ><a href="https://docs.nshiftgo.com/shipments" target="_top"><strong class="slate-bold">Shipment booking</strong></a></p><p class="slate-p " >Orchestrate booking of shipments by creating parcels and linking to relevant definitions using the worlds largest carrier library.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ><a href="https://docs.nshiftgo.com/orders" target=""><strong class="slate-bold">Order management (coming soon)</strong></a></p><p class="slate-p " >Import orders directly from your platform and fulfill them into shipment bookings based on the order details.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p slate-indent-0" style="0px"><a href="https://docs.nshiftgo.com/print" target=""><strong class="slate-bold">Label printing (coming soon)</strong></a></p><p class="slate-p " >Stable and reliable print service. Configure printer profiles according to what type of printers in use or what type of documents to print.</p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p>

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

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

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.

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

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

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

<p class="slate-p " >Signup and subscription models is managed using Stripe.</p><ol class="slate-ol " ><li class="slate-li " ><div style="position:relative">You will receive a link from us for a <strong class="slate-bold">onboarding page</strong> displaying a subscription.
If you have a prenegotiated model you will receive a unique link instead of our standard link.</div></li><li class="slate-li " ><div style="position:relative">Once you access the onboarding page you will see the available subscriptions and the pricing.</div></li><li class="slate-li " ><div style="position:relative">Select a subscription and provide the needed information to finish the process.</div></li><li class="slate-li " ><div style="position:relative">Once completed, you will find your unique client ID and client Secret (Save these credentials securely).</div></li></ol><div style="text-align:left"><img src="https://theneo-prod-public.s3.us-east-1.amazonaws.com/4328fa46-b3a6-49d5-9e85-8a0c8895ce5a.jpg" style="
              width:957px;
	            height:510px;
	            aspect-ratio:957 / 510"
         /></div><p class="slate-p " ></p><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=error ><div class="callout-icon"><svg width="18" height="18" viewBox="0 0 18 18" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M9.08366 9.9801C9.25033 9.9801 9.39269 9.92107 9.51074 9.80302C9.6288 9.68496 9.68783 9.53566 9.68783 9.3551V5.31344C9.68783 5.14677 9.62533 5.00441 9.50033 4.88635C9.37533 4.7683 9.22949 4.70927 9.06283 4.70927C8.88227 4.70927 8.73296 4.7683 8.61491 4.88635C8.49685 5.00441 8.43783 5.15371 8.43783 5.33427V9.37594C8.43783 9.5426 8.50033 9.68496 8.62533 9.80302C8.75033 9.92107 8.9031 9.9801 9.08366 9.9801ZM9.00033 13.1676C9.19477 13.1676 9.35796 13.1016 9.48991 12.9697C9.62185 12.8377 9.68783 12.6745 9.68783 12.4801C9.68783 12.2857 9.62185 12.1225 9.48991 11.9905C9.35796 11.8586 9.19477 11.7926 9.00033 11.7926C8.80588 11.7926 8.64269 11.8586 8.51074 11.9905C8.3788 12.1225 8.31283 12.2857 8.31283 12.4801C8.31283 12.6745 8.3788 12.8377 8.51074 12.9697C8.64269 13.1016 8.80588 13.1676 9.00033 13.1676ZM9.00033 17.3343C7.81977 17.3343 6.72255 17.1225 5.70866 16.6989C4.69477 16.2752 3.81283 15.6884 3.06283 14.9384C2.31283 14.1884 1.72602 13.3065 1.30241 12.2926C0.878798 11.2787 0.666992 10.1815 0.666992 9.00094C0.666992 7.83427 0.878798 6.74399 1.30241 5.7301C1.72602 4.71621 2.31283 3.83427 3.06283 3.08427C3.81283 2.33427 4.69477 1.74399 5.70866 1.31344C6.72255 0.88288 7.81977 0.667603 9.00033 0.667603C10.167 0.667603 11.2573 0.88288 12.2712 1.31344C13.285 1.74399 14.167 2.33427 14.917 3.08427C15.667 3.83427 16.2573 4.71621 16.6878 5.7301C17.1184 6.74399 17.3337 7.83427 17.3337 9.00094C17.3337 10.1815 17.1184 11.2787 16.6878 12.2926C16.2573 13.3065 15.667 14.1884 14.917 14.9384C14.167 15.6884 13.285 16.2752 12.2712 16.6989C11.2573 17.1225 10.167 17.3343 9.00033 17.3343ZM9.00033 16.0843C10.9448 16.0843 12.6114 15.3898 14.0003 14.0009C15.3892 12.612 16.0837 10.9454 16.0837 9.00094C16.0837 7.05649 15.3892 5.38982 14.0003 4.00094C12.6114 2.61205 10.9448 1.9176 9.00033 1.9176C7.05588 1.9176 5.38921 2.61205 4.00033 4.00094C2.61144 5.38982 1.91699 7.05649 1.91699 9.00094C1.91699 10.9454 2.61144 12.612 4.00033 14.0009C5.38921 15.3898 7.05588 16.0843 9.00033 16.0843Z" fill="#E90005"></path></svg></div><div ><p class="slate-p " ><strong class="slate-bold">IMPORTANT: </strong>Remember to store your Client ID and Client Secret in a secure manner. These cannot be regenerated.</p></div></div><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p>

Signup and subscription models is managed using Stripe.

<div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " >If you&apos;re a partner you have to <a href="https://docs.nshiftgo.com/getting-started/signup" target="_top">sign up as an nShift Go partner</a> before you can start onboarding customers.</p></div></div><p class="slate-p " >If you are new to REST APIs then have a look at our <a href="https://docs.nshiftgo.com/getting-started/rest-api-guideline" target="_top">REST API Guidelines</a> to get a good starting point. Below you will find some step-by-step <strong class="slate-bold">tutorials</strong> to get you started.</p><p class="slate-p " >As accounts, carrier definitions and shipment channels are prerequisites to booking shipments we recommend following the sections below in subsequent order.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><h1 class="slate-h1 " ><strong class="slate-bold">Create accounts</strong></h1><p class="slate-p " >First you need to create an <strong class="slate-bold">account </strong>for your <a href="https://docs.nshiftgo.com/getting-started/terminology" target="_top">merchant</a>:</p><h3 class="slate-h3 " ><strong class="slate-bold">Step 1: Create account</strong></h3><p class="slate-p " ><a href="https://docs.nshiftgo.com/accounts/create-an-account" target="_top">Create account</a> using your <strong class="slate-bold">client ID</strong> and <strong class="slate-bold">client secret </strong>from the <a href="https://docs.nshiftgo.com/getting-started/signup" target="">signup</a> process.</p><p class="slate-p " >Authentification for accounts need to be verified through a base64 encoded string of <code class="slate-code">client_id:client_secret</code> following <a href="https://swagger.io/docs/specification/v3_0/authentication/" target="">OpenAPI&apos;s securitySchemes and basicAuth</a>, more info on the <a href="https://docs.nshiftgo.com/accounts" target="">Accounts page</a>.</p><h3 class="slate-h3 " ><strong class="slate-bold">Step 2: Issue Token</strong></h3><p class="slate-p " >The <strong class="slate-bold">account ID</strong> received is used as <code class="slate-code">sub</code> using the <a href="https://docs.nshiftgo.com/accounts/issue-a-token-for-an-account" target="_top">Issue Token endpoint</a>.</p><p class="slate-p " ><strong class="slate-bold">Grant type</strong> is always set to “<strong class="slate-bold">client_credentials</strong>”.</p><h3 class="slate-h3 " ><strong class="slate-bold">Step 3: Receive Bearer token</strong></h3><p class="slate-p " >Token returned is used as <strong class="slate-bold">Bearer token</strong> (expiration time 4 h) in subsequent requests to other endpoints.</p><p class="slate-p " >For each account you will need to do some initial configurations.</p><p class="slate-p " >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.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><h1 class="slate-h1 " ><strong class="slate-bold">Setup carrier definition</strong></h1><p class="slate-p " >In order to create shipments you need to add carriers to the account in question through carrier definitions. </p><h3 class="slate-h3 " >Step 1: API Endpoint</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Endpoint</strong>: <strong class="slate-bold">POST /v0/carrier-definitions</strong></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Base URL</strong>: <a href="https://api.nshiftgo.com/" target="_blank"><strong class="slate-bold">https://api.nshiftgo.com</strong></a></div></li></ul><h3 class="slate-h3 " >Step 2: Request Body</h3><p class="slate-p " >The request body must include the necessary details for the carrier definition. Below is an example of the required and optional fields:</p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden">{
  "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"
    }
  ]
} </textarea><code class="language-plainText keep-markup drop-tokens"></code></pre></div><h3 class="slate-h3 " >Step 3: Authentication Header</h3><p class="slate-p " >Add the following header for authentication:</p><p class="slate-p " ><span style="color:rgb(56, 67, 91)"><code class="slate-code">Authorization: Bearer {token}</code></span></p><p class="slate-p " >Replace <strong class="slate-bold">{token}</strong> with your actual bearer token.</p><h3 class="slate-h3 " >Step 4: Content Type</h3><p class="slate-p " >Ensure the <strong class="slate-bold">Content-Type</strong> header is set to <strong class="slate-bold">application/json</strong> to indicate the MIME type of the request body.</p><h3 class="slate-h3 " >Step 5: Request</h3><p class="slate-p " >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.</p><h3 class="slate-h3 " >Step 6: Response</h3><p class="slate-p " >A successful request will return HTTP status <strong class="slate-bold">201 Created</strong> with a JSON response containing the <strong class="slate-bold">id</strong> of the newly created carrier configuration. Handle other HTTP status codes (like <strong class="slate-bold">400 Bad Request</strong>) appropriately based on the API documentation.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><h1 class="slate-h1 " ><strong class="slate-bold">Setup shipment channel</strong></h1><p class="slate-p " >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.</p><h3 class="slate-h3 " ><strong class="slate-bold">Create a New Shipment Channel</strong></h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Endpoint:</strong> <strong class="slate-bold">POST </strong><a href="https://api.nshiftgo.com/shipments/channels" target="_blank"><strong class="slate-bold">https://api.nshiftgo.com/shipments/channels</strong></a></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Content Type:</strong> <strong class="slate-bold">application/json</strong></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Required Headers: Authorization: Bearer {token} </strong>(optional)</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Request Body:</strong></div></li></ul><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden">{
       "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"
       }
     } </textarea><code class="language-plainText keep-markup drop-tokens"></code></pre></div><h3 class="slate-h3 " ><strong class="slate-bold">Update an Existing Shipment Channel</strong></h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Endpoint:</strong> <strong class="slate-bold">PUT </strong><a href="https://api.nshiftgo.com/shipments/channels/%7BchannelId%7D" target="_blank"><strong class="slate-bold">https://api.nshiftgo.com/shipments/channels/{channelId}</strong></a></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Content Type:</strong> <strong class="slate-bold">application/json</strong></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Required Path Parameter: channelId</strong> (UUID of the Shipment Channel)</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Required Headers: Authorization: Bearer {token}</strong> (optional)</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Request Body:</strong> Similar to the creation, but include the <strong class="slate-bold">channelId</strong> in the path and modify the settings as necessary.</div></li></ul><p class="slate-p " ></p><h3 class="slate-h3 " ><strong class="slate-bold">Fetch Existing Shipment Channel</strong></h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Endpoint:</strong> <strong class="slate-bold">GET </strong><a href="https://api.nshiftgo.com/shipments/channels/%7BchannelId%7D" target="_blank"><strong class="slate-bold">https://api.nshiftgo.com/shipments/channels/{channelId}</strong></a></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Content Type:</strong> <strong class="slate-bold">application/json</strong></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Required Path Parameter: channelId</strong> (UUID of the Shipment Channel)</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Required Headers: Authorization: Bearer {token}</strong> (optional)</div></li></ul><p class="slate-p " ></p><h3 class="slate-h3 " ><strong class="slate-bold">Retrieve All Shipment Channels</strong></h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Endpoint:</strong> <strong class="slate-bold">GET </strong><a href="https://api.nshiftgo.com/shipments/channels" target="_blank"><strong class="slate-bold">https://api.nshiftgo.com/shipments/channels</strong></a></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Content Type:</strong> <strong class="slate-bold">application/json</strong></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Query Parameters:</strong> (optional)</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">page</strong>: The page number of results.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">size</strong>: Number of items per page.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Required Headers: Authorization: Bearer {token}</strong> (optional)</div></li></ul><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><h1 class="slate-h1 " ><strong class="slate-bold">Prepare shipment booking</strong></h1><p class="slate-p " >Once you have configured the shipment channel you can start booking shipments.</p><h3 class="slate-h3 " >Step 1: Required Data</h3><p class="slate-p " >Before making a request to create a shipment booking, ensure you have the following information ready:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Shipment Channel</strong>: You need the unique identifier of the Shipment Channel.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Carrier Configuration</strong>: Details like the carrier code, carrier ID, and specific configurations for the carrier.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Parcel Information</strong>: Details about the parcels including dimensions, weight, and any specific parcel items.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Addresses and Parties</strong>: Information about parties involved such as sender, receiver, and any other relevant parties.</div></li></ul><h3 class="slate-h3 " >Step 2: Request Body</h3><p class="slate-p " >Create a JSON/ object that includes all necessary details. Here is a general structure based on the requirements:</p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden">{
  "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
        }
      ]
    }
  ]
} </textarea><code class="language-plainText keep-markup drop-tokens"></code></pre></div><h3 class="slate-h3 " >Step 3: API Request</h3><p class="slate-p " >Send a POST request to the endpoint that handles shipment booking:</p><p class="slate-p " ><code class="slate-code">POST </code><a href="https://api.nshiftgo.com/shipment-booking" target="_self"><code class="slate-code">https://api.nshiftgo.com/shipment-booking</code></a></p><p class="slate-p " >Include the JSON body you&apos;ve constructed in the request. Ensure that the <strong class="slate-bold">Content-Type</strong> header of your request is set to <strong class="slate-bold">application/json</strong>.</p><h3 class="slate-h3 " >Step 4: Response</h3><p class="slate-p " >The API will respond with details of the created shipment booking. Handle the response/ accordingly based on your application&apos;s logic. If successful, the response should contain information about the booked shipment, including any identifiers and status information.</p><h3 class="slate-h3 " >Step 5: Errors</h3><p class="slate-p " >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.</p><h3 class="slate-h3 " >Example CURL Command</h3><p class="slate-p " >Here is an example CURL command to create a shipment booking:</p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden">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": [...]
}' </textarea><code class="language-plainText keep-markup drop-tokens"></code></pre></div><p class="slate-p " >Replace the placeholders and property values with actual data as per your requirements.</p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p>

If you are new to REST APIs then have a look at our 

 to get a good starting point. Below you will find some step-by-step 

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

Authentification for accounts need to be verified through a base64 encoded string of 

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

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

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

DHL Home Delivery

Add the following header for authentication:

 to indicate the MIME type of the request body.

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.

A successful request will return HTTP status 

 of the newly created carrier configuration. Handle other HTTP status codes (like 

) appropriately based on the API documentation.

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.

Channel 1

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

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

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

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

Include the JSON body you've constructed in the request. Ensure that the 

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.

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.

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

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

<p class="slate-p " >We use a set of definitions across our specifications in order to increase understanding and providing consistency. </p><div class="table-container" style="width:60%;
  min-width:60%;"><table class="slate-table" ><div class="published-table-header" style="width:100%;min-width:100%;min-height:initial;visibility: hidden;border:initial"><div style="width:100px;">Title</div><div style="width:100px;">Description</div></div><colgroup ><col style="width:initial"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Terminology</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Meaning</strong></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p slate-indent-1" style="24px">Owner</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >An owner in Go is the legal contract holder with nShift. The owner is holder for the subscription and billing and all 
legal aspects regarding the contract and party to our SLA. We have 4 different owner types depending on the type of agreement they have with nShift:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Business</div></li><li class="slate-li " ><div style="position:relative">Reseller</div></li><li class="slate-li " ><div style="position:relative">Brand</div></li><li class="slate-li " ><div style="position:relative">In-App</div></li></ul></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p slate-indent-1" style="24px">Merchant</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >The owner can provision accounts (according to their agreement) to their own clients/users. We call these Merchants.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p slate-indent-1" style="24px">Account</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >A data isolated entity in our system provisioned by the owner under a Merchant. All data used and stored is associated with an account. Multiple accounts can be provisioned for the same Merchant to provide data isolation for warehousing operations etc.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p slate-indent-1" style="24px">Access Token</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >A token generated using the owner Client ID and Client Secret and the Account ID of the account the token should bear access to. The Client ID and Client Secret are received during Partner Signup.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p slate-indent-1" style="24px">URI Parameter</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >A resource identifier defined in the path segment of the request i.e. &lt;domain-segment&gt;/v1/accounts/<strong class="slate-bold">4c293bf4-5667-44a4-a1a6-669b48a8d6e0</strong>.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p slate-indent-1" style="24px">Query Parameter</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >A variable passed in a request using the query segment i.e. &lt;path-segment&gt;?<strong class="slate-bold">sort=asc</strong>.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p slate-indent-1" style="24px">Body Parameter</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >A field in the JSON request payload i.e.

{
<strong class="slate-bold">  “id”: &quot;4c293bf4-5667-44a4-a1a6-669b48a8d6e0&quot;</strong>
}</p></td></div></tr></tbody></table></div><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p>

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

Title

Description

<h2 class="slate-h2 " >What is a REST API?</h2><p class="slate-p " >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.</p><p class="slate-p " ></p><h2 class="slate-h2 " >AOS 3.0 Specifications</h2><p class="slate-p " >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&apos;s capabilities, limitations, and protocols, promoting a seamless integration and reliable operation.</p><p class="slate-p " ></p><h2 class="slate-h2 " >Error Responses</h2><p class="slate-p " >Our API conforms to RFC 9457 (<a href="https://datatracker.ietf.org/doc/html/rfc9457" target="_top">https://datatracker.ietf.org/doc/html/rfc9457</a>) for reporting problems within HTTP responses. </p><p class="slate-p " >This standard helps in structuring error messages consistently across our API, making it easier for clients to understand and diagnose issues. </p><p class="slate-p " >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. </p><p class="slate-p " >This information aids developers in quickly identifying the problem and finding a resolution.</p><p class="slate-p " ></p><h2 class="slate-h2 " >Syntactical Standards</h2><p class="slate-p " >We adhere to the JSON Schema Validation vocabulary to define the structure of our JSON data. </p><p class="slate-p " >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. </p><p class="slate-p " >By enforcing these standards, we maintain high data integrity and facilitate smooth data interchange between systems.</p><p class="slate-p " ></p><h3 class="slate-h3 " >URL Definitions</h3><p class="slate-p " >Our API follows a set of URL design principles to ensure they are intuitive, consistent, and easily scalable:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Resource names</strong>: Always use pluralized nouns for resources (e.g., <code class="slate-code">/users</code>).</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Resource identifiers</strong>: Use URL-friendly identifiers for resources, typically UUID values.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Path segments</strong>: Utilize kebab-case for path segments (e.g., <code class="slate-code">/new-orders</code>).</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Property names</strong>: Property names in payloads are to be in camelCase (e.g., <code class="slate-code">userName</code>).</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Query parameters</strong>: Always use snake_case for query parameters (e.g., <code class="slate-code">start_date</code>).</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Normalized paths</strong>: URLs should be normalized, omitting empty path segments and trailing slashes.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Verb-free URLs</strong>: Keep URLs focused on resources rather than actions.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Null and absent properties</strong>: Treat null and absent properties with the same semantics. Avoid using null for boolean properties; instead, use true or false.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Array names</strong>: Pluralize names of array properties to reflect multiple values (e.g., <code class="slate-code">phoneNumbers</code>).</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Enum values</strong>: Declare enum values using UPPER_SNAKE_CASE (e.g., <code class="slate-code">STATUS_ACTIVE</code>).</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Entity identifiers</strong>: Define identifiers of entities as UUID values to ensure uniqueness.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Pagination</strong>: Implement cursor-based pagination to manage data retrieval efficiently and securely.</div></li></ul><p class="slate-p " >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.</p><p class="slate-p " ></p>

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.

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.

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

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.

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

Sections