Documentation

SOM API

SOM is responsible for shipment order management. Booking and tracking of the shipments, parcels and deliveries. Below are the endpoints (or methods) available.

Domain Model

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

graph LR s(Shipment) p(Parcels) d(Deliveries) s-- has many -->p; p-- has many -->d;

General Flow

Creating a Shipment, generating labels and tracking numbers and booking pickup involves three steps.

sequenceDiagram participant C as Client participant S as SOM C->>S: POST /shipments.create S->>C: Return Shipment with Parcels and Deliveries C->>S: POST /shipment.bookParcels S->>C: Return Shipment with Parcels and Deliveries C->>S: POST /deliveries.bookPickup S->>C: Return Delivery
  1. Create a shipment. Shipment, Parcels and Deliveries are created with a single call to shipments.create.
  2. To generate labels and tracking numbers for a Shipment, call shipments.bookParcels. This will create labels and tracking numbers for all Deliveries in the specified Shipment.
  3. The final step is to book one or all Deliveries attached to a Shipment. This is done by calling deliveries.bookPickup with the tracking number as a parameter. Once a delivery has been booked, it is handled by our booking service which will most often generate and upload an EDI file at a configured interval.

Create Shipment

This call creates new shipment, parcels and deliveries at once in SOM. So called Composite Shipment.

tos_id

If you already use our Delivery Checkout solution we highly recommend to provide tos_id in CreateShipment request, in order to connect Shipment with Order. In this case, you don't have to provide all the shipment details, Ingrid will take all the required data for the shipment from the Order. But you still will have a possibility to override TOS Order data with the data you would give in the CreateShipment request.

address_return

Provide address_return in the CreateShipment request in case you want to override a default return address. A default return address is taken from the sender address ("address_from") which is usually the address of your warehouse.

Use case:
An outbound shipment is made from Sweden to Norway, however, you want an inbound shipment (return shipment) to be delivered back to Norway (your hub or warehouse). In this case, you need to provide a Norwegian address in the address return field.

Request 🔗

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

{
  "tos_id": "01G1QDS00DVDJ6190NZBCCV229",
  "shipping_method": "pnl-mpc",
  "shipment_value": 19900,
  "shipping_date": "2022-07-29T09:08:36.499Z",
  "number_of_parcels": 1,
  "external_id": "ACME12345",
  "location_ref": "3806098",
  "customer_info": {
    "name": "Erik Johansson",
    "email": "erik@example.com",
    "phone": "0761234561",
    "address": {
      "care_of": "Anders Ekman",
      "address_lines": [
        "Elvegata 12"
      ],
      "city": "Sandnes",
      "postal_code": "4306",
      "country": "NO"
    }
  },
  "address_to": {
    "name": "Coop Extra Sandnes",
    "address_lines": [
      "Elvegata 11"
    ],
    "postal_code": "4306",
    "city": "Sandnes",
    "country": "NO"
  },
  "address_from": {
    "name": "Acme, Main Warehouse",
    "address_lines": [
      "Frihamnsgatan 56"
    ],
    "postal_code": "11556",
    "city": "Stockholm",
    "country": "SE"
  },
  "address_return": {
    "name": "Acme, Norway Warehouse",
    "address_lines": [
      "Bestumåsen 190"
    ],
    "postal_code": "0281",
    "city": "Oslo",
    "country": "NO"
  },
  "contents": {
    "goods": [
      {
        "sku": "SKU12345",
        "name": "Saucony Shadow 6000",
        "quantity": 1,
        "weight": 720,
        "dimensions": {
          "length": 600,
          "width": 300,
          "height": 250
        },
        "tags": [
          "shoes",
          "indigo",
          "class_one"
        ]
      }
    ]
  },
  "meta": {
    "is_fragile": "true"
  },
  "direction_type": "OUTBOUND"
}

Response 🔗

HTTP/1.1 200 OK
Date: Fri, 29 Jul 2022 09:08:36 GMT
Content-Type: application/json
Content-Length: 1068
Connection: close
Vary: Accept-Encoding
x-trace-id: S2022072909083681PTEQ5HST9BSYAK

{
  "shipment": {
    "id": "4ce3db05-6b57-4d68-bfdd-871a0fbd8b90",
    "site_id": "11756e4a98c64fa9a9c5d627fd88a236",
    "customer_info": {
      "address": {
        "care_of": "Anders Ekman",
        "address_lines": [
          "Elvegata 12"
        ],
        "city": "Sandnes",
        "postal_code": "4306",
        "country": "NO"
      },
      "phone": "0761234561",
      "email": "erik@example.com"
    },
    "meta": {
      "is_fragile": "true"
    },
    "shipping_date": "2022-07-29T09:08:36Z",
    "address_from": {
      "name": "Acme, Main Warehouse",
      "address_lines": [
        "Frihamnsgatan 56"
      ],
      "city": "Stockholm",
      "postal_code": "11556",
      "country": "SE"
    },
    "address_to": {
      "name": "Coop Extra Sandnes",
      "address_lines": [
        "Elvegata 11"
      ],
      "city": "Sandnes",
      "postal_code": "4306",
      "country": "NO"
    },
    "address_return": {
      "name": "Acme, Norway Warehouse",
      "address_lines": [
        "Bestumåsen 190"
      ],
      "city": "Oslo",
      "postal_code": "0281",
      "country": "NO"
    },
    "line_items": [
      {
        "sku": "SKU12345",
        "name": "Saucony Shadow 6000",
        "quantity": "1",
        "dimensions": {
          "length": "600",
          "height": "250",
          "width": "300"
        },
        "tags": [
          "shoes",
          "indigo",
          "class_one"
        ],
        "weight": "720"
      }
    ],
    "parcels": [
      {
        "id": "2d77928d-55c5-4402-968c-e89c7c0526c2",
        "shipment_id": "4ce3db05-6b57-4d68-bfdd-871a0fbd8b90",
        "line_items": [
          {
            "sku": "SKU12345",
            "name": "Saucony Shadow 6000",
            "quantity": "1",
            "dimensions": {
              "length": "600",
              "height": "250",
              "width": "300"
            }
          }
        ],
        "deliveries": [
          {
            "id": "c63bbfd5-a374-4ba9-bd7f-53273f1045b0",
            "parcel_id": "2d77928d-55c5-4402-968c-e89c7c0526c2",
            "address_from": {
              "name": "Acme, Main Warehouse",
              "address_lines": [
                "Frihamnsgatan 56"
              ],
              "city": "Stockholm",
              "postal_code": "11556",
              "country": "SE"
            },
            "address_to": {
              "name": "Coop Extra Sandnes",
              "address_lines": [
                "Elvegata 11"
              ],
              "city": "Sandnes",
              "postal_code": "4306",
              "country": "NO"
            },
            "shipping_method": "pnl-mpc",
            "location_ref": "3806098",
            "delivery_status": "created",
            "address_return": {
              "name": "Acme, Norway Warehouse",
              "address_lines": [
                "Bestumåsen 190"
              ],
              "city": "Oslo",
              "postal_code": "0281",
              "country": "NO"
            },
            "created_at": "2022-07-29T09:08:36Z",
            "updated_at": "2022-07-29T09:08:36Z"
          }
        ],
        "created_at": "2022-07-29T09:08:37Z",
        "updated_at": "2022-07-29T09:08:37Z",
        "dimensions": {
          "length": "600",
          "height": "250",
          "width": "300"
        },
        "weight": "720"
      }
    ],
    "external_id": "ACME12345",
    "shipment_value": "19900",
    "tos_id": "01G1QDS00DVDJ6190NZBCCV229",
    "contents": {
      "goods": [
        {
          "sku": "SKU12345",
          "name": "Saucony Shadow 6000",
          "quantity": "1",
          "dimensions": {
            "length": "600",
            "height": "250",
            "width": "300"
          },
          "tags": [
            "shoes",
            "indigo",
            "class_one"
          ],
          "weight": "720"
        }
      ]
    },
    "created_at": "2022-07-29T09:08:37Z",
    "updated_at": "2022-07-29T09:08:37Z",
    "direction_type": "OUTBOUND"
  }
}

Book Parcels

Creates a booking with the shipping company. This is when tracking numbers, tracking links and shipping labels are generated.

Request 🔗

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

{
  "shipment_id": "4ce3db05-6b57-4d68-bfdd-871a0fbd8b90"
}

Response 🔗

HTTP/1.1 200 OK
Date: Fri, 29 Jul 2022 09:08:37 GMT
Content-Type: application/json
Content-Length: 54
Connection: close
Vary: Accept-Encoding
x-trace-id: S20220729090836H4KJ6XH1NRRGXNBA

{
  "shipment": {
    "id": "4ce3db05-6b57-4d68-bfdd-871a0fbd8b90",
    "site_id": "11756e4a98c64fa9a9c5d627fd88a236",
    "customer_info": {
      "address": {
        "care_of": "Anders Ekman",
        "address_lines": [
          "Elvegata 12"
        ],
        "city": "Sandnes",
        "postal_code": "4306",
        "country": "NO"
      },
      "phone": "0761234561",
      "email": "erik@example.com"
    },
    "meta": {
      "is_fragile": "true"
    },
    "shipping_date": "2022-07-29T09:08:36Z",
    "address_from": {
      "name": "Acme, Main Warehouse",
      "address_lines": [
        "Frihamnsgatan 56"
      ],
      "city": "Stockholm",
      "postal_code": "11556",
      "country": "SE"
    },
    "address_to": {
      "name": "Coop Extra Sandnes",
      "address_lines": [
        "Elvegata 11"
      ],
      "city": "Sandnes",
      "postal_code": "4306",
      "country": "NO"
    },
    "address_return": {
      "name": "Acme, Norway Warehouse",
      "address_lines": [
        "Bestumåsen 190"
      ],
      "city": "Oslo",
      "postal_code": "0281",
      "country": "NO"
    },
    "line_items": [
      {
        "sku": "SKU12345",
        "name": "Saucony Shadow 6000",
        "quantity": "1",
        "dimensions": {
          "length": "600",
          "height": "250",
          "width": "300"
        },
        "tags": [
          "shoes",
          "indigo",
          "class_one"
        ],
        "weight": "720"
      }
    ],
    "parcels": [
      {
        "id": "2d77928d-55c5-4402-968c-e89c7c0526c2",
        "shipment_id": "4ce3db05-6b57-4d68-bfdd-871a0fbd8b90",
        "line_items": [
          {
            "sku": "SKU12345",
            "name": "Saucony Shadow 6000",
            "quantity": "1",
            "dimensions": {
              "length": "600",
              "height": "250",
              "width": "300"
            }
          }
        ],
        "deliveries": [
          {
            "id": "c63bbfd5-a374-4ba9-bd7f-53273f1045b0",
            "parcel_id": "2d77928d-55c5-4402-968c-e89c7c0526c2",
            "tracking_number": "00033333333000138729",
            "label_url": "https://api.ingrid.com/v1/labels/path-to-generated-label.svg",
            "address_from": {
              "name": "Acme, Main Warehouse",
              "address_lines": [
                "Frihamnsgatan 56"
              ],
              "city": "Stockholm",
              "postal_code": "11556",
              "country": "SE"
            },
            "address_to": {
              "name": "Coop Extra Sandnes",
              "address_lines": [
                "Elvegata 11"
              ],
              "city": "Sandnes",
              "postal_code": "4306",
              "country": "NO"
            },
            "shipping_method": "pnl-mpc",
            "location_ref": "3806098",
            "delivery_status": "booked",
            "address_return": {
              "name": "Acme, Norway Warehouse",
              "address_lines": [
                "Bestumåsen 190"
              ],
              "city": "Oslo",
              "postal_code": "0281",
              "country": "NO"
            },
            "tracking_url": "https://tracking.postnord.com/NO?id=00033333333000138729",
            "created_at": "2022-07-29T09:08:36Z",
            "updated_at": "2022-07-29T09:08:37Z",
            "delivery_time": {
              "start": "0001-01-01T00:00:00Z",
              "end": "2022-07-29T09:08:36Z"
            }
          }
        ],
        "created_at": "2022-07-29T09:08:37Z",
        "updated_at": "2022-07-29T09:08:37Z",
        "dimensions": {
          "length": "600",
          "height": "250",
          "width": "300"
        },
        "weight": "720"
      }
    ],
    "external_id": "ACME12345",
    "shipment_value": "19900",
    "tos_id": "01G1QDS00DVDJ6190NZBCCV229",
    "contents": {
      "goods": [
        {
          "sku": "SKU12345",
          "name": "Saucony Shadow 6000",
          "quantity": "1",
          "dimensions": {
            "length": "600",
            "height": "250",
            "width": "300"
          },
          "tags": [
            "shoes",
            "indigo",
            "class_one"
          ],
          "weight": "720"
        }
      ]
    },
    "created_at": "2022-07-29T09:08:37Z",
    "updated_at": "2022-07-29T09:08:37Z",
    "direction_type": "OUTBOUND"
  }
}

Book Pickup

When the shipment has received tracking numbers and labels it is time to book pickup. This call makes the actual booking and and notifies the shipping company about the delivery.

Request 🔗

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

{
  "tracking_number": "00033333333000138705"
}

Response 🔗

HTTP/1.1 200 OK
Date: Fri, 29 Jul 2022 09:08:35 GMT
Content-Type: application/json
Content-Length: 42
Connection: close
Vary: Accept-Encoding
x-trace-id: S202207290908359GDDJ9AH388J9FMR

{
  "delivery": {
    "id": "82d02bd1-2104-4d1c-854a-6c99171a6d7b",
    "parcel_id": "866ed2e4-d289-4506-a615-1607b7a6bbcd",
    "tracking_number": "00033333333000138705",
    "label_url": "https://api.ingrid.com/v1/labels/path-to-generated-label.svg",
    "address_from": {
      "name": "Acme, Main Warehouse",
      "address_lines": [
        "Frihamnsgatan 56"
      ],
      "city": "Stockholm",
      "postal_code": "11556",
      "country": "SE"
    },
    "address_to": {
      "name": "Coop Extra Sandnes",
      "address_lines": [
        "Elvegata 11"
      ],
      "city": "Sandnes",
      "postal_code": "4306",
      "country": "NO"
    },
    "shipping_method": "pnl-mpc",
    "location_ref": "3806098",
    "delivery_status": "pickup",
    "address_return": {
      "name": "Acme, Norway Warehouse",
      "address_lines": [
        "Bestumåsen 190"
      ],
      "city": "Oslo",
      "postal_code": "0281",
      "country": "NO"
    },
    "tracking_url": "https://tracking.postnord.com/NO?id=00033333333000138705",
    "created_at": "2022-07-29T09:08:34Z",
    "updated_at": "2022-07-29T09:08:35Z",
    "delivery_time": {
      "start": "0001-01-01T00:00:00Z",
      "end": "2022-07-29T09:08:34Z"
    }
  }
}

Get Delivery

Request 🔗

GET /v1/som/deliveries.get?tracking_number=00033333333000138705 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: Fri, 29 Jul 2022 09:08:35 GMT
Content-Type: application/json

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

{
  "delivery": {
    "id": "82d02bd1-2104-4d1c-854a-6c99171a6d7b",
    "parcel_id": "866ed2e4-d289-4506-a615-1607b7a6bbcd",
    "tracking_number": "00033333333000138705",
    "label_url": "https://api.ingrid.com/v1/labels/path-to-generated-label.svg",
    "address_from": {
      "name": "Acme, Main Warehouse",
      "address_lines": [
        "Frihamnsgatan 56"
      ],
      "city": "Stockholm",
      "postal_code": "11556",
      "country": "SE"
    },
    "address_to": {
      "name": "Coop Extra Sandnes",
      "address_lines": [
        "Elvegata 11"
      ],
      "city": "Sandnes",
      "postal_code": "4306",
      "country": "NO"
    },
    "shipping_method": "pnl-mpc",
    "location_ref": "3806098",
    "delivery_status": "pickup",
    "address_return": {
      "name": "Acme, Norway Warehouse",
      "address_lines": [
        "Bestumåsen 190"
      ],
      "city": "Oslo",
      "postal_code": "0281",
      "country": "NO"
    },
    "tracking_url": "https://tracking.postnord.com/NO?id=00033333333000138705",
    "created_at": "2022-07-29T09:08:34Z",
    "updated_at": "2022-07-29T09:08:35Z",
    "delivery_time": {
      "start": "0001-01-01T00:00:00Z",
      "end": "2022-07-29T09:08:34Z"
    }
  }
}

Create and Book

Create and book shipment is essentially a wrapper for the three calls shipments.create, shipments.bookParcels and deliveries.bookPickup. It will create a shipment, generate labels and tracking numbers and finally book the created deliveries for pickup, all in one single call.

Request 🔗

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

{
  "shipping_method": "pnl-mpc",
  "shipment_value": 19900,
  "shipping_date": "2022-07-29T09:08:35.888Z",
  "number_of_parcels": 1,
  "external_id": "ACME12345",
  "location_ref": "592971",
  "customer_info": {
    "name": "Erik Johansson",
    "email": "erik@example.com",
    "phone": "0761234561",
    "address": {
      "care_of": "Anders Ekman",
      "address_lines": [
        "Industrigatan 5"
      ],
      "city": "Stockholm",
      "postal_code": "11239",
      "country": "SE"
    }
  },
  "address_to": {
    "name": "ICA Västermalmsgallerian",
    "address_lines": [
      "S:t Eriksgatan 45"
    ],
    "city": "Stockholm",
    "postal_code": "11234",
    "country": "SE"
  },
  "address_from": {
    "name": "Acme, Main Warehouse",
    "address_lines": [
      "Frihamnsgatan 56"
    ],
    "postal_code": "11556",
    "city": "Stockholm",
    "country": "SE"
  },
  "contents": {
    "goods": [
      {
        "sku": "SKU12345",
        "name": "Saucony Shadow 6000",
        "quantity": 1,
        "weight": 720,
        "dimensions": {
          "length": 600,
          "width": 300,
          "height": 250
        },
        "tags": [
          "shoes",
          "indigo",
          "class_one"
        ]
      }
    ]
  },
  "meta": {
    "is_fragile": "true"
  },
  "direction_type": "OUTBOUND"
}

Response 🔗

HTTP/1.1 200 OK
Date: Fri, 29 Jul 2022 09:08:36 GMT
Content-Type: application/json
Content-Length: 915
Connection: close
Vary: Accept-Encoding
x-trace-id: S20220729090836CZWGRPBXBRTYPJZF

{
  "shipment": {
    "id": "6b2db67e-27a3-4873-a6d2-35759027c1f3",
    "site_id": "11756e4a98c64fa9a9c5d627fd88a236",
    "customer_info": {
      "address": {
        "care_of": "Anders Ekman",
        "address_lines": [
          "Industrigatan 5"
        ],
        "city": "Stockholm",
        "postal_code": "11239",
        "country": "SE"
      },
      "phone": "0761234561",
      "email": "erik@example.com"
    },
    "meta": {
      "is_fragile": "true"
    },
    "shipping_date": "2022-07-29T09:08:35Z",
    "address_from": {
      "name": "Acme, Main Warehouse",
      "address_lines": [
        "Frihamnsgatan 56"
      ],
      "city": "Stockholm",
      "postal_code": "11556",
      "country": "SE"
    },
    "address_to": {
      "name": "ICA Västermalmsgallerian",
      "address_lines": [
        "S:t Eriksgatan 45"
      ],
      "city": "Stockholm",
      "postal_code": "11234",
      "country": "SE"
    },
    "line_items": [
      {
        "sku": "SKU12345",
        "name": "Saucony Shadow 6000",
        "quantity": "1",
        "dimensions": {
          "length": "600",
          "height": "250",
          "width": "300"
        },
        "tags": [
          "shoes",
          "indigo",
          "class_one"
        ],
        "weight": "720"
      }
    ],
    "parcels": [
      {
        "id": "ae3ecfe1-cacc-4e17-84c9-0c12ef2e47e8",
        "shipment_id": "6b2db67e-27a3-4873-a6d2-35759027c1f3",
        "line_items": [
          {
            "sku": "SKU12345",
            "name": "Saucony Shadow 6000",
            "quantity": "1",
            "dimensions": {
              "length": "600",
              "height": "250",
              "width": "300"
            }
          }
        ],
        "deliveries": [
          {
            "id": "2f8163a3-33a2-4514-b977-1784fa23107c",
            "parcel_id": "ae3ecfe1-cacc-4e17-84c9-0c12ef2e47e8",
            "tracking_number": "00033333333000138712",
            "label_url": "https://api.ingrid.com/v1/labels/path-to-generated-label.svg",
            "address_from": {
              "name": "Acme, Main Warehouse",
              "address_lines": [
                "Frihamnsgatan 56"
              ],
              "city": "Stockholm",
              "postal_code": "11556",
              "country": "SE"
            },
            "address_to": {
              "name": "ICA Västermalmsgallerian",
              "address_lines": [
                "S:t Eriksgatan 45"
              ],
              "city": "Stockholm",
              "postal_code": "11234",
              "country": "SE"
            },
            "shipping_method": "pnl-mpc",
            "location_ref": "592971",
            "delivery_status": "booked",
            "tracking_url": "https://tracking.postnord.com/SE?id=00033333333000138712",
            "created_at": "2022-07-29T09:08:36Z",
            "updated_at": "2022-07-29T09:08:36Z",
            "delivery_time": {
              "start": "0001-01-01T00:00:00Z",
              "end": "2022-07-29T09:08:35Z"
            }
          }
        ],
        "created_at": "2022-07-29T09:08:36Z",
        "updated_at": "2022-07-29T09:08:36Z",
        "dimensions": {
          "length": "600",
          "height": "250",
          "width": "300"
        },
        "weight": "720"
      }
    ],
    "external_id": "ACME12345",
    "shipment_value": "19900",
    "tos_id": "01G94KDYHXPE488CQ2SJQ0DJGW",
    "contents": {
      "goods": [
        {
          "sku": "SKU12345",
          "name": "Saucony Shadow 6000",
          "quantity": "1",
          "dimensions": {
            "length": "600",
            "height": "250",
            "width": "300"
          },
          "tags": [
            "shoes",
            "indigo",
            "class_one"
          ],
          "weight": "720"
        }
      ]
    },
    "created_at": "2022-07-29T09:08:36Z",
    "updated_at": "2022-07-29T09:08:36Z",
    "direction_type": "OUTBOUND"
  }
}

Get Shipment

Returns the shipment by a specified parameter.

Request 🔗

GET /v1/som/shipments.get?id=6b2db67e-27a3-4873-a6d2-35759027c1f3 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: Fri, 29 Jul 2022 09:08:36 GMT
Content-Type: application/json

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

{
  "shipment": {
    "id": "6b2db67e-27a3-4873-a6d2-35759027c1f3",
    "site_id": "11756e4a98c64fa9a9c5d627fd88a236",
    "customer_info": {
      "address": {
        "care_of": "Anders Ekman",
        "address_lines": [
          "Industrigatan 5"
        ],
        "city": "Stockholm",
        "postal_code": "11239",
        "country": "SE"
      },
      "phone": "0761234561",
      "email": "erik@example.com"
    },
    "meta": {
      "is_fragile": "true"
    },
    "shipping_date": "2022-07-29T09:08:35Z",
    "address_from": {
      "name": "Acme, Main Warehouse",
      "address_lines": [
        "Frihamnsgatan 56"
      ],
      "city": "Stockholm",
      "postal_code": "11556",
      "country": "SE"
    },
    "address_to": {
      "name": "ICA Västermalmsgallerian",
      "address_lines": [
        "S:t Eriksgatan 45"
      ],
      "city": "Stockholm",
      "postal_code": "11234",
      "country": "SE"
    },
    "line_items": [
      {
        "sku": "SKU12345",
        "name": "Saucony Shadow 6000",
        "quantity": "1",
        "dimensions": {
          "length": "600",
          "height": "250",
          "width": "300"
        },
        "tags": [
          "shoes",
          "indigo",
          "class_one"
        ],
        "weight": "720"
      }
    ],
    "parcels": [
      {
        "id": "ae3ecfe1-cacc-4e17-84c9-0c12ef2e47e8",
        "shipment_id": "6b2db67e-27a3-4873-a6d2-35759027c1f3",
        "line_items": [
          {
            "sku": "SKU12345",
            "name": "Saucony Shadow 6000",
            "quantity": "1",
            "dimensions": {
              "length": "600",
              "height": "250",
              "width": "300"
            }
          }
        ],
        "deliveries": [
          {
            "id": "2f8163a3-33a2-4514-b977-1784fa23107c",
            "parcel_id": "ae3ecfe1-cacc-4e17-84c9-0c12ef2e47e8",
            "tracking_number": "00033333333000138712",
            "label_url": "https://api.ingrid.com/v1/labels/path-to-generated-label.svg",
            "address_from": {
              "name": "Acme, Main Warehouse",
              "address_lines": [
                "Frihamnsgatan 56"
              ],
              "city": "Stockholm",
              "postal_code": "11556",
              "country": "SE"
            },
            "address_to": {
              "name": "ICA Västermalmsgallerian",
              "address_lines": [
                "S:t Eriksgatan 45"
              ],
              "city": "Stockholm",
              "postal_code": "11234",
              "country": "SE"
            },
            "shipping_method": "pnl-mpc",
            "location_ref": "592971",
            "delivery_status": "pickup",
            "tracking_url": "https://tracking.postnord.com/SE?id=00033333333000138712",
            "created_at": "2022-07-29T09:08:36Z",
            "updated_at": "2022-07-29T09:08:36Z",
            "delivery_time": {
              "start": "0001-01-01T00:00:00Z",
              "end": "2022-07-29T09:08:35Z"
            }
          }
        ],
        "created_at": "2022-07-29T09:08:36Z",
        "updated_at": "2022-07-29T09:08:36Z",
        "dimensions": {
          "length": "600",
          "height": "250",
          "width": "300"
        },
        "weight": "720"
      }
    ],
    "external_id": "ACME12345",
    "shipment_value": "19900",
    "tos_id": "01G94KDYHXPE488CQ2SJQ0DJGW",
    "contents": {
      "goods": [
        {
          "sku": "SKU12345",
          "name": "Saucony Shadow 6000",
          "quantity": "1",
          "dimensions": {
            "length": "600",
            "height": "250",
            "width": "300"
          },
          "tags": [
            "shoes",
            "indigo",
            "class_one"
          ],
          "weight": "720"
        }
      ]
    },
    "created_at": "2022-07-29T09:08:36Z",
    "updated_at": "2022-07-29T09:08:36Z",
    "direction_type": "OUTBOUND"
  }
}

Cancel Delivery

Cancels a delivery before it has been picked up by the carrier.

Request 🔗

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

{
  "tracking_number": "00033333333000136619"
}

Response 🔗

HTTP/1.1 200 OK
Date: Mon, 01 Mar 2021 12:19:40 GMT
Content-Type: application/json
Content-Length: 42
Connection: close
Vary: Accept-Encoding
x-trace-id: 01EZPVNMVG9A2303F4RF1SS6MT

{}

Update Shipment

Updates a shipment

Request 🔗

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

{
  "shipment_id": "82dbb827-05c1-4fff-98f2-30cac5a4c3e8",
  "shipping_method": "pnl-mpc",
  "shipment_value": 27800,
  "shipping_date": "2022-07-25T07:20:58.151Z",
  "external_id": "ACME12345",
  "location_ref": "3806098",
  "customer_info": {
    "name": "Erik Johansson",
    "email": "erik@example.com",
    "phone": "0761234561",
    "address": {
      "care_of": "Anders Ekman",
      "address_lines": [
        "Industrigatan 5"
      ],
      "city": "Stockholm",
      "postal_code": "11239",
      "country": "SE"
    }
  },
  "address_to": {
    "name": "Coop Extra Sandnes",
    "address_lines": [
      "Elvegata 11"
    ],
    "postal_code": "4306",
    "city": "Sandnes",
    "country": "NO"
  },
  "address_from": {
    "name": "Acme, Main Warehouse",
    "address_lines": [
      "Frihamnsgatan 56"
    ],
    "postal_code": "11556",
    "city": "Stockholm",
    "country": "SE"
  },
  "address_return": {
    "name": "Acme, Norway Warehouse",
    "address_lines": [
      "Bestumåsen 190"
    ],
    "postal_code": "0281",
    "city": "Oslo",
    "country": "NO"
  },
  "meta": {
    "is_fragile": "true",
    "spring_promo": "true"
  }
}

Response 🔗

HTTP/1.1 200 OK
Date: Mon, 25 Jul 2022 07:20:58 GMT
Content-Type: application/json
Content-Length: 874
Connection: close
Vary: Accept-Encoding
x-trace-id: S20220725072058NVWE4KGR43WPGTKZ

{
  "shipment": {
    "id": "82dbb827-05c1-4fff-98f2-30cac5a4c3e8",
    "site_id": "11756e4a98c64fa9a9c5d627fd88a236",
    "customer_info": {
      "address": {
        "care_of": "Anders Ekman",
        "address_lines": [
          "Industrigatan 5"
        ],
        "city": "Stockholm",
        "postal_code": "11239",
        "country": "SE"
      },
      "phone": "0761234561",
      "email": "erik@example.com"
    },
    "meta": {
      "is_fragile": "true",
      "spring_promo": "true"
    },
    "shipping_date": "2022-07-25T07:20:58Z",
    "address_from": {
      "name": "Acme, Main Warehouse",
      "address_lines": [
        "Frihamnsgatan 56"
      ],
      "city": "Stockholm",
      "postal_code": "11556",
      "country": "SE"
    },
    "address_to": {
      "name": "Coop Extra Sandnes",
      "address_lines": [
        "Elvegata 11"
      ],
      "city": "Sandnes",
      "postal_code": "4306",
      "country": "NO"
    },
    "address_return": {
      "name": "Acme, Norway Warehouse",
      "address_lines": [
        "Bestumåsen 190"
      ],
      "city": "Oslo",
      "postal_code": "0281",
      "country": "NO"
    },
    "line_items": [
      {
        "sku": "SKU12345",
        "name": "Saucony Shadow 6000",
        "quantity": "1",
        "dimensions": {
          "length": "600",
          "height": "250",
          "width": "300"
        },
        "tags": [
          "shoes",
          "indigo",
          "class_one"
        ],
        "weight": "720"
      }
    ],
    "parcels": [
      {
        "id": "272973b7-3c19-42f9-a2d8-49b99a99456b",
        "shipment_id": "82dbb827-05c1-4fff-98f2-30cac5a4c3e8",
        "line_items": [
          {
            "sku": "SKU12345",
            "name": "Saucony Shadow 6000",
            "quantity": "1",
            "dimensions": {
              "length": "600",
              "height": "250",
              "width": "300"
            }
          }
        ],
        "deliveries": [
          {
            "id": "08dda0c9-6b36-492a-a35e-73ce83f509f0",
            "parcel_id": "272973b7-3c19-42f9-a2d8-49b99a99456b",
            "address_from": {
              "name": "Acme, Main Warehouse",
              "address_lines": [
                "Frihamnsgatan 56"
              ],
              "city": "Stockholm",
              "postal_code": "11556",
              "country": "SE"
            },
            "address_to": {
              "name": "Coop Extra Sandnes",
              "address_lines": [
                "Elvegata 11"
              ],
              "city": "Sandnes",
              "postal_code": "4306",
              "country": "NO"
            },
            "shipping_method": "pnl-mpc",
            "location_ref": "3806098",
            "delivery_status": "created",
            "address_return": {
              "name": "Acme, Norway Warehouse",
              "address_lines": [
                "Bestumåsen 190"
              ],
              "city": "Oslo",
              "postal_code": "0281",
              "country": "NO"
            },
            "created_at": "2022-07-25T07:20:58Z",
            "updated_at": "2022-07-25T07:20:58Z",
            "label_url": "https://api.ingrid.com/v1/labels/path-to-generated-label.svg"
          }
        ],
        "created_at": "2022-07-25T07:20:58Z",
        "updated_at": "2022-07-25T07:20:58Z",
        "dimensions": {
          "length": "600",
          "height": "250",
          "width": "300"
        },
        "weight": "720"
      }
    ],
    "external_id": "ACME12345",
    "shipment_value": "27800",
    "tos_id": "01G1QDS00DVDJ6190NZBCCV229",
    "contents": {
      "goods": [
        {
          "sku": "SKU12345",
          "name": "Saucony Shadow 6000",
          "quantity": "1",
          "dimensions": {
            "length": "600",
            "height": "250",
            "width": "300"
          },
          "tags": [
            "shoes",
            "indigo",
            "class_one"
          ],
          "weight": "720"
        }
      ]
    },
    "created_at": "2022-07-25T07:20:58Z",
    "updated_at": "2022-07-25T07:20:58Z",
    "direction_type": "OUTBOUND"
  }
}

Cancel Shipment

Cancels a shipment

Request 🔗

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

{
  "shipment_id": "82dbb827-05c1-4fff-98f2-30cac5a4c3e8"
}

Response 🔗

HTTP/1.1 200 OK
Date: Mon, 25 Jul 2022 07:20:58 GMT
Content-Type: application/json
Content-Length: 54
Connection: close
Vary: Accept-Encoding
x-trace-id: S20220725072058088HZTK4X3YZKPJE

{}

Add Parcel

Allows adding new parcel to already existing shipment. It is possible to add the parcel to the newly created (CreateShipment) carrier pickup that is not yet requested. If the shipment was booked using BookParcels, using AddParcel will book and generate a new label for the added parcel. The endpoint also works with custom booking methods. If a return shipment is connected with the provided shipment, a parcel will be added there.

Typical use case would be to generate labels separately for each parcel in a warehouse.

Request 🔗

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

{
  "site_id": "5ba74bc0-c44d-4abf-b3df-2acdedc7c8bc",
  "shipment_id": "886772b7-ecb2-4a54-bcbb-5c6c60abcfa8"
}

Response 🔗

HTTP/1.1 200 OK
Date: Mon, 01 Mar 2021 12:19:41 GMT
Content-Type: application/json
Content-Length: 1095
Connection: close
Vary: Accept-Encoding
x-trace-id: 01EZPVNNV2D664XW57S0GD96EM

{
  "shipment": {
    "id": "4659fc78-a9cf-4012-8709-6479e51aa119",
    "site_id": "11756e4a98c64fa9a9c5d627fd88a236",
    "customer_info": {
      "address": {
        "care_of": "Anders Ekman",
        "address_lines": [
          "Industrigatan 5"
        ],
        "city": "Stockholm",
        "postal_code": "11239",
        "country": "SE"
      },
      "phone": "0761234561",
      "email": "erik@example.com"
    },
    "meta": {
      "is_fragile": "true"
    },
    "shipping_date": "2021-03-01T12:19:40Z",
    "address_from": {
      "name": "Acme, Main Warehouse",
      "address_lines": [
        "Frihamnsgatan 56"
      ],
      "city": "Stockholm",
      "postal_code": "11556",
      "country": "SE"
    },
    "address_to": {
      "name": "ICA Västermalmsgallerian",
      "address_lines": [
        "S:t Eriksgatan 45"
      ],
      "city": "Stockholm",
      "postal_code": "11234",
      "country": "SE"
    },
    "line_items": [
      {
        "sku": "SKU12345",
        "name": "Saucony Shadow 6000",
        "quantity": "1",
        "dimensions": {
          "length": "600",
          "height": "250",
          "width": "300"
        },
        "tags": [
          "shoes",
          "indigo",
          "class_one"
        ],
        "weight": "720"
      }
    ],
    "parcels": [
      {
        "id": "316b6769-b537-4dd9-96f1-a824e747f8bb",
        "shipment_id": "4659fc78-a9cf-4012-8709-6479e51aa119",
        "deliveries": [
          {
            "id": "c3cbf98f-fe7a-4de1-ae78-3e2a36758c2a",
            "parcel_id": "316b6769-b537-4dd9-96f1-a824e747f8bb",
            "address_from": {
              "name": "Acme, Main Warehouse",
              "address_lines": [
                "Frihamnsgatan 56"
              ],
              "city": "Stockholm",
              "postal_code": "11556",
              "country": "SE"
            },
            "address_to": {
              "name": "ICA Västermalmsgallerian",
              "address_lines": [
                "S:t Eriksgatan 45"
              ],
              "city": "Stockholm",
              "postal_code": "11234",
              "country": "SE"
            },
            "shipping_method": "pnl-mpc",
            "location_ref": "592971",
            "delivery_status": "created",
            "created_at": "2021-03-01T12:19:40Z",
            "updated_at": "2021-03-01T12:19:40Z"
          }
        ],
        "created_at": "2021-03-01T12:19:40Z",
        "updated_at": "2021-03-01T12:19:40Z",
        "dimensions": {
          "length": "600",
          "height": "250",
          "width": "300"
        },
        "weight": "720"
      },
      {
        "id": "ddee0942-e5d8-4a9b-a2d0-69c256e66d60",
        "shipment_id": "4659fc78-a9cf-4012-8709-6479e51aa119",
        "deliveries": [
          {
            "id": "fcd7d87a-1772-4044-bc25-68a14de34203",
            "parcel_id": "ddee0942-e5d8-4a9b-a2d0-69c256e66d60",
            "address_from": {
              "name": "Acme, Main Warehouse",
              "address_lines": [
                "Frihamnsgatan 56"
              ],
              "city": "Stockholm",
              "postal_code": "11556",
              "country": "SE"
            },
            "address_to": {
              "name": "ICA Västermalmsgallerian",
              "address_lines": [
                "S:t Eriksgatan 45"
              ],
              "city": "Stockholm",
              "postal_code": "11234",
              "country": "SE"
            },
            "shipping_method": "pnl-mpc",
            "location_ref": "592971",
            "delivery_status": "created",
            "created_at": "2021-03-01T13:29:40Z",
            "updated_at": "2021-03-01T13:29:40Z"
          }
        ],
        "created_at": "2021-03-01T13:29:40Z",
        "updated_at": "2021-03-01T13:29:40Z",
        "dimensions": {
          "length": "600",
          "height": "250",
          "width": "300"
        },
        "weight": "720"
      }
    ],
    "external_id": "ACME12345",
    "shipment_value": "19900",
    "tos_id": "01EZPVNN71H7JDH6B9HZ080YGH",
    "contents": {
      "goods": [
        {
          "sku": "SKU12345",
          "name": "Saucony Shadow 6000",
          "quantity": "1",
          "dimensions": {
            "length": "600",
            "height": "250",
            "width": "300"
          },
          "tags": [
            "shoes",
            "indigo",
            "class_one"
          ],
          "weight": "720"
        }
      ]
    },
    "created_at": "2021-03-01T12:19:40Z",
    "updated_at": "2021-03-01T12:19:40Z"
  }
}

Last updated: Thu, Apr 25, 06:15 AM