Integration Guide

This part of the documentation will guide you through the steps of integrating with the Ingrid tracking solution. It consists of two parts:

installing and displaying Ingrid Delivery Tracking Widget on your page,
using Ingrid hosted Tracking Page,
providing orders for Ingrid to track.
using Ingrid Tracking API.

Using correct endpoints for integration

Make sure that you are using correct endpoints when using different environments for testing and production releases.

To use Tracking Widget and Tracking Page on stage environment, use following base urls:

https://api-stage.ingrid.com/,
https://cdn-stage.ingrid.com/,
https://tracking-stage.ingrid.com/

Tracking Widget should be embedded in a site controlled by Merchant. The most common scenario is a dedicated tracking page within Merchant's domain and built by Merchant specifically to host Tracking Widget. A link to this tracking page with an embedded Tracking Widget is subsequently given to the Customer.

Flow for the Merchant

Load Tracking Widget code:

<script src="https://cdn.ingrid.com/delivery-tracking/bootstrap.js"></script>

Select which element of the page should be the widget container and give it a unique id. For example:

<div id="delivery-tracking-widget"></div>

Note

There are two options for initializing Tracking Widget: search mode and private mode. Search mode is being used to display a search form where the end-user can search for their package. Private mode displays full information about the given package.

After the script is loaded, initialize Tracking Widget using JavaScript. To initialize search mode use the renderSearchMode method:

window.IngridDeliveryTrackingWidgetApi.renderSearchMode({
  containerId: string,
  locale: string,
  siteId: string,
});

If you want to render private mode use the renderPrivateMode method:

window.IngridDeliveryTrackingWidgetApi.renderPrivateMode({
  containerId: string,
  locale: string,
  siteId: string,
  identifier: string,
  contact: string,
});

After calling the respective method to render mode Tracking Widget should appear on the page

IngridDeliveryTrackingWidgetApi

Search mode

IngridDeliveryTrackingWidgetApi.renderSearchMode function expects as argument an options object with 2 required properties:

containerId: HTML id of the container to inject the tracking widget into
siteId: Id of the site (use IMP to get your siteId)

Optional properties are:

locale: Adjusts the language - by default, the widget will use en-US. See Supported Languages.
prefillIdentifier: either tracking number for parcel or external id for order. Used to prefill the form
prefillContact: either end customer telephone number or email. Used to prefill the form

Private mode

IngridDeliveryTrackingWidgetApi.renderPrivateMode function expects as argument an options object with 4 required properties:

containerId: HTML id of the container to inject the tracking widget into
siteId: Id of the site (use IMP to get your siteId)
identifier: either tracking number for parcel or external id for order
contact: either end customer telephone number or email

Optional property is:

locale: Adjusts the language - by default, the widget will use en-US. See Supported Languages.

Passing arguments to IngridDeliveryTrackingWidgetApi

It is up to you how you pass arguments to IngridDeliveryTrackingWidgetApi but we recommend that you take identifier and contact from query parameters.

For example, the link to your site can look like this:

https://tracking/?identifier=<TRACKING_NUMBER>&contact=<CONTACT>

Then you can extract identifier and contact from query paramaters:

const params = new URLSearchParams(window.location.search);
const identifier = params.get("identifier");
const contact = params.get("contact");

// for search mode
window.IngridDeliveryTrackingWidgetApi.renderSearchMode({
  containerId: "delivery-tracking-widget",
  siteId: "YOUR_SITE_ID_FROM_IMP",
  prefillId: identifier,
  prefillContact: contact,
});

// or for private mode
window.IngridDeliveryTrackingWidgetApi.renderPrivateMode({
  containerId: "delivery-tracking-widget",
  siteId: "YOUR_SITE_ID_FROM_IMP",
  identifier,
  contact,
});

Currently we provide mode_change event when user switches from search mode to private mode and vice versa. You can use following snippet to listen to mode_change:

window.IngridDeliveryTrackingWidgetApi.on("mode_changed", containerId, (event) => {
  console.log(`Mode changed for ${containerId} with event:`, event);
});

on function takes 3 arguments:

event_type - currently only mode_change is supported
containerId - HTML id of widget container (the same you use to embed widget)
event handler - function with one argument of {to: 'search|private'} object that indicates to what widget mode user switched

Ingrid hosted portal and page

You can use Ingrid hosted portal and page by going into Ingrid Tracking Portal. Portal consists of two parts:

Portal - is a place where end-user can search for their packages
Page - is a place where the end-user will get information about a specific package

Flow for the merchant

If you need to send the end customer to the Ingrid portal you can use the following link:

https://tracking.ingrid.com/

You can add two query parameters (prefillContact and perfill_id) to the URL if you want to prefill search on the tracking portal

https://tracking.ingrid.com/?prefillContact=<EMAIL/PHONE>&prefillIdentifier=<ORDER/TRACKING NUMBER>

Link to tracking portal can be localized by adding locale after .ingrid.com part:

https://tracking.ingrid.com/<LOCALE>/

Note

Ingrid Tracking page can be accessed in two ways: public view and private view. The public view is easier to integrate but the end-user will need to provide an email or phone number in the widget. The private view is harder to integrate but end-user does not need to do anything if they want to see tracking info.

Link to public view is created by taking Ingrid Transport Order Id (TOS id) and adding /order/<TRANSPORT_ORDER_ID> to URL:

https://tracking.ingrid.com/order/<TRANSPORT_ORDER_ID>

Link to public Tracking page can be localized by adding locale after .ingrid.com part:

https://tracking.ingrid.com/<LOCALE>/order/<TRANSPORT_ORDER_ID>

Link to private Tracking page can be generated using our API:

POST v1/delivery_tracking/generate_tracking_page_link
Host: api.ingrid.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer base64-encoded-api-token

{
    "locale": "en-US",
    "order_id": "592978",
    "site_id": "11756e4a98c64fa9a9c5d627fd88a236"
}

Parameter locale will adjusts the language of Page. See Supported Languages.

You can also specify tracking number in body request:

POST v1/delivery_tracking/generate_tracking_page_link
Host: api.ingrid.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer base64-encoded-api-token

{
    "locale": "en-US",
    "tracking_number": "BST000079234",
    "site_id": "11756e4a98c64fa9a9c5d627fd88a236"
}

Generate tracking page link

Either tracking_number or order_id can be added to JSON request for generating private tracking page. Passing both of them at the same time will result in an error.

In response you will get full link with token to Ingrid Tracking Page:

HTTP/1.1 200 OK
Date: Tue, 10 May 2022 13:25:51 GMT
Content-Type: application/json

Connection: close
Vary: Accept-Encoding
x-trace-id: D20220314132550W4T98CK0A6AEQ72X

{
  "tracking_link": "tracking.ingrid.com/en-US/TOKEN"
}

Supported Languages

The following locales are supported:

Czech - cs-CZ
Danish - da-DK
Dutch - nl-NL
English (Australia) - en-AU
English (Canada) - en-CA
English (Ireland) - en-IE
English (United States) - en-US
English (Great Britain) - en-GB
Estonian - et-EE
French - fr-FR
Finnish (Finland) - fi-FI
Finnish (Sweden) - fi-SE
German - de-DE
Greek - el-GR
Croatian - hr-HR
Icelandic - is-IS
Italian - it-IT
Japanese - ja-JP
Korean - ko-KR
Lithuanian - lt-LT
Norwegian Bokmål - nb-NO
Norwegian Nynorsk - nn-NO
Norwegian - no-NO
Polish - pl-PL
Portuguese - pt-PT
Russian - ru-RU
Slovak - sk-SK
Slovenian - sl-SI
Spanish - es-ES
Swedish (Finland) - sv-FI
Swedish (Sweden) - sv-SE

Providing orders to track

Note

When using Ingrid Transport Automation all of your shipments will be automatically visible in the Ingrid tracking solution and you can skip that section.

If you are using an external system for booking your orders you can still track them using Ingrid Tracking Widget. The one thing we need you to do to is to post the tracking number you got from your external booking system and specify the order number (external_id or tos_id) together with the carrier product that was used for booking.

To send an externally booked order to the Ingrid system you should do a POST request to v1/events_gateway/events.registerTrackingNumber.

POST v1/events_gateway/events.registerTrackingNumber HTTP/1.1
Host: api.ingrid.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer base64-encoded-api-token

{
  "tracking_number": "BST000185540",
  "external_id": "592978",
  "carrier_product_ref": "postnord-mypack-collect",
  "direction_type": "OUTBOUND"
}

POST v1/events_gateway/events.registerTrackingNumber HTTP/1.1
Host: api.ingrid.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer base64-encoded-api-token

{
  "tracking_number": "BST000185540",
  "tos_id": "01G51NDWW1NCPNV2MV5WMB0H6A",
  "carrier_product_ref": "postnord-mypack-collect",
  "direction_type": "OUTBOUND"
}

Order identification

When providing external_id keep in mind that it should match external_id provided in Delivery Checkout, otherwise we won't be able to connect those orders, and Deliver Tracking experience will be degraded.

Specifying a concrete carrier product used for booking can be tricky as each party or system usually operates based on self-made identifiers. That is why Ingrid created a mechanism that makes the integration easier by allowing any integrator to reuse its own internal naming while being precise about the carrier product - see carrier product mapping.

direction_type is an optional field, that holds information about the initial package direction. This information helps us to show you the most accurate list on MAD and also helps to serve the best tracking experience for your customers. This field is especially important when you are registering not only outbound parcels but also return one - e.g. you are booking a return shipment and want to register it in our system.

Carrier product mapping

carrier_product_ref is a carrier product reference from an external system that is mapped in Ingrid and indicates which carrier product has been used.

This reference can be any string, but it should be the same for all orders booked with the same carrier product.

Each time you start using a new carrier product, it needs to be mapped in order to enable tracking for it. Mappings can be created in the Ingrid Merchant Platform (Delivery Tracking > Features) and there are two ways to do it - you can use one of the carrier products already defined by Ingrid, or create a custom configuration.

Using existing carrier product

This is how the configuration window looks like:

Mapping existing carrier product

Here you can enter your carrier product reference and select the corresponding carrier product. After selecting your desired carrier product, you will be able to see the status of the Ingrid tracking integration for this product - is it available and does it need some additional configuration. Even if it's not, don't worry - in that case, Ingrid will show the carrier's tracking links instead.

Creating custom mapping

If your desired carrier product isn't contained in Ingrid's list of available products, or if you want to show custom tracking links, you may want to create a custom mapping. Here is how to do it:

Adding custom mapping

If you need, you can add separate URLs for every locale.

Note

Every custom URL needs to contain a <tracking_number> placeholder. It will be filled with the shipment's tracking number by Ingrid.

Ingrid Tracking API

For all custom integrations based on data from tracking, Ingrid provides a dedicated API. In order to get the current tracking status of parcels you need to make a GET request to v1/delivery_tracking/parcels. This request can be made using one of the two identifiers.

Identifiers

Either tracking_number or external_id must be provided in the request. Passing both of them at the same time will result in an error.

Using tracking number

When a tracking number is passed in the request, the API will return only the status of the parcel it identifies based on that tracking number.

POST /v1/delivery_tracking/parcels?tracking_number=<tracking_number> HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <base64-encoded-api-token>

HTTP/1.1 200 OK
Date: Fri, 28 Oct 2022 16:07:11 GMT
Content-Type: application/json
Content-Length: 656
Vary: Accept-Encoding

{
    "parcels": [
        {
            "tracking_number": <tracking_number>,
            "current_progress": {
                "step": "STEP_DELIVERED_TO_CONSUMER",
                "time": "2022-10-28T15:10:04Z"
            },
            "progress_history": [
                {
                    "step": "STEP_DELIVERED_TO_CONSUMER",
                    "time": "2022-10-28T15:10:04Z"
                },
                {
                    "step": "STEP_ON_ROUTE",
                    "time": "2022-10-28T15:10:04Z"
                },
                {
                    "step": "STEP_SUBMITTED_TO_CARRIER",
                    "time": "2022-10-28T14:29:20Z"
                },
                {
                    "step": "STEP_PREPARED_BY_MERCHANT",
                    "time": "2022-10-28T10:13:44Z"
                },
                {
                    "step": "STEP_CONFIRMED_BY_MERCHANT",
                    "time": "2022-10-17T22:01:45Z"
                }
            ],
            "carrier_name": "Airmee"
        }
    ],
    "external_id": <external_id>,
    "tracking_link": <tracking_link>
}

Using external identifier

When an external identifier of the order (external_id) is used instead of the tracking number, the API will return all parcels that have been created for that order.

POST /v1/delivery_tracking/parcels?external_id=<external_id> HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <base64-encoded-api-token>

HTTP/1.1 200 OK
Date: Fri, 28 Oct 2022 16:07:11 GMT
Content-Type: application/json
Content-Length: 1156
Vary: Accept-Encoding

{
    "parcels": [
        {
            "tracking_number": <tracking_number_1>,
            "current_progress": {
                "step": "STEP_DELIVERED_TO_CONSUMER",
                "time": "2022-10-28T15:10:04Z"
            },
            "progress_history": [
                {
                    "step": "STEP_DELIVERED_TO_CONSUMER",
                    "time": "2022-10-28T15:10:04Z"
                },
                {
                    "step": "STEP_ON_ROUTE",
                    "time": "2022-10-28T15:10:04Z"
                },
                {
                    "step": "STEP_SUBMITTED_TO_CARRIER",
                    "time": "2022-10-28T14:29:20Z"
                },
                {
                    "step": "STEP_PREPARED_BY_MERCHANT",
                    "time": "2022-10-27T05:55:45Z"
                },
                {
                    "step": "STEP_CONFIRMED_BY_MERCHANT",
                    "time": "2022-10-17T22:01:45Z"
                }
            ],
            "carrier_name": "Airmee"
        },
        {
            "tracking_number": <tracking_number_2>,
            "current_progress": {
                "step": "STEP_DELIVERED_TO_CONSUMER",
                "time": "2022-10-28T15:10:04Z"
            },
            "progress_history": [
                {
                    "step": "STEP_DELIVERED_TO_CONSUMER",
                    "time": "2022-10-28T15:10:04Z"
                },
                {
                    "step": "STEP_ON_ROUTE",
                    "time": "2022-10-28T15:10:04Z"
                },
                {
                    "step": "STEP_SUBMITTED_TO_CARRIER",
                    "time": "2022-10-28T14:29:20Z"
                },
                {
                    "step": "STEP_PREPARED_BY_MERCHANT",
                    "time": "2022-10-28T10:13:44Z"
                },
                {
                    "step": "STEP_CONFIRMED_BY_MERCHANT",
                    "time": "2022-10-17T22:01:45Z"
                }
            ],
            "carrier_name": "Airmee"
        }
    ],
    "external_id": <external_id>,
    "tracking_link": <tracking_link>
}

Last updated: Thu, Dec 08, 06:15 AM

Integration Guide

Installing Delivery Tracking Widget

Flow for the Merchant

IngridDeliveryTrackingWidgetApi

Search mode

Private mode

Passing arguments to IngridDeliveryTrackingWidgetApi

Listening to events emitted by widget

Ingrid hosted portal and page

Flow for the merchant

Supported Languages

Providing orders to track

Carrier product mapping

Using existing carrier product

Creating custom mapping

Ingrid Tracking API

Using tracking number

Using external identifier