Object Reference

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`
total_discount
integeroptional
Discount amount in cents. Example `2000` is `20.00`.
currency
stringrequired
Cart's currency. Should be in sync with the checkout. Example `SEK`
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.
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.
cart_id
stringrequired
Unique cart id for the customers cart on the merchant side.
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.

CompleteSessionRequest

Contains the data needed to complete a session

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 address.
customer
CustomerInforequired
Customer information (name, email, phone number and address)
external_id
stringoptional
Can be used to store a unique identifier from the merchant. For example external order ID

CompleteSessionResponse

Returns the completed session state

session
Final session state
tos_id
stringdeprecated
Deprecated, use the `tos_id` on the session instead.

Coordinates

Geolocation coordinates

lat
number
Latitude
lng
number
Longitude

Cost

Cost amount

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

CreateSessionRequest

Contains the required information to initialize a new session.

purchase_country
stringrequired
The country of the purchase. Example SE
purchase_currency
stringrequired
The currency of the purchase. Example SEK
locale
stringdeprecated
Use `locales` property instead
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.
external_id
stringoptional
Can be used to store a unique identifier from the merchant. For example external order ID
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[]required
List of locales to load the shipping selector widget in, in order of preference (first supported one will be used)

CreateSessionResponse

Contains the session object and shipping selector HTML snippet

session
Session object
html_snippet
string
HTML snippet to be included on the page

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 to

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

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 and shipping selector HTML snippet

session
Session object
html_snippet
string
HTML snippet to be included on the page

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

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
The type of pickup location. Can be `UNKNOWN_PICKUP_LOCATION_TYPE, LOCKER, STORE, POSTOFFICE, MANNED`

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

A route represents a list of delivery steps for a chained delivery.

id
string
Id of the route
shipping_legs
ShippingLegs represent a list of delivery steps.

SelectedShippingOption

Contains shipping option chosen by the user after the session is completed

shipping_method
string
Unique identifier of the shipping product. Example `pnl-mpc` which is the id for PostNord MyPack Collect
delivery_type
string
Type of delivery (pickup, instore, mailbox, delivery)
carrier
string
Company name of the shipping company
product
string
Name of the shipping product
price
integer
Shipping price in cents. Example `10000` is `100.00` SEK
currency
string
Shipping currency. Example `SEK`
location
Service point, pre-selected by us or actively selected by the customer. Only available for delivery type 'pickup' or 'instore'
time_slot
Information about the delivery time. Estimation on when the shipment is expected to be delivered to the customer.
shipping_category
string
Shipping category under which the selected shipping options are grouped. Shipping categories are setup and configured in the merchant admin tool.
external_method_id
string
External method identifier that can be used for custom shipping methods mappings, eg overriding a shipping product id from Ingrid by merchant's own. This mapping needs to be setup in the Merchant Admin tool.
meta
hash
Carrier specific metadata related to the shipping option, for example addons. [t:hash<string,string>]
routes
Routes represent a list of delivery steps. This is used for so called chained deliveries where there are more than two deliveries involved to deliver a package to the customer. For example from central warehouse to the service point and then from a service point to customer's house. For a non-chained delivery this will contain only one step.

Session

Contains information about the current session. Each session is unique for every customer transaction

id
string
UUIDv4 identifier of the session. Generated when session is created. Used for updating, fetching and completing the session.
status
stringreadonly
Current session status (ACTIVE, COMPLETE). You cannot reactivate a session after it is completed
customer_info
CustomerInfodeprecated
CustomerInfo is only supported for backwards compatibility, use Customer and SearchAddress instead.
cart
Cartrequired
Cart details as items, their weight, dimensions, attributes, quantities as well as shipping date, cart total value and currency.
selected_shipping_option
Currently selected shipping option. Contains information about shipping product and eventual pickup location
external_id
string
Can be used to store a unique identifier from the merchant. For example external order ID or external shipment ID.
shipping_price
integer
Price of currently selected (or pre-selected) shipping option.
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.
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
This property is used by the shipping selector widget when customer enters her address information. Can be populated upfront by the merchant if information about the customer is known, for example for customers who are already logged in. If this property is populated the data in it is used to calculate the best shipping option.
tos_id
string
Identifies the transport order (TO) which the session belongs to. This id is only available when the session is completed of if the session was created from a transport order
shipping_cost
Contains detailed information about the shipping cost such as cost for additional services
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.

ShippingCost

Detailed information about the shipping cost.

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

ShippingLeg

Represents a single step in the chained delivery.

shipping_method
string
Shipping product used in this delivery step
delivery_type
string
Step's delivery type
from
Information about the origin location. Can be a warehouse or a service point or a merchant store.
to
Information about the destination location. Can be a warehouse or a service point or a merchant store or a customer's home address.

Supports

Contains information about features that a shipping option supports. Configurable in Merchant Admin tool.

search
boolean
Indicates if search should be enabled
door_code
boolean
Indicates if shipping option supports door code. If true, a door code input will be displayed in the shipping selector widget. Only applicable for home delivery type.
courier_instructions
boolean
Indicates if shipping option supports courier notes. If true, a courier instructions input will be displayed in the shipping selector widget. Only applicable for home delivery type.
customer_number
boolean
Indicates if shipping option supports carrier specific customer number. If true, a carrier number input will be displayed in the shipping selector widget. Only applicable for DHL Germany at this moment, where customer has to provide a number that identifies a pickup locker.

TimeSlot

Contains information about estimated delivery times

id
string
Unique ID of the time slot
external_id
string
External ID TODO
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
customer_info
CustomerInfodeprecated
Use `customer` property instead
cart
Cart details as items, their weight, dimensions, attributes, quantities as well as shipping date, cart total value and currency
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
Can be used to store a unique identifier from the merchant. For example external order ID

UpdateSessionResponse

Returns the current session state

session
Session object
Last Updated: 3/13/2020, 2:31:37 PM