SOM Consolidated Shipment API

A consolidated shipment is a logistics solution that allows multiple smaller shipments to be combined into a larger shipment, often referred to as "groupage", "bulk split", "mother-shipment", "line haul". This approach optimizes outbound logistics and enhances efficiency in shipping processes. This method is supported by certain carriers, contact Ingrid for list of supported carriers.

Key Features of Consolidated Shipments:

Consolidation: Multiple shipments are combined into a single shipment for efficiency.
Carrier Support: Currently implemented for specific carriers, with plans for broader integration.
API Integration: A general API has been created to support all current carrier bulk shipments, allowing for easier integration by merchants.

Domain Model

The domain model consists of three important objects - Shipment, Parcel and Delivery.

graph LR s(Shipments) p(Parcels) d(Deliveries) cs(Consolidated Shipments) pa(Pallets) cs-- has many -->s; cs-- has many -->pa; s-- has many -->p; p-- has many -->d;

General Flow

Creating a Shipment, generating labels and tracking numbers and booking pickup involves three simple steps: Opening a consolidated shipment, booking "child"-shipments with a reference to the consolidated shipment using the regular SOM api but with a reference to the consolidated shipment, and finally calling consolidated_shipment.book. Booking will generate shipping documents, labels and tracking numbers for the consolidated shipment

sequenceDiagram participant C as Client participant S as SOM C->>S: POST /consolidated_shipment.open S->>C: Returns consolidated shipment C->>S: POST /shipments.createAndBook S->>C: Return Shipment with Parcels and Deliveries C->>S: POST /shipments.createAndBook S->>C: Return Shipment with Parcels and Deliveries C->>S: POST /consolidated_shipment.book S->>C: Returns labels, shipping and customs documents, and tracking numbers

Open Consolidated Shipment

This call creates new consolidated shipment

Request 🔗

POST /v1/som/consolidated_shipments.open HTTP/1.1
Host: api.ingrid.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer base64-encoded-api-token

{
  "external_id": "ext-123",
  "from": {
    "address": {
      "name": "Acme, Main Warehouse",
      "address_lines": [
        "Frihamnsgatan 56"
      ],
      "postal_code": "11556",
      "city": "Stockholm",
      "country": "SE"
    }
  },
  "meta": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "shipping_date": "2025-04-29T09:03:47.845Z",
  "shipping_method": "brn-bulksplit",
  "to": {
    "address": {
      "name": "Coop Extra Sandnes",
      "address_lines": [
        "Elvegata 11"
      ],
      "postal_code": "4306",
      "city": "Sandnes",
      "country": "NO"
    }
  }
}

Response 🔗

HTTP/1.1 200 OK
Date: Tue, 29 Apr 2025 09:03:48 GMT
Content-Type: application/json
Content-Length: 468
Connection: close
Vary: Accept-Encoding
x-trace-id: S20250429090347EC5QZZSCGWG2SJPG

{
  "consolidated_shipment": {
    "id": "e9a04733-1256-4984-b4c2-bbbef1944b66",
    "site_id": "11756e4a98c64fa9a9c5d627fd88a236",
    "shipping_method": "brn-bulksplit",
    "shipping_date": "2025-04-29T09:03:47Z",
    "from": {
      "address": {
        "name": "Acme, Main Warehouse",
        "address_lines": [
          "Frihamnsgatan 56"
        ],
        "city": "Stockholm",
        "postal_code": "11556",
        "country": "SE"
      }
    },
    "to": {
      "address": {
        "name": "Coop Extra Sandnes",
        "address_lines": [
          "Elvegata 11"
        ],
        "city": "Sandnes",
        "postal_code": "4306",
        "country": "NO"
      }
    },
    "external_id": "ext-123",
    "meta": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "tracking_number": "CL312500608NO",
    "created_at": "2025-04-29T09:03:48Z",
    "updated_at": "2025-04-29T09:03:48Z"
  }
}

POST /v1/som/consolidated_shipments.book HTTP/1.1
Host: api.ingrid.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer base64-encoded-api-token

{
  "consolidated_shipment_id": "e9a04733-1256-4984-b4c2-bbbef1944b66",
  "meta": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "pallets": [
    {
      "dimensions": {
        "height": "5",
        "length": "5",
        "width": "5"
      },
      "external_id": "ext-123",
      "shipping_methods": [
        "pnl-bpp"
      ],
      "weight": "12345"
    }
  ]
}

Response 🔗

HTTP/1.1 200 OK
Date: Tue, 29 Apr 2025 09:03:57 GMT
Content-Type: application/json
Content-Length: 296
Connection: close
Vary: Accept-Encoding
x-trace-id: S202504290903499272EQZGN92QVE92

{
  "consolidated_shipment": {
    "id": "e9a04733-1256-4984-b4c2-bbbef1944b66",
    "site_id": "11756e4a98c64fa9a9c5d627fd88a236",
    "shipping_method": "brn-bulksplit",
    "shipping_date": "2025-04-29T09:03:47Z",
    "from": {
      "address": {
        "name": "Acme, Main Warehouse",
        "address_lines": [
          "Frihamnsgatan 56"
        ],
        "city": "Stockholm",
        "postal_code": "11556",
        "country": "SE"
      }
    },
    "to": {
      "address": {
        "name": "Coop Extra Sandnes",
        "address_lines": [
          "Elvegata 11"
        ],
        "city": "Sandnes",
        "postal_code": "4306",
        "country": "NO"
      }
    },
    "external_id": "ext-123",
    "meta": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "documents": [
      {
        "name": "cmr.pdf",
        "url": "https://api.ingrid.com/v1/blobs/?file=generate_file.pdf",
        "id": "CL312500608NO",
        "type": "CMR"
      }
    ],
    "pallets": [
      {
        "id": "ac6f53d2-3dee-466d-87c8-59cdb6d87a23",
        "external_id": "ext-123",
        "weight": "12345",
        "dimensions": {
          "length": "5",
          "height": "5",
          "width": "5"
        },
        "tracking_number": "CL117900730NO",
        "label_url": "https://api.ingrid.com/v1/labels/path-to-generated-label.svg"
      }
    ],
    "created_at": "2025-04-29T09:03:48Z",
    "updated_at": "2025-04-29T09:03:57Z"
  }
}

Get Consolidated Shipment

This call fetches a consolidated shipment

Request

GET /v1/som/consolidated_shipments.get?consolidated_shipment_id=e9a04733-1256-4984-b4c2-bbbef1944b66 HTTP/1.1
Host: api.ingrid.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer base64-encoded-api-token

Response 🔗

HTTP/1.1 200 OK
Date: Tue, 29 Apr 2025 09:03:49 GMT
Content-Type: application/json

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

{
  "consolidated_shipment": {
    "id": "e9a04733-1256-4984-b4c2-bbbef1944b66",
    "site_id": "11756e4a98c64fa9a9c5d627fd88a236",
    "shipping_method": "brn-bulksplit",
    "shipping_date": "2025-04-29T09:03:47Z",
    "from": {
      "address": {
        "name": "Acme, Main Warehouse",
        "address_lines": [
          "Frihamnsgatan 56"
        ],
        "city": "Stockholm",
        "postal_code": "11556",
        "country": "SE"
      }
    },
    "to": {
      "address": {
        "name": "Coop Extra Sandnes",
        "address_lines": [
          "Elvegata 11"
        ],
        "city": "Sandnes",
        "postal_code": "4306",
        "country": "NO"
      }
    },
    "external_id": "ext-123",
    "meta": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "tracking_number": "CL312500608NO",
    "created_at": "2025-04-29T09:03:48Z",
    "updated_at": "2025-04-29T09:03:48Z"
  }
}

Last updated: Wed, May 07, 06:15 AM

SOM Consolidated Shipment API

Domain Model

General Flow

Open Consolidated Shipment

Request 🔗

Response 🔗

Book Child Shipments

How to remove a Child Shipment

Book Consolidated Shipment

Request 🔗

Response 🔗

Get Consolidated Shipment

Request

Response 🔗