nShift Go Documentation

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.

Accounts should be created for each individual merchant. This is also the only data isolation layer we have, meaning if you need to separate activity between e.g. stores or warehouses etc. and manage access you need to setup as many accounts as you require.

Each account will hold it's own data including settings, personal information etc. and you will need to issue individual access tokens per account.

Authentication for accounts need to be verified through a base64 encoded string of client_id:client_secret following OpenAPI's securitySchemes and basicAuth.

PLAINTEXT

"securitySchemes" : {
         "basicAuth" : {
            "description" : "Basic Authentication, `base64(client_id:secret)`",
            "scheme" : "basic",
            "type" : "http"
         },
         "bearerToken" : {
            "bearerFormat" : "Bearer <token>",
            "description" : "Use the `/authorize` endpoint to get a token.",
            "scheme" : "bearer",
            "type" : "http"
         }
      }    "securitySchemes" : {
         "basicAuth" : {
            "description" : "Basic Authentication, `base64(client_id:secret)`",
            "scheme" : "basic",
            "type" : "http"
         },
         "bearerToken" : {
            "bearerFormat" : "Bearer <token>",
            "description" : "Use the `/authorize` endpoint to get a token.",
            "scheme" : "bearer",
            "type" : "http"
         }
      }

Production:

https://api.nshiftgo.com

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.

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.

Header Parameters

Authorizationstring

Body Parameters

addressLinesarray Required

A list of address line objects.

Min items

1

Show child attributes

buildingNumberstring

Building number or name.

citystring

City name is autocompleted, if omitted, based on countryCode and postalCode if possible.

companyobject

Information about the company associated with the Address.

Show child attributes

contactobject

Contact information associated with the Address.

Show child attributes

countryCodestring Required

An 'ISO 3166-1 alpha-2' defined country code e.g. 'SE', 'UK', 'DE' etc. Pattern ^[A-Z]{2}$

Pattern

^[A-Z]{2}$

Enum values:

ADAEAFAGAIALAMAOAQAR

... 239 other enums

groupstring

The group can be used to group addresses together.

Pattern

^\w+$

postalCodestring Required

The country specific postal.

referencesobject

A field for providing a references e.g. identifiers for both internal and external systems.

Show child attributes

regionCodestring

An 'ISO 3166-1 alpha-2' defined region/district code e.g. 'US-DC' (District of Columbia) etc.

stateCodestring

An 'ISO 3166-1 alpha-2' defined state code e.g. 'US-AL' (Alabama) etc.

Response

201

Object

Created

Response Attributes

idstring (uuid)

The unique identifier of the resource.

400

Object

Bad Request

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

The type of error

401

Object

Unauthorized

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

The type of error

422

Object

Validation error

Response Attributes

typestring (uri-reference)Required

The type of error

titlestring Required

detailstring

statusstring (int32)Required

instancestring (uri-reference)

errorsarray

Show child attributes

500

Object

Internal Server Error

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

curl --location 'https://api.nshiftgo.com/v0/addresses' \
--header 'Authorization: Basic <base64-encoded string>' \
--data-raw '{
  "addressLines": [
    {
      "type": "STREET_NAME",
      "value": "Schillerstraße"
    }
  ],
  "buildingNumber": "13",
  "city": "Washington DC",
  "company": {
    "customsNumber": "",
    "doorCode": "",
    "dunsNumber": "",
    "einNumber": "12-3456789",
    "eoriNumber": "SE556546371701",
    "fdaNumber": "",
    "iossNumber": "",
    "name": "nShift",
    "organizationNumber": "5565463717",
    "sprnNumber": "",
    "vatNumber": "SE556546371701"
  },
  "contact": {
    "email": "jdoe@nshift.com",
    "fax": "+4670000000",
    "firstName": "John",
    "lastName": "Doe",
    "mobile": "+4670000000",
    "phone": "+4670000000",
    "preferredLanguage": "EN"
  },
  "countryCode": "US",
  "group": "warehouse",
  "postalCode": "111111",
  "references": {
    "external": "PRT_987654-321",
    "internal": "1234567-7890-12"
  },
  "regionCode": "US_DC",
  "stateCode": "US_WA"
}'

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}

Update an existing Address with new information by using its unique identifier addressId.

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

Header Parameters

Authorizationstring

Path Parameters

addressIdstring (uuid)Required

The Address ID

Body Parameters

addressLinesarray Required

A list of address line objects.

Min items

1

Show child attributes

buildingNumberstring

Building number or name.

citystring

City name is autocompleted, if omitted, based on countryCode and postalCode if possible.

companyobject

Information about the company associated with the Address.

Show child attributes

contactobject

Contact information associated with the Address.

Show child attributes

countryCodestring Required

An 'ISO 3166-1 alpha-2' defined country code e.g. 'SE', 'UK', 'DE' etc. Pattern ^[A-Z]{2}$

Pattern

^[A-Z]{2}$

Enum values:

ADAEAFAGAIALAMAOAQAR

... 239 other enums

groupstring

The group can be used to group addresses together.

Pattern

^\w+$

postalCodestring Required

The country specific postal.

referencesobject

A field for providing a references e.g. identifiers for both internal and external systems.

Show child attributes

regionCodestring

An 'ISO 3166-1 alpha-2' defined region/district code e.g. 'US-DC' (District of Columbia) etc.

stateCodestring

An 'ISO 3166-1 alpha-2' defined state code e.g. 'US-AL' (Alabama) etc.

Response

204

Object

No content

400

Object

Bad Request

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

The type of error

401

Object

Unauthorized

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

The type of error

404

Object

Not found

Response Attributes

detailstring

errorsarray

Show child attributes

instancestring (uri-reference)

statusstring (int32)Required

titlestring Required

typestring (uri-reference)Required

The type of error

422

Object

Validation error

Response Attributes

typestring (uri-reference)Required

The type of error

titlestring Required

detailstring

statusstring (int32)Required

instancestring (uri-reference)

errorsarray

Show child attributes

500

Object

Internal Server Error

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

200

Object

Successfully updated Address

Response Attributes

idstring

curl --location --globoff --request PUT 'https://api.nshiftgo.com/v0/addresses/{addressId}' \
--header 'Authorization: Basic <base64-encoded string>' \
--data-raw '{
  "addressLines": [
    {
      "type": "STREET_NAME",
      "value": "Schillerstraße"
    }
  ],
  "buildingNumber": "13",
  "city": "Washington DC",
  "company": {
    "customsNumber": "",
    "doorCode": "",
    "dunsNumber": "",
    "einNumber": "12-3456789",
    "eoriNumber": "SE556546371701",
    "fdaNumber": "",
    "iossNumber": "",
    "name": "nShift",
    "organizationNumber": "5565463717",
    "sprnNumber": "",
    "vatNumber": "SE556546371701"
  },
  "contact": {
    "email": "jdoe@nshift.com",
    "fax": "+4670000000",
    "firstName": "John",
    "lastName": "Doe",
    "mobile": "+4670000000",
    "phone": "+4670000000",
    "preferredLanguage": "EN"
  },
  "countryCode": "US",
  "group": "warehouse",
  "postalCode": "111111",
  "references": {
    "external": "PRT_987654-321",
    "internal": "1234567-7890-12"
  },
  "regionCode": "US_DC",
  "stateCode": "US_WA"
}'

No content

Remove an existing Address by using its unique identifier addressId.

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

Header Parameters

Authorizationstring

Path Parameters

addressIdstring (uuid)Required

The Address ID

Response

204

Object

No Content

400

Object

Bad request

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

The type of error

401

Object

Unauthorized

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

The type of error

404

Object

Not Found

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

The type of error

422

Object

Validation error

Response Attributes

typestring (uri-reference)Required

The type of error

titlestring Required

detailstring

statusstring (int32)Required

instancestring (uri-reference)

errorsarray

Show child attributes

500

Object

Internal Server Error

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

1
2

curl --location --globoff --request DELETE 'https://api.nshiftgo.com/v0/addresses/{addressId}' \
--header 'Authorization: Basic <base64-encoded string>' \

No Content

Retrieve an existing Address by using its unique identifier addressId.

Header Parameters

Authorizationstring

Path Parameters

addressIdstring (uuid)Required

The Address ID

Response

200

Object

Success

Response Attributes

addressLinesarray

A list of address line objects.

Show child attributes

buildingNumberstring

Building number or name.

citystring

City name is autocompleted, if omitted, based on countryCode and postalCode if possible.

companyobject

Information about the company associated with the Address.

Show child attributes

contactobject

Contact information associated with the Address.

Show child attributes

countryCodestring

Enum values:

ADAEAFAGAIALAMAOAQAR

... 239 other enums

createdAtstring (date-time)

The date and time when the Address was created.

groupstring

The group can be used to group addresses together.

idstring (uuid)

The unique identifier of the Address.

postalCodestring

The country specific postal.

referencesobject

A field for providing a references e.g. identifiers for both internal and external systems.

Show child attributes

regionCodestring

An 'ISO 3166-1 alpha-2' defined region/district code e.g. 'US-DC' (District of Columbia) etc.

stateCodestring

An 'ISO 3166-1 alpha-2' defined state code e.g. 'US-AL' (Alabama) etc.

updatedAtstring (date-time)

The date and time when the Address was last updated.

400

Object

Bad request

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

The type of error

401

Object

Unauthorized

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

The type of error

404

Object

Not Found

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

The type of error

422

Object

Validation error

Response Attributes

typestring (uri-reference)Required

The type of error

titlestring Required

detailstring

statusstring (int32)Required

instancestring (uri-reference)

errorsarray

Show child attributes

500

Object

Internal Server Error

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

1
2

curl --location --globoff 'https://api.nshiftgo.com/v0/addresses/{addressId}' \
--header 'Authorization: Basic <base64-encoded string>' \

{
  "addressLines": [
    {
      "type": "STREET_NAME",
      "value": "Schillerstraße"
    }
  ],
  "buildingNumber": "13",
  "city": "Washington DC",
  "company": {
    "customsNumber": "",
    "doorCode": "",
    "dunsNumber": "",
    "einNumber": "",
    "eoriNumber": "SE556546371701",
    "fdaNumber": "",
    "iossNumber": "",
    "name": "nShift",
    "organizationNumber": "5565463717",
    "sprnNumber": "",
    "vatNumber": "SE556546371701"
  },
  "contact": {
    "email": "jdoe@nshift.com",
    "fax": "+4670000000",
    "firstName": "John",
    "lastName": "Doe",
    "mobile": "+4670000000",
    "phone": "+4670000000",
    "preferredLanguage": "EN"
  },
  "countryCode": "AD",
  "createdAt": "2021-09-01T12:00:00+02:00",
  "group": "warehouse",
  "id": "12345678-1234-1234-1234-123456789012",
  "postalCode": "111111",
  "references": {
    "external": "PRT_987654-321",
    "internal": "1234567-7890-12"
  },
  "regionCode": "US_DC",
  "stateCode": "US_WA",
  "updatedAt": "2021-09-01T12:00:00+02:00"
}

Lists all existing Addresses stored on the account.

Header Parameters

Authorizationstring

Query Parameters

queryParametersobject Required

Response

200

Object

Successful operation

Response Attributes

itemsarray

Show child attributes

nextCursorstring (uuid)

The next cursor to be used for the next page.

400

Object

Bad Request

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

401

Object

Unauthorized

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

404

Object

Not Found

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

500

Object

Internal Server Error

Response Attributes

detailstring

instancestring (uri)

propertiesobject

statusinteger (int32)

titlestring

typestring (uri)

1
2

curl --location 'https://api.nshiftgo.com/v0/addresses?queryParameters=' \
--header 'Authorization: Basic <base64-encoded string>' \

{
  "items": [
    {
      "addressLines": [
        {
          "type": "STREET_NAME",
          "value": "Schillerstraße"
        }
      ],
      "buildingNumber": "13",
      "city": "Washington DC",
      "company": {
        "customsNumber": "",
        "doorCode": "",
        "dunsNumber": "",
        "einNumber": "",
        "eoriNumber": "SE556546371701",
        "fdaNumber": "",
        "iossNumber": "",
        "name": "nShift",
        "organizationNumber": "5565463717",
        "sprnNumber": "",
        "vatNumber": "SE556546371701"
      },
      "contact": {
        "email": "jdoe@nshift.com",
        "fax": "+4670000000",
        "firstName": "John",
        "lastName": "Doe",
        "mobile": "+4670000000",
        "phone": "+4670000000",
        "preferredLanguage": "EN"
      },
      "countryCode": "AD",
      "createdAt": "2021-09-01T12:00:00+02:00",
      "group": "warehouse",
      "id": "12345678-1234-1234-1234-123456789012",
      "postalCode": "111111",
      "references": {
        "external": "PRT_987654-321",
        "internal": "1234567-7890-12"
      },
      "regionCode": "US_DC",
      "stateCode": "US_WA",
      "updatedAt": "2021-09-01T12:00:00+02:00"
    }
  ],
  "nextCursor": "12345678-1234-1234-1234-123456789012"
}

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.

Shipping quotes are generated from delivery options. Once the delivery options are configured you can evaluate them and the system will automatically generate relevant shipping quotes. The quotes will only persist for 24 hours after which they are removed from our system.

Production:

https://api.nshiftgo.com

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.

Sections

Getting Started

Welcome to nShift!

API

Mission

What is nShift Go?

Accounts

Language Box

cURL

Ruby

Python

PHP

Java

Node.js

Go

.NET

Addresses

What made this section unhelpful for you?

Create Address

Header Parameters

Body ParametersExpand all

... 239 other enums

ResponseExpand all

Response Attributes

Response Attributes

Response Attributes

Response Attributes

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Update Address

Header Parameters

Path Parameters

Body ParametersExpand all

... 239 other enums

ResponseExpand all

Response Attributes

Response Attributes

Response Attributes

Response Attributes

Response Attributes

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Delete Address

Header Parameters

Path Parameters

ResponseExpand all

Response Attributes

Response Attributes

Response Attributes

Response Attributes

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Fetch Address

Header Parameters

Path Parameters

ResponseExpand all

Response Attributes

... 239 other enums

Response Attributes

Response Attributes

Response Attributes

Response Attributes

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

List Addresses

Header Parameters

Query Parameters

ResponseExpand all

Response Attributes

Response Attributes

Response Attributes

Response Attributes

Body Parameters

Response

Body Parameters

Response

Response

Response

Response