SOM

Shipment Order Management is our Transport Administration system specifically tailored for e-commerce

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.

A Shipment contains some general information about the whole shipment and ties a number of Parcels together. A Parcel represents a physical package that is a part of a Shipment. A Delivery represents a transporation of the Parcel by a specified shipping method, between two places. Since a Parcel may be redirected or forwarded, each Parcel may contain multiple Deliveries but only one can be active at one time.

General flow

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

  1. Create a Shipment. Shipments, 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.

Alternative flow

If you just want to create a shipment, print labels and book pickup in a single call, you can use shipments.createAndBook as described below.

Create shipment

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

Request

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

{
  "shipping_method": "brn-blp",
    "shipment_value": 2000,
    "shipping_date": "2016-11-22T15:00:00Z",
    "number_of_parcels": 3,
    "customer_info": {
      "name": "Erik Johansson",
      "email": "erik@testmail.com",
      "phone": "0761234567",
      "address": {
        "care_of": "Anders Ekman",
        "address_lines": ["Industrigatan 5"],
        "city": "Stockholm",
        "postal_code": "11239",
        "country": "SE"
      }
    },
    "address_to": {
      "name": "Erik Johansson",
      "care_of": "Anders Ekman",
      "address_lines": ["Industrigatan 5"],
      "postal_code": "11239",
      "city": "Stockholm",
      "country": "SE"
    },
    "address_from": {
      "name": "Acme",
      "address_lines":["Frihamnsgatan 56"],
      "postal_code": "11556",
      "city": "Stockholm",
      "country": "SE"
    },
    "line_items": [{
      "name": "En påse"
    }],
    "dimensions": {
      "length": 100,
      "width": 200,
      "height": 10
    },
    "weight": 200,
    "meta": {
      "foo": "bar",
      "label.top": "[\"top1\", \"top2\", \"top3\", \"top4\" ]",
      "label.bottom": "[\"bottom1\", \"bottom2\", \"bottom3\", \"bottom4\"]"
    }
}

Create and book shipment

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.

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

{
 // request body is identical to shipments.create
 ...
}

Create shipment from session

Creates new shipment from an existing COS Session

Request

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

{
  "cos_session_id": "37930eaad0f742e69739b4e8a8748564",
  "shipping_date": "2016-11-22T15:00:00Z",
  "address_return": {
    "name": "Acme",
    "address_lines":["Frihamnsgatan 56"],
    "postal_code": "11556",
    "city": "Stockholm",
    "country": "SE"
  }
}

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
Authorization: Bearer base64-encoded-api-token
Content-Type: application/json

{
  "shipment_id": "37930eaa-d0f7-42e6-9739-b4e8a8748564"
}

Get shipment

Returns the shipment by a specified parameter.

Request

GET /shipments.get?id=3ee7ba34-32bb-437e-8754-2b512dcdc21e HTTP/1.1
Host: api.ingrid.com
Content-Type: application/json
Authorization: Bearer xxx

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
Authorization: Bearer base64-encoded-api-token
Content-Type: application/json

{
  "tracking_number": "SWSY0000034"
}

Object Definitions

Addon

Describes an additional service provided by shipping method.

name
string
Internal idenfifier of an addon.
code
string
External code, as defined in carrier's system.
description
string
Description of the addon.
data
object
Additional data that has to be passed to use the addon.

Address

Generic address entity

name
string
Customer name
care_of
string optional
Care of part of address
attn
string optional
Attention field
address_lines
string[]
List of address lines part of address
city
string
Name of the city
region
string optional
Region can be a state or a province
postal_code
string
Postal code (or zipcode in US)
country
string
Country should be specified as two uppercase letters (ISO Alpha-2). Example SE
coordinates
Coordinates readonly
Geolocation coordinates of the address
door_code
string optional
The door code to the main entrance

BookParcelsRequest

Perform a booking request to generate tracking numbers, shipping labels and tracking links.

shipment_id
string required
The ID of the shipment which parcels should be booked.

BookParcelsResponse

Returns latest shipment state together with generated shipping labels, tracking numbers and tracking links.

shipment
Shipment
Current shipment object state

BookPickupRequest

Book a pickup with the shipping company.

tracking_number
string required
Tracking number of the delivery which should be booked.

BookPickupResponse

Returns the state of the booked delivery.

delivery
Delivery
Booked delivery state

CancelDeliveryRequest

id
string
Delivery ID
tracking_number
string
Delivery tracking number

CancelShipmentRequest

shipment_id
string

Contents

Contents contains all goods sent in a Shipment or Parcel. Goods can either be defined directly by providing the full details of the goods, it can be referenced by transport order id or an external reference to goods defined by an external system.

goods
LineItem[]
Goods a.k.a. Line items.
transport_orders
TransportOrderContentItem[]
Tranport orders contained in this shipment.
external_orders
ExternalOrderContentItem[]
External orders contained in this shipment.

Coordinates

Geolocation coordinates

lat
number
Latitude
lng
number
Longitude

CreateCompositeShipmentFromOrderRequest

Request object that is used to create a Shipment from order.

tos_id
string required
TosId is an order ID as given from TOS.
shipping_date
string required
The date that the shipment will most likely be dispatched from the warehouse.
address_return
Address
Address where deliveries of this shipment should be returned to.
number_of_parcels
string
Number of parcels to generate. If supplied it will override the number of parcels created for this shipment. Otherwise the number of parcels will default to one
meta
object
Generic key-value object that can be used to attach additional information to the shipment.
external_id
string
Can be used to store a unique identifier from the merchant. For example external order ID or external shipment ID.
with_return
boolean
Indicates whether a return shipment should be created.
delivery_time
DateTimeRange
Time range when the deliveries will most likely be delivered to the customer.
shipping_method
string
Specific shipping product ID by which the generated parcels should be delivered. If tos_id is provided and the referenced order has field metadata.session.method, this field is optional. Otherwise, it is required.
contents
Contents
Contents of the shipment
addons
Addon[]
List of addons.
parcel_free_text
string
ParcelFreeText is a custom description to be assigned to all parcels in the shipment.

CreateCompositeShipmentFromRequest

Request object that is used to create a Shipment from another source, for example via a COS session.

cos_session_id
string required
CosSessionId a session id as given from COS.
shipping_date
string required
The date that the shipment will most likely be dispatched from the warehouse.
address_return
Address
Address where deliveries of this shipment should be returned to.
number_of_parcels
string
Number of parcels to generate. If supplied it will override the number of parcels created for this shipment. Otherwise the number of parcels will default to one.
parcel_free_text
string
ParcelFreeText is a custom description to be assigned to all parcels in the shipment.

CreateCompositeShipmentRequest

Request object that is used to create a Shipment together with Parcels and Deliveries all at once.

shipping_method
string required
Specific shipping product ID by which the generated parcels should be delivered.
dimensions
Dimensions
Dimensions will override the dimensions for each created parcel. If not set, the total weight of each parcel will be calculated from the line items if that information is available. Default unit is millimeters. (mm)
weight
string
Weight in grams (g). If not set, the total weight of each parcel will be calculated from its line items if that information is available.
address_from
Address required
Address where the shipment will be dispatched from. Most often the address of the warehouse.
address_to
Address required
Destination address. For example address of the service point or the click and collect store.
address_return
Address
Address where deliveries of this shipment should be returned to.
line_items
LineItem[]
Line items that the shipment contains.
customer_info
CustomerInfo
Contains the customer information such as name, email, phone and address. This field can be omitted, only if tos_id is not empty and the referenced order has enough data to derive customer info from it.
shipping_date
string required
The date that the shipment will most likely be dispatched from the warehouse.
shipment_value
string
Total value of the shipment including tax. Example 10000 is 100 SEK.
number_of_parcels
string
Number of parcels to generate. If supplied it will override the number of parcels created for this shipment. Otherwise the number of parcels will default to one
meta
object
Generic key-value object that can be used to attach additional information to the shipment.
location_ref
string
ID of the pickup location where the parcels should be delivered to.
external_id
string
Can be used to store a unique identifier from the merchant. For example external order ID or external shipment ID.
delivery_time
DateTimeRange
Time range when the deliveries will most likely be delivered to the customer.
courier_instructions
string
Optional instructions to the courier
with_return
boolean
Indicates whether a return shipment should be created.
contents
Contents
Contents of the shipment
tos_id
string
Order ID from TOS.
addons
Addon[]
List of addons.
parcel_free_text
string
ParcelFreeText is a custom description to be assigned to all parcels in the shipment.
shipping_category_ref
string
ShippingCategoryRef is an ID of shipping category that user choice belongs to. It's used to resolve virtual methods connected with ship. category.

CreateCompositeShipmentResponse

Response from the shipment create call. Contains the latest shipment state.

shipment
Shipment
Current shipment object state

CustomerInfo

Contains the necessary information about a customer in order to make a delivery

address
Address
Customer's home address.
phone
string
Customer's mobile phone number.
email
string
Customer's email.

DateTimeRange

start
string
Start DateTime in RFC3339.
end
string
End DateTime in RFC3339.

Delivery

Delivery is the parcel with start and end destination. A delivery always has one parcel that it belongs to.

id
string
Unique id of the delivery (uuid).
parcel_id
string
ID of the parcel which the delivery belongs to.
tracking_number
string
Tracking number for the delivery.
shipment_tracking_number
string
Consolidated tracking number for all deliveries in a shipment.
label_url
string
URL of the delivery's shipping label.
address_from
Address
Origin address for this delivery.
address_to
Address
Destination address for this delivery.
shipping_method
string
Shipping product ID for the delivery.
location_ref
string
ID of the service point location if applicable.
transit_time
TransitTime deprecated
Transit time .
delivery_status
string
State of the delivery. Possible values are 'created','booked','pickup'.
address_return
Address
The return address to which a delivery that is returned should be sent.
weight
string
Weight of the delivery in grams.
courier_instructions
string
Optional instructions to the courier.
return_tracking_number
string
Tracking number for the return delivery.
return_label_url
string
URL of the delivery's return label.
addons
Addon[]
Addons available for the shipment.
tracking_url
string
Tracking URL for the upcoming delivery.
created_at
string
Timestamp when delivery was created.
updated_at
string
Timestamp when delivery was last updated.

Dimensions

Length, height and width

length
string
Length in millimeters.
height
string
Height in millimeters.
width
string
Width in millimeters.

ExternalOrderContentItem

ExternalOrderContentItem is a reference to goods defined by an external system.

external_id
string
A reference to an external order.

FilterCountRange

max
string
min
string

Filtering

tos_ids
string[]
id
string
Id will be matched against shipment_id, tos_id and external_id.
shipping_date_range
shipping_methods
string[]
statuses
string[]
line_items
created_at_range
shipment_ids
string[]

GetDeliveryResponse

Returns a delivery object

delivery
Delivery
Delivery object state

GetShipmentResponse

Returns latest shipment state.

shipment
Shipment
Current shipment object state

LineItem

Physical item of the parcel. A parcel can contain many line items. The parameters on the line item are used by the shipping rules framework to make better shipping decisions.

sku
string
Unique product identifier.
name
string
Product name or title.
description
string
Description of the product.
quantity
string
Number of items.
dimensions
Dimensions
Dimensions of the line item.
price
string
Price of the line item.
currency
string
Currency of the line item.
tags
string[]
List of tags or attributes that can be attached to this line item.
weight
string
Weight of the line item in grams.

ListShipmentsRequest

tos_id
string
Order ID.
pagination
filtering
order_by_direction

ListShipmentsResponse

shipments
Shipment[]
List of shipments belonging to an order.
count
string
more_shipments
boolean

Pagination

offset
string
limit
string

Parcel

Parcel is the physical package. One parcel can have at least one delivery at a time.

id
string
Unique ID of the parcel (uuid).
shipment_id
string
ID of the shipment that parcel belongs to (uuid).
line_items
LineItem[]
All line items that are part of the parcel.
deliveries
Delivery[]
Deliveries associated with the parcel.
created_at
string
Timestamp when parcel was created.
updated_at
string
Timestamp when parcel was last updated.
dimensions
Dimensions optional
Length, height and width .
parcel_number
integer deprecated
Index number of the individual parcel in a shipment, i.e parcel 3 of 5 .
parcel_total
integer deprecated
Not used .
weight
string
Total weight of the parcel in grams.
contents
Contents
Content of parcel.
free_text
string
FreeText is a custom description of a parcel.

Shipment

Shipment is the top level object in SOM. A shipment can be composed of multiple parcels and each parcel can contain many deliveries. Only one delivery can be active at a time.

id
string
ID of the shipment (uuid).
site_id
string
Site ID to which the shipment belongs to [internal].
customer_info
CustomerInfo required
Contains the customer information such as name, email, phone and address .
meta
object
Generic key-value object that can be used to attach additional information to the shipment.
shipping_date
string required
The date that the shipment will most likely be dispatched from the warehouse .
address_from
Address required
Address where the shipment will be dispatched from. Most often the address of the warehouse .
address_to
Address required
Destination address. For example address of the service point or the click and collect store .
address_return
Address
Address where deliveries of this shipment should be returned to.
line_items
LineItem[]
Line items associated with this shipment.
parcels
Parcel[]
Parcels associated with this shipment.
external_id
string
Can be used to store a unique identifier from the merchant. For example external order ID or external shipment ID.
shipment_value
string
Total value of the shipment including tax. Example 10000 is 100 SEK.
with_return
boolean
Indicates whether a return shipment should be created.
tos_id
string
ID of a corresponding order.
contents
Contents
Contents of shipment.
addons
Addon[]
Addons available for the shipment.
created_at
string
Timestamp when shipment was created.
updated_at
string
Timestamp when shipment was last updated.

TotalShipmentsCountResponse

total_count
string

TransitTime

start
string
end
string

TransportOrderContentItem

TransportOrderContentItem is a reference to goods defined by a transport order.

tos_id
string
The transport order id.
external_ref
string
An additional reference which can be used freely by the client.

UpdateShipmentRequest

Update a shipment

shipment_id
string
Shipment id
shipping_method
string required
Specific shipping product ID by which the generated parcels should be delivered.
weight
string
Weight in grams (g). If not set, the total weight of each parcel will be calculated from its line items if that information is available.
address_from
Address required
Address where the shipment will be dispatched from. Most often the address of the warehouse.
address_to
Address required
Destination address. For example address of the service point or the click and collect store.
address_return
Address
Address where deliveries of this shipment should be returned to.
customer_info
CustomerInfo
Contains the customer information such as name, email, phone and address.
shipping_date
string required
The date that the shipment will most likely be dispatched from the warehouse.
shipment_value
string
Total value of the shipment including tax. Example 10000 is 100 SEK.
meta
object
Generic key-value object that can be used to attach additional information to the shipment.
location_ref
string
ID of the pickup location where the parcels should be delivered to.
external_id
string
Can be used to store a unique identifier from the merchant. For example external order ID or external shipment ID.
courier_instructions
string
Optional instructions to the courier
with_return
boolean
Indicates whether a return shipment should be created.
addons
Addon[]
List of addons.
parcel_free_text
string
ParcelFreeText is a custom description to be assigned to all parcels in the shipment.

UpdateShipmentResponse

Returns the updated shipment

shipment
Shipment
The updated shipment