Object Reference

Addon

Describes an additional service provided by shipping method.

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

Address

Common address entity that used almost everywhere in Ingrid's API.

name
string
Customer or company name
care_of
stringoptional
Care of part of address usually written as `c/o`
attn
stringoptional
Attention field. Can be used to indicate an employee if the address is a company address
address_lines
string[]
List of address lines part of address such as street and building number
city
string
Name of the city
region
stringoptional
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` for Sweden, `ES` for Spain.
coordinates
Geolocation coordinates of the address. If reverse geolocation lookup of the address was successful this property will be populated. If coordinates are available they will be used to in service point search. In case of `search_address` coordinates can also be set by merchant if known.
door_code
stringoptional
The door code to the main entrance of the building if applicable

BookParcelsRequest

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

shipment_id
stringrequired
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
Current shipment object state

BookPickupRequest

Book a pickup with the shipping company.

tracking_number
stringrequired
Tracking number of the delivery which should be booked.

BookPickupResponse

Returns the state of the booked delivery.

delivery
Booked delivery state

CancelDeliveryRequest

Request to cancel a delivery if the shipment has not been picked up yet.

id
string
Delivery ID
tracking_number
string
Delivery tracking number

CancelShipmentRequest

Request to cancel a shipment if the shipment has not been picked up yet.

shipment_id
string
Shipment ID

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
Goods a.k.a. line items.
transport_orders
Transport orders contained in this shipment, so called consolidated shipment.
external_orders
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
stringrequired
TosId is an order ID as given from TOS.
shipping_date
stringrequired
The date that the shipment will most likely be dispatched from the warehouse.
address_return
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
hash
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
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 of the shipment
addons
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
stringrequired
CosSessionId a session id as given from COS.
shipping_date
stringrequired
The date that the shipment will most likely be dispatched from the warehouse.
address_return
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
stringrequired
Specific shipping product ID by which the generated parcels should be delivered.
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
Addressrequired
Address where the shipment will be dispatched from. Most often the address of the warehouse.
address_to
Addressrequired
Destination address. For example address of the service point or the click and collect store.
address_return
Address where deliveries of this shipment should be returned to.
line_items
LineItem[]deprecated
Use `contents` instead
customer_info
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
stringrequired
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
hash
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
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 of shipment. Can be of different types - goods, transport orders and external orders.
tos_id
string
Order ID from TOS.
addons
Addons that should be used for the shipment.
parcel_free_text
string
Custom description (notes) that will be assigned to all parcels in the shipment.
shipping_category_ref
string
ID of shipping category that user choice belongs to. It's used to resolve virtual methods connected with ship. category.
address_from_location_ref
string
ID of the warehouse, from which package will be delivered.

CreateCompositeShipmentResponse

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

shipment
Current shipment object state

CustomerInfo

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

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

DateTimeRange

Provides a date interval. Depending on a case, `start` and `end` parts are not guaranteed to be present.

start
string
Start of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31-07:00`
end
string
End of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31-07:00`.

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
Origin address for this delivery.
address_to
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
TransitTimedeprecated
Transit time .
delivery_status
string
State of the delivery. Possible values are 'created','booked','pickup'.
address_return
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
Addons available for the shipment.
tracking_url
string
Tracking URL for the upcoming delivery if available.
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. For example `140` is 0,14 m
height
string
Height in millimeters. For example `50` is 0,05 m
width
string
Width in millimeters. For example `20` is 2 cm

ExternalOrderContentItem

Reference to goods defined by an external system.

external_id
string
A reference to an external (merchant) order.

GetDeliveryResponse

Returns a delivery object

delivery
Delivery object state

GetShipmentResponse

Returns latest shipment state.

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
stringrequired
Unique product identifier.
name
stringrequired
Product name or title
description
stringoptional
Description of the product
quantity
stringrequired
Number of items.
dimensions
Dimensionsoptional
Dimensions of the line item.
price
stringoptional
Price of the line item.
currency
stringoptional
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. For example `200` is 0,2 kg.

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[]deprecated
Use `contents` instead
deliveries
Deliveries associated with the parcel.
created_at
string
Timestamp when parcel was created.
updated_at
string
Timestamp when parcel was last updated.
dimensions
Dimensionsoptional
Length, height and width .
parcel_number
integerdeprecated
Index number of the individual parcel in a shipment, i.e parcel 3 of 5 .
parcel_total
integerdeprecated
Not used .
weight
string
Total weight of the parcel in grams.
contents
Contents of the parcel.
free_text
string
Custom description (notes) 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
stringinternal
Site ID to which the shipment belongs to .
customer_info
CustomerInforequired
Contains the customer information such as name, email, phone and address .
meta
hash
Generic key-value object that can be used to attach additional information to the shipment.
shipping_date
stringrequired
The date that the shipment will most likely be dispatched from the warehouse .
address_from
Addressrequired
Address where the shipment will be dispatched from. Most often the address of the warehouse .
address_to
Addressrequired
Destination address. For example address of the service point or the click and collect store .
address_return
Address where deliveries of this shipment should be returned to.
line_items
LineItem[]deprecated
Use `contents` instead
parcels
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 in cents. 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 of shipment. Can be of different types - goods, transport orders and external orders.
addons
Addons that should be used for the shipment.
created_at
string
Timestamp when shipment was created.
updated_at
string
Timestamp when shipment was last updated.

TransportOrderContentItem

Reference to goods defined by a transport order.

tos_id
string
Transport order id.
external_ref
string
Additional reference which can be used freely by the client to tie together a SOM shipment with an internal ID.

UpdateShipmentRequest

Update a shipment request

shipment_id
string
Shipment ID
shipping_method
stringrequired
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
Addressrequired
Address where the shipment will be dispatched from. Most often the address of the warehouse.
address_to
Addressrequired
Destination address. For example address of the service point or the click and collect store.
address_return
Address where deliveries of this shipment should be returned to.
customer_info
Contains the customer information such as name, email, phone and address.
shipping_date
stringrequired
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
hash
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
List of shipment addons.
parcel_free_text
string
Custom description (notes) that will be assigned to all parcels in the shipment.

UpdateShipmentResponse

Returns the updated shipment

shipment
The updated shipment state
Last Updated: 3/13/2020, 2:31:37 PM