Documentation

Integrate with Ingrid

Ingrid typically builds integrations tailored to specific carriers but we also make it possible for carriers to integrate with us.

From checkout to tracking, the following documentation provides you with everything needed for a complete integration with Ingrid.

Diagram

Ingrid Carrier Integration Sequence Diagram

Endpoints

1. Fetch access token

POST /oauth/token

Request body:

{
"client_id": "client_id_value",
"client_secret": "client_secret_value"
}

NOTE: ideally there should be only one set of credentials granted for Ingrid that would work for every merchant that books with us

Response body:

{
"access_token": "access_token_value",
"scope": "general", // should always be set to general
"token_type": "Bearer", // should always be set to Bearer
"expires_in": 3600 // in seconds
}

2. Fetch shipping options

POST /shipping-options

This request is made when the customer buys something at the merchant's e-commerce portal and then presented with the delivery options during the checkout step

Headers:

Request body:

{
"shipping_method": "velove-std", // id of the product within Ingrid. Not important for carriers that have only one product
"parties": {
// Address of the merchant's warehouse
"from": {
"address": {
"name": "Test Merchant",
"care_of": "",
"address_lines": [
"Test warehouse street 15"
],
"city": "Kalmar",
"postal_code": "39357",
"country": "SE"
}
},
// Address that customer types in when checking available delivery options
// Usually is empty outside of postal code and country
"search": {
// Maximum amount of pickup points in the response
"location_limit": 25,
// Can be used to exclude some pickup points from the response
"location_types": ["locker", "postoffice", "manned", "store"],
// Maximum radius in kilometers, only relevant for pickup points
"location_radius": 15.42,
"address": {
"name": "Test Testson",
"care_of": "",
"address_lines": [
"Test street 1"
],
"city": "Kalmar",
"postal_code": "39356",
"country": "SE"
}
},
// Customer's home address if provided
"customer": {
"phone": "+48000000000",
"email": "customer@ingrid.com",
"address": {
"name": "Test Testson",
"care_of": "",
"address_lines": [
"Test street 1"
],
"city": "Kalmar",
"postal_code": "39356",
"country": "SE"
}
},
"shipper": {
"id": "id of the merchant" // id that uniquely identifies the merchant on the carrier's end
}
},
"pickup_time": { // expected time range when parcel is going to picked up from the merchant's warehouse by the carrier
"start": "2023-07-30T23:30:00Z",
"end": "2023-07-30T23:30:00Z"
},
"references": {
"cart_id": "ID of the checkout cart"
}
}

Response body (success, http code 200)

{
// Multiple timeslots are supported in case if the carrier allows the customer to select preferred delivery time slot
"delivery_times": [
{
"start": "2023-07-31T17:30:00Z",
"end": "2023-07-31T18:30:00Z"
},
{
"start": "2023-07-31T20:30:00Z",
"end": "2023-07-31T21:30:00Z"
}
],
// Relevant only for products that support delivery to pickup points (post office, locker etc)
"delivery_locations": [
{
// Unique identifier of the pickup point needed for booking
"id": "9101",
"address": {
"name": "Rīgas T/C Akropole pakomāts",
"care_of": "",
"address_lines": [
"Maskavas iela 257"
],
"city": "Rīga",
"postal_code": "LV-9101",
"country": "LV",
// Mandatory, needed to present pickup point on the map
"coordinates": {
"lat": 56.9238129,
"lng": 24.1752396
}
},
// locker|postoffice|manned|store
"location_type": "locker",
"opening_hours": [
{
"day": 1, // Sunday = 0, Monday = 1, Tuesday = 2 ...
"start": "T08:00+02:00",
"end": "T11:00+02:00"
},
{
"day": 1,
"start": "T12:00+02:00",
"end": "T23:59+02:00"
},
{
"day": 2,
"start": "T08:00+02:00",
"end": "T23:59+02:00"
},
]
}
]
}

Response body (bad request, http code >=400)

{
"errors": [
{
"message": "provided postal code is not covered"
}
]
}

3. Pre-booking

POST /prebooking

This request is sent when the customer completes checkout session from within merchant's e-commerce portal

Headers:

Request body:

{
"shipping_method": "velove-std", // id of the product within Ingrid. Not important for carriers that have only one product
"parties": {
"from": {
"address": {
"name": "Test Merchant",
"care_of": "",
"address_lines": [
"Test warehouse street 15"
],
"city": "Kalmar",
"postal_code": "39357",
"country": "SE"
}
},
"to": {
"id": "", // id of the pickup point in case if delivery is done to pre-selected pickup point, empty otherwise
"address": { // Usually the same as the customer.address unless it is a delivery to some pre-selected pickup point
"name": "Test Testson",
"care_of": "",
"address_lines": [
"Test street 1"
],
"city": "Kalmar",
"postal_code": "39356",
"country": "SE"
}
},
"customer": {
"phone": "+48000000000",
"email": "customer@ingrid.com",
"address": {
"name": "Test Testson",
"care_of": "",
"address_lines": [
"Test street 1"
],
"city": "Kalmar",
"postal_code": "39356",
"country": "SE"
}
},
"shipper": {
"id": "id of the merchant" // id that uniquely identifies the merchant on the carrier's end
}
},
"delivery_time": { // expected time range when parcel is going to be delivered to the end receiver. Usually this time range is selected from the checkout widget by the receiver themselves
"start": "2023-07-31T23:30:00Z",
"end": "2023-07-31T23:30:00Z"
},
"references": {
"tos_id": "01H6AAXCB6S6K679DPEC38TPMR", // ID of the TOS order in Ingrid, can be used for pre-booking purposes, TOS orders are created when checkout session is completed
"external_id": "Order 001" // ID of the order/shipment provided by the merchant
}
}

Response body (success, http code 200)

{
}

Response body (bad request, http code >=400)

{
"errors": [
{
"message": "delivery time must not be in the past"
}
]
}

4. Book shipment

This request is sent when shipment is booked at the merchant's warehouse by their WMS

POST /booking

Headers:

Request body:

{
"shipping_method": "velove-std", // id of the product within Ingrid. Not important for carriers that have only one product
"parties": {
"from": {
"address": {
"name": "Test Merchant",
"care_of": "",
"address_lines": [
"Test warehouse street 15"
],
"city": "Kalmar",
"postal_code": "39357",
"country": "SE"
}
},
"to": {
"id": "", // id of the pickup point in case if delivery is done to pre-selected pickup point, empty otherwise
"address": { // Usually the same as the customer.address unless it is a return shipment or delivery to some pre-selected pickup point
"name": "Test Testson",
"care_of": "",
"address_lines": [
"Test street 1"
],
"city": "Kalmar",
"postal_code": "39356",
"country": "SE"
}
},
"customer": {
"phone": "+48000000000",
"email": "customer@ingrid.com",
"address": {
"name": "Test Testson",
"care_of": "",
"address_lines": [
"Test street 1"
],
"city": "Kalmar",
"postal_code": "39356",
"country": "SE"
}
},
"shipper": {
"id": "id of the merchant" // id that uniquely identifies the merchant on the carrier's end
}
},
"delivery_time": { // expected time range when parcel is going to be delivered to the end receiver. Usually this time range is selected from the checkout widget by the receiver themselves
"start": "2023-07-31T23:30:00Z",
"end": "2023-07-31T23:30:00Z"
},
"delivery_instructions": "", // Additional instructions for the courier
"print_config": {
"label_format": "pdf", // pdf|zpl - it is enough to support only one of these formats
"label_size": "normal" // normal|small
},
"references": {
"tos_id": "01H6AAXCB6S6K679DPEC38TPMR", // ID of the TOS order in Ingrid, can be used for pre-booking purposes, TOS orders are created when checkout session is completed
"external_id": "Order 001" // ID of the order/shipment provided by the merchant
},
"packages": [
{
"references": {
"package_id": "delivery 1 uuid"
},
"weight": 15000, // in grams
"dimensions": {
"height": 150, // in millimeters
"length": 200, // in millimeters
"width": 300 // in millimeters
}
}
],
"addons": [
"take_signature",
"id_check",
"age_check_16",
"age_check_18",
"age_check_21"
],
// outbound|return
"direction_type": "outbound"
}

Response body (success, http code 200)

{
"packages": [
{
"barcode": "tracking number",
"label_data": "bGFiZWwgZGF0YQ=="
}
]
}

Response body (bad request, http code >=400)

{
"errors": [
{
"message": "label format ZPL is not supported"
},
{
"message": "delivery time must not be in the past"
}
]
}

5. Cancel shipment

This request is sent when the merchant wants to cancel shipment via their WMS or Ingrid's TA

DELETE /booking/packages/:barcode

Headers:

Request body: -

Response body (success, http code 200)

{
}

Response body (bad request, http code >=400)

{
"errors": [
{
"message": "package was not found"
}
]
}

6. Tracking

Tracking is implemented via webhook exposed by Ingrid

POST https://api.ingrid.com/v1/integrations/:carrier/update.status?site_id=:site_id

where

Headers:

where

Request body:

{
"barcode": "tracking number",
"shipping_method": "velove-std", // id of the product within Ingrid
"shipper_id": "id of the merchant", // id that uniquely identifies the merchant on the carrier's end
"event_status": "submitted", // free text, any status will be accepted. At Ingrid we will do our best to map those statuses to our internal statuses
"event_time": "2023-07-31T23:30:00Z",
"estimated_arrival_time": { // Optional, can be ommited
"start": "2023-07-31T23:30:00Z",
"end": "2023-07-31T23:30:00Z"
}
}

Response body (success, http code 200)

{
}

Response body (bad request, http code >=400)

{
"errors": [
{
"message": "invalid or missing authorization header"
}
]
}

Last updated: Fri, Jul 12, 06:15 AM