Introduction
Shadow Booking allows you to add shipments booked outside nShift to the nShift platform without booking them again.
This enables you to use nShift Track and other available features, even when shipments are created using a different book and print solution.
With Shadow Booking, you can:
- Consolidate shipment data from multiple shipping systems.
- Track shipments booked outside nShift.
- Receive carrier tracking events and shipment status updates.
- Use nShift Track features such as notifications and reporting.
- Gain better visibility across your shipping operations.
There are two ways to create Shadow Bookings:
- Delivery Cloud API – Add externally booked shipments directly to nShift Portal.
- Shipment Server API (POST ShadowShipments) – Add externally booked shipments through nShift Ship.
Both methods allow you to make externally booked shipments available for tracking without creating a new booking with the carrier.
Option 1: Create Shadow Bookings using Delivery Cloud API
With Delivery Cloud API, you can send shipments directly to nShift Portal, where they can be used with nShift Track and other supported services.
This option is particularly useful if you:
- Use multiple book and print solutions.
- Have shipments created by external warehouses or dropshipping partners.
- Use a non-nShift shipping solution but want to use nShift Track.
- Want to consolidate shipment data in nShift Portal.
- Want to use additional services such as nShift Emissions Tracker.
Getting started
To create Shadow Bookings using Delivery Cloud API, follow these steps:
Step 1: Set up Delivery Cloud in nShift Portal
Log in to nShift Portal and navigate to Settings > Company Management > Delivery Cloud Configuration.
Create an Organization Unit and Member Account specifically for Delivery Cloud.
Save the Organization ID and Member Account ID, as you will need them when making API requests.
If Delivery Cloud Configuration is not available, contact nShift Customer Service to have it activated.
Step 2: Create API credentials
In nShift Portal, navigate to Settings > API Configuration > Clients.
Create a new API client and select Portal Shipment Data API under Allowed Scopes.
Save the generated Client ID and Client Secret.
Step 3: Authenticate
Use your Client ID and Client Secret to request an access token.
POST https://account.nshiftportal.com/idp/connect/token
The access token must be included in the Authorization header of subsequent API requests.
Step 4: Retrieve carrier and service information
Before creating a shipment, retrieve the relevant carrier and service IDs using the API.
GET /metadata/carriers
GET /metadata/carriers/{carrierId}/services
GET /metadata/carriers/{carrierId}/addonsThe addons endpoint is optional if your shipment does not use any addons.
Step 5: Create the shipment
Once you have identified the correct carrier and service, you can add your externally booked shipment using:
PUT /shipments
Include the required shipment information and use the Member Account ID as the accountId.
The shipment will be added to nShift Portal without making a new carrier booking.
Delivery Cloud API documentation
For detailed setup instructions, authentication examples, and guidance on creating shipments, see:
The technical documentation contains endpoint descriptions, request parameters, and API schemas.
Option 2: Create Shadow Bookings using Shipment Server API (POST ShadowShipments)
You can also create Shadow Bookings using the Shipment Server API in nShift Ship.
This method allows you to create a copy of a shipment that has already been booked outside nShift.
When a shipment is created using POST ShadowShipments:
- The shipment is added directly to the Sent section in nShift Ship with the status Transmitted.
- The normal submit and transmit processes are bypassed.
- No carrier booking or routing API calls are triggered.
- Carrier validations are disabled.
- No shipping labels are generated.
- No automatic check-digit calculations or barcode prefix additions are performed.
Implementation
Use the following endpoint to create a Shadow Booking:
POST {{URL}}/ShipServer/{{ID}}/ShadowShipmentsWhere:
- URL is the Shipment Server API base URL.
-
ID is the ID of the actor against which the request is executed.
Request body
The request body must be an application/json object containing data and options.
{
"data": {},
"options": {}
}As a minimum, the shipment data must include:
- Shipment number, package number, or both.
- SubmitDate.
- TransmitDate.
- PickupDate.
Although these fields may be sufficient for some carriers, it is generally necessary to provide the same shipment information required for a normal booking, including the carrier service used.
For more information about the required shipment structure, see the existing Shadow Booking documentation and the Shipment Server API documentation.
Important considerations for carrier tracking
Regardless of which method you use, it is important that the shipment information matches the data used by the carrier.
To receive tracking events successfully, nShift must be able to identify the shipment when processing the carrier's return data.
Correct shipment and package numbers
Make sure you provide the correct barcode or tracking number.
Some carriers use package numbers rather than shipment numbers to identify shipments. Others may include or exclude check digits or prefixes.
The value provided must match the format used by the carrier in its tracking events.
Additional matching information
Some carriers use additional information, such as order numbers or account numbers, to match shipments.
When using the Shipment Server API, these values may need to be supplied in the fields PortalBarcode1 (ReferenceKind 279) or PortalBarcode2 (ReferenceKind 280).
Carrier return data compatibility
Not all carrier return data formats are supported.
Some carriers provide customer-specific return data formats that may differ from those supported by nShift.
Even if a carrier is available in the nShift carrier library, this does not necessarily mean that all return data formats are compatible.
If the carrier cannot provide a compatible return data format, tracking events may not be available for your Shadow Bookings.
Further information
- Getting started with Delivery Cloud API
- Delivery Cloud API technical documentation – Theneo
- Shipment Server API documentation
If you have any questions or need assistance setting up Shadow Bookings, please contact our support team.