Object Reference

AddLocationToSessionRequest

Payload that adds location the session

id
string
Session ID
shipping_method
string
Shipping method to add location to
location_ref
string
Location reference

AddLocationToSessionResponse

Result of adding found location to the session

session
Current session state

AdditionalInfo

Additional meta information related to the session.

courier_instructions
stringoptional
Courier instruction provided by the customer
door_code
stringoptional
Entrance door code provided by the customer that can be used by the courier to get in
customer_number
stringoptional
Optional customer number provided by the user. Sometimes required by specific shipping products. For example DHL lockers in Germany

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

BillingItem

Individual billing item of the total shipping cost.

description
string
The kind of shipping cost. Can be pure shipping cost, addon or additional service.
cost
Individual cost in cents. Example `1000` is 10 SEK

CarrierAddon

Carrier specific addons

name
string
Internal identifier of an addon.
code
string
Identifier of the addon in carrier's system.
description
string
Description of the addon's functionality

Cart

Cart information from the e-commerce store. Information in here is used by the shipping rule engine to calculate the best shipping option for the customer.

total_value
integerrequired
Total cart value in cents. Example `20000` represents `200.00`
currency
stringrequired
Cart's currency. Should be in sync with the checkout. Example `SEK`
shipping_date
Date the order is expected to be dispatched from the warehouse. For orders containing out of stock items or items available for pre-order only. If this property is not set Ingrid defaults to today's date.
items
CartItem[]required
Information about the individual order items. This can be used by the shipping rule engine to calculate the best shipping option.
total_discount
integeroptional
Discount amount in cents. Example `2000` is `20.00`.
pre_order
booleanoptional
Indicated if the order can be shipped earliest on the provided shipping date
voucher
stringdeprecated
Voucher code. The voucher code is static, meaning that the merchant should map individual voucher codes send to the customers to a common voucher code that is sent to Ingrid.
cart_id
stringrequired
Unique cart id for the customers cart on the merchant side.
attributes
string[]optional
Attributes of the cart. Also known as `tags` or `categories`. Can be used by the shipping rule engine to calculate the correct shipping option. Ex. ["circle", "prescription", "food"]
vouchers
string[]optional
Vouchers that can be used in price/filter rules.

CartItem

Product in the shopping cart

sku
stringrequired
Unique product identifier
name
stringoptional
Product name or title
attributes
string[]optional
Attributes of the cart item. Also known as `tags` or `categories`. Can be used by the shipping rule engine to calculate the correct shipping option. Ex. ["circle", "prescription", "food"]
out_of_stock
booleanoptional
Flag indicating if the item is currently out of stock
dimensions
Dimensions of this cart item. Can be used by the shipping rule engine to calculate the best shipping option.
quantity
integer
Total number product item in the cart.
weight
integeroptional
Weight of the item in grams. Can be used by the shipping rule engine to calculate the best shipping option. Example `1000` is 1 kg and `10` is 0,001 kg.
discount
integeroptional
Eventual discount of the item. Can be used by the shipping rule engine to calculate the best shipping option.
price
integeroptional
Price of the item. Can be used by the shipping rule engine to calculate the best shipping option.

Choice

Contains data both about user choice and preselected choice

shipping_method
string
Specific shipping product chosen by the customer
location_ref
string
Service point location or merchant store referenced if shipping type is `pickup`. Use this key to find the correct service point in session data.
time_slot_ref
string
Time slot reference. Use this key to find the correct time slot in session data.
shipping_category_ref
string
Category the shipping option belongs to

CompleteSessionAndPromoteToOrderRequest

Sent as a final request. `customer` property needs to be present and have all customer data. This payload will also create a Transport Order behind the scenes.

id
stringrequired
Session ID
customer_info
CustomerInfodeprecated
Use `customer` property instead
warehouse_id
string
Warehouse ID specifies from which warehouse order will be sent. If it is not supplied and site has only one warehouse, this warehouse will be used as sender. Otherwise order will have no sender.
customer
Information about the customer such as name, email, phone and address. This information is required when completing a session and is usually taken from the payment provider in the time of purchase. Information is used to calculate best shipping option and pickup location if no active selection has been made by the customer earlier during the checkout.
external_id
stringoptional
Optional external ID to connect the session with an order on the merchant side. Can be used for troubleshooting and debugging.

CompleteSessionAndPromoteToOrderResponse

Result of the complete session and promote to order call

session
Final session state. After this call the session is marked as `COMPLETE` and cannot be changed.
tos_id
string
Transport Order ID

CompleteSessionAndUpdateOrderRequest

Sent as a final request. `customer´ needs to be present and have all customer data.

id
stringrequired
Session ID
tos_id
string
Transport order ID from which a new session was created
customer_info
CustomerInfodeprecated
Use `customer` property instead
warehouse_id
string
Warehouse ID specifies from which warehouse order will be sent. If it is not supplied and site has only one warehouse, this warehouse will be used as sender. Otherwise order will have no sender.
customer
Information about the customer such as name, email, phone and address. This information is required when completing a session and is usually taken from the payment provider in the time of purchase. Information is used to calculate best shipping option and pickup location if no active selection has been made by the customer earlier during the checkout.
external_id
stringoptional
Can be used to store a unique identifier from the merchant. For example external order ID

CompleteSessionAndUpdateOrderResponse

Result of the complete session and update order call

session
Final session state. After this call the session is marked as `COMPLETE` and cannot be changed.

CompleteSessionRequest

Sent as a final request. `customer` property need to to be present and have all customer data.

id
stringrequired
Session ID
customer_info
CustomerInfodeprecated
Use `customer` property instead
tos_id
stringoptional
ID of the Transport Order, which was created from this session.
customer
Information about the customer such as name, email, phone and address. This information is required when completing a session and is usually taken from the payment provider in the time of purchase. Information is used to calculate best shipping option and pickup location if no active selection has been made by the customer earlier during the checkout.
external_id
stringoptional
Optional external ID to connect the session with an order on the merchant side. Can be used for troubleshooting and debugging.

CompleteSessionResponse

Result of the complete session call

session
Final session state. After this call the session is marked as `COMPLETE` and cannot be changed.

Coordinates

Geolocation coordinates

lat
number
Latitude
lng
number
Longitude

Cost

Cost amount

amount
integer
Actual cost amount in cents. Example `1000` is 10 SEK

CreateSessionFromOrderRequest

Provides session data needed to create a new session from a Transport Order.

locale
stringdeprecated
Use `locales` property instead
external_id
stringoptional
Optional external ID to connect the session with an order on the merchant side. Can be used for troubleshooting and debugging.
tos_id
string
Transport order ID from which a new session will be created
locales
string[]
List of locales defined as lc-CC, see ISO 3166-1 in order of preference (first supported one will be chosen).

CreateSessionFromOrderResponse

Result of create session from order response.

session
Current session state

CreateSessionRequest

Data needed to create a new session.

purchase_country
stringrequired
Customer country where the purchase is being made. Should be in sync with the checkout country. Example `SE` for Sweden
purchase_currency
stringrequired
Customer currency. Should be in sync with the checkout currency. Example `SEK`
locale
stringdeprecated
Use `locales` property instead
customer_info
CustomerInfodeprecated
use `customer` and `search_address` instead.
cart
Cartrequired
Cart details such as items, their weight, dimensions, attributes, quantities as well as shipping date, cart total value and currency.
external_id
string
Optional external ID to connect the session with an order on the merchant side. Can be used for troubleshooting and debugging.
tos_id
string
If the session was created from a transport order, it is the id of the order. Only once the session is completed a `tos_id` will be available. See TOS documentation for details.
customer
Information about the customer such as name, email, phone and address. This information is required when completing a session and is usually taken from the payment provider in the time of purchase. Information is used to calculate best shipping option and pickup location if no active selection has been made by the customer earlier during the checkout.
search_address
Lookup address for delivery. May be an office address if customer wants to pick up a package close to his/her work place. Minimum required field is country and postal code.
locales
string[]
Locales list defined as lc-CC, see ISO 3166-1 in order of preference (first supported one will be chosen).

CreateSessionResponse

Returns the current session state

session
Session object

CustomShippingLocation

Locations that are explicitly injected into the session by search.

shipping_method
string
Ingrid's ID of the shipping product. Example `bst-std` for BEST Delivery
location_ref
string
Service point or merchant store location referenced if shipping type is `pickup`
added_at
string
Time when location was injected to session.

CustomerInfo

Contains information about the customer such as name, address, email and mobile phone number

address
Customer's address. Can be delivery or billing address, depending on the use case.
phone
string
Customer's mobile phone number where SMS notifications will be sent.
email
string
Customer's email where email notifications will be sent.

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`.

DeliveryTimeProperties

Helper properties that are passed to the service widget and used for delivery time formatting and overwriting some values.

format
string
Formats of date to display in the widget. Values: days, date, weekday, weekday_date.
use_timespan
boolean
Flag describing whether we should use timespan in delivery time rendering.
custom_text
string
Bypass all formatting logic, just render the custom text.
timespan
Timespan to be used before address is submitted.
ignore_cutoffs
boolean
Ignore cutoffs in timeslot calculation. Normally timeslot is calculated: closest cutoff time + delivery time. By setting ignore_cutoffs to true we calculate timeslot just by adding delivery time to current time.
range
Decides whether widget should show delivery time as range between dates or just end (max) date. TODO: time_formatting should be moved here. Values: interval, max.

DeliveryTimePropertiesTimespan

from
string
to
string

Dimensions

Dimensions of an item in millimeters.

height
integer
Height of the item in millimeters.
length
integer
Length of the item in millimeters.
width
integer
Width of the item in millimeters.

Distance

Walking and driving distance information (if available). This depends if we could reverse geolocate supplied address and succeeded in finding a nearest route from A to B. Usually only available for distance information between address provided by the customer and service point address.

walking
Walking distance in meters
driving
Driving distance in minutes

DistanceSpec

Generic distance object used by Distance object to provide driving and walking information.

value
integer
Approximate distance in meters
duration
integer
Approximate duration in minutes

GetSessionResponse

Returns the current session state

session
Session object

LegLocation

LegLocation represents a location that takes part in a delivery.

address
Address of a location. This is optional when LocationType is WAREHOUSE or HOME, since these values can be obtained from the session.
location_type
Location type. Can be UNKNOWN, WAREHOUSE, STORE or HOME
external_id
string
Possibility to set an external id for this location. Usually service point id or merchant store id

LocationSearchResponse

Returns a list of locations found

locations
List of found locations

OperationalHours

Service points's operational hours

mon
string
tue
string
wed
string
thu
string
fri
string
sat
string
sun
string
free_text
string[]
Free text operational hours. Used as a fallback when the operational hours cannot be parsed correctly

PickupLocation

Contains information about the pickup service point as returned by the carrier.

external_id
string
Carrier specific ID of the service point location returned by the carrier.
name
string
Name or title of the service point as returned by the carrier
address
Visiting address of the service point
distance
Distance between the service point location and customer's delivery address if available.
operational_hours
Operation hours for the service point provided by the carrier if available.
meta
hash
Carrier specific metadata related to the pickup location [t:hash<string,string>]
location_type
carrier_order
string
Order in which the location should be sorted as returned by the carrier.

Result

shipping
category
pricing

ResultCategory

Category selected by the user.

id
string
Id as set by the merchant in configuration.
name
string
Default category name. Used in shipping selector widget to show category name to the customer.
external_id
string
Optional external id that can be used to map to merchant specific ids. Can be set in configuration.

ResultPricing

How much customer should pay.

currency
string
Session's currency. Example `SEK`.
price
integer
Price in cents. Example `20000` represents `200.00`.

ResultShipping

How the package should be shipped to the end customer.

shipping_method
string
Ingrid's ID of the shipping product. Example `bst-std` for BEST Delivery.
delivery_type
string
Type of delivery (pickup, instore, mailbox, delivery).
carrier
string
Name of the shipping company.
product
string
Name of the shipping product.
location
Pickup location if delivery type is `pickup` or `instore`.
delivery_time
When customer can expect package to be delivered.
external_method_id
string
External method identifier, can be used for merchant-specific shipping methods mappings, eg override.
addons
Shipping products addons that are enabled by default. Can be configured in the Merchant Admin tool.
supports
Contains information about the features a shipping option should support.
meta
hash
Carrier specific metadata related to the shipping option, for example addons.
route
Delivery steps.

Route

Route represents a list of delivery steps.

id
string
UUID of the route
shipping_legs
ShippingLegs represent a list of delivery steps. For a non-chained delivery this will contain only one element.

SearchLocation

Location, usually a merchant store, from the data provided by the merchant. SearchLocation is used in the location search. TODO explain more

external_id
string
Merchant specific location id
name
string
Location's name
address
Address of the location
operational_hours
Location's operating hours as provided by the merchant
shipping_method
string
Location's shipping method

Session

A root object of COS system that holds information about the current user transaction. Whenever user selects a shipping option using the shipping selector widget or anything is changed in a cart, session is updated and stored.

id
string
UUIDv4 identifier of the session. Generated when session is created. Used for updating, fetching and completing the session.
token
string
Authorization token used by the shipping selector widget to fetch, update or complete sessions. Generated when the session is created.
status
stringreadonly
Current session status (ACTIVE, COMPLETE). You cannot reactivate a session after it is completed
customer_info
CustomerInfodeprecated
customer_info is only supported for backwards compatibility, use `customer` and `search_address` instead.
cart
Cartrequired
Cart details as items, their weight, dimensions, attributes, quantities as well as shipping date, cart total value and currency.
user_choice
Current user selection of the shipping option. Every time user selects different shipping option, this field is updated.
preselected_choice
Shipping option that is pre-selected by COS for the user. Matches shipping category with preselected flag set to true and reflects the best possible shipping option (based on sorting rules). This is the property to check if a user has not made an active choice.
shipping_categories
Pre-configured shipping categories. All shipping options fall into one of categories. If no shipping options are available, for example when no search_address is provided, possible user choices are made based on categories instead.
shipping_options
Real shipping options (as fetched from carrier integrations). Contains pickup locations with opening hours and time slots and possible delivery times.
purchase_country
stringrequired
Country where the purchase is being made. Should be in sync with the checkout country. Example `SE` for Sweden
purchase_currency
stringrequired
Customer currency. Should be in sync with the checkout currency. Example `SEK`
locale
stringrequired
Customer locale. Sets the language the data is displayed in. Should be in sync with the language in the checkout. Example `sv-SE` for Sweden
external_id
stringoptional
Optional external ID to connect the session with an order on the merchant side. Can be used for troubleshooting and debugging.
choices
List of possible choices generated based on shipping options or categories (if options are missing).
additional_information
Additional information associated with the current session such as door code and delivery notes to courier
expires_at
string
Time at which some of the shipping options will be invalid. This is influenced by the cutoff times at the warehouse among other things. Session should be refreshed if this value is in the past.
tos_id
string
If the session was created from a transport order, it is the id of the order. Only once the session is completed a `tos_id` will be available. See TOS documentation for details.
custom_shipping_locations
Used as a placeholder for custom locations (merchant stores, service points) that are not found by the search_address per default but explicitly injected through `/session.addLocation`. This is related to the search functionality.
customer
Information about the customer such as name, email, phone and address. This information is required when completing a session and is usually taken from the payment provider in the time of purchase. Information is used to calculate best shipping option and pickup location if no active selection has been made by the customer earlier during the checkout.
search_address
Lookup address for delivery. May be an office address if customer wants to pick up a package close to his/her work place. Minimum required field is country and postal code.
updated_at
string
Information about when the session was last updated.
result
Selected shipping option. This is the place at, when checking which shipping option was selected. If the selected shipping option is based on the user choice (user_choice is not empty), it contains details of the user choice. Otherwise, it contains details of the preselected choice.

ShippingCategory

Category which can group multiple shipping products of the same delivery type. It's not possible for a category to bundle shipping products of different kinds.

id
string
Id as set by the merchant in configuration
name
string
Default category name. Used in shipping selector widget to show category name to the customer.
price
integerdeprecated
Use `prices` instead.
sort_order
integer
The order which a category will be rendered in shipping selector widget.
region_ids
string[]
A list of regions that a category belongs to
shipping_methods
string[]
A list of shipping methods a category supports.
custom_text
string
Additional text that will be displayed below the category name in the shipping selector widget
custom_info_text
string
Information text that will be displayed in the shipping selector widget. Can for example be used to provide the customer with edge cases or other type of deviations.
preselected
boolean
Indicated if this category is preselected by default in cases when there is no information about the current user. Can be set in configuration.
requirements
Enables of disables certain features in shipping selector widget
delivery_type
string
Delivery type that this category supports
time_slot
Delivery time promise. Describes when it will be delivered. TODO describe expires_at
external_id
string
Optional external id that can be used to map to merchant specific ids. Can be set in configuration.
currency
string
Currency of the category
prices
hash
Prices per shipping product in cents when no customer data is known yet [t:hash<string,number>]
group_id
stringinternal
Not used
custom_unavailable_text
stringinternal
Not used
time_formatting
Controls how delivery time will be displayed in the shipping selector widget Deprecated in favour of DeliveryTimeProperties.range
pickup_location_types
Used for filtering of pickup location types, eg. to restrict the locations to "manned", "lockers", "post offices", etc.
delivery_time_properties
DeliveryTimeProperties contains various helper properties that are passed to the service widget.

ShippingCategoryRequirements

Settings that controls functionality of the shipping selector widget

address
boolean
Decides if address fields should be shown in the shipping selector widget
hide_shipping_options
boolean
Decides if service point selection should be enabled in the shipping selector widget
use_price_from
boolean
Decides if shipping selector widget should show category prices as `from XX SEK` before an address is provided.
customer_number
boolean
Decides if customer number input should be enabled. Only used for DHL lockers in Germany at the moment.

ShippingCost

Detailed information about the shipping cost.

billing_items
List of individual cost items
total_cost
Total shipping cost in cents.

ShippingLeg

ShippingLeg represents a single step of package delivery.

shipping_method
string
Shipping product used for this step
delivery_type
string
Step's delivery type
from
Origin address. Can be warehouse or service point or merchant store address.
to
Destination address. Can be warehouse or service point or merchant store address or customer's home address.

ShippingOption

Option presented to the customer based on the provided customer information.

shipping_method
string
Ingrid's ID of the shipping product. Example `bst-std` for BEST Delivery
delivery_type
string
Type of delivery (pickup, instore, mailbox, delivery)
carrier
string
Name of the shipping company
product
string
Name of the shipping product
price
integerdeprecated
Use Prices on ShippingCategory instead.
currency
stringdeprecated
Use Currency on ShippingCategory instead.
locations
Service points available for the shipping option if delivery type is `pickup` or `instore`
time_slots
Time slots available for the shipping option indicating when customer can expect package to be delivered
external_method_id
string
External method identifier, can be used for merchant-specific shipping methods mappings, eg override.
default_addons
Shipping products addons that are enabled by default. Can be configured in the Merchant Admin tool.
supports
Contains information about the features a shipping option should support. Basically, feature toggles that are configured in the Merchant Admin tool.
meta
hash
Carrier specific metadata related to the shipping option, for example addons. [t:hash<string,string>]
routes
Represents all possible combinations for delivery steps.
shipping_cost
Contains detailed information about the shipping cost such as cost for additional services

Supports

search
boolean
door_code
boolean
courier_instructions
boolean
customer_number
boolean

TimeSlot

Contains information about estimated delivery times TODO

id
string
Unique ID of the time slot
expires
string
Defines the point in time when this timeslot is not valid any longer and will expire
start
string
Earliest delivery date in RFC3339 format. No specific time of day is promised if the time part is 00:00:00
end
string
Latest delivery date in RFC3339 format. No specific time of day is promised if the time part is 00:00:00

UpdateSessionRequest

Contains the data needed to update the session

id
stringrequired
Session ID
user_choice
Current user selection of the shipping option. Every time user selects different shipping option, this field is updated.
customer_info
CustomerInfodeprecated
Use `customer` property instead
cart
Cartrequired
Cart details as items, their weight, dimensions, attributes, quantities as well as shipping date, cart total value and currency.
additional_info
Additional information associated with the current session such as door code and delivery notes to courier
customer
Information about the customer such as name, email, phone and address. This information is required when completing a session and is usually taken from the payment provider in the time of purchase. Information is used to calculate best shipping option and pickup location if no active selection has been made by the customer earlier during the checkout.
search_address
Lookup address for delivery. May be an office address if customer wants to pick up a package close to his/her work place. Minimum required field is country and postal code.
external_id
stringoptional
Optional external ID to connect the session with an order on the merchant side. Can be used for troubleshooting and debugging.

UpdateSessionResponse

Result of the update session call

session
Current session state
Last Updated: 3/13/2020, 2:31:37 PM