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

Any

type_url
string
value
string

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
ShippingDateoptional
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. Multiple shipping dates with appropriate tags can be specified inside internal field `category_tags`. 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.
attributes
string[]optional
Attributes of the Cart. Cart level attributes are specific to the cart or for the full cart contents. Ingrid Delivery Checkout can set varied delivery scenarios based on such attributes. Ex. [“PRIO”, “AB-testID”]

CartItem

Product in the shopping cart

sku
stringrequired
Unique product identifier
name
stringoptional
Product name or title
attributes
string[]optional
Attributes of Cart items. Often referred to as ‘tags’. Cart Item level attributes are specific to that particular item and can be set to adjust delivery scenarios in Ingrid Delivery Checkout. A typical scenario is disabling of one or many delivery options based on cart containing cart items with certain attributes. Ex. [“SendAsLetter”, “Prescription”, “Hazmat”]
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. The address information is used as recipient address information to correctly calculate the correct shipping option.
search_address
Lookup address for generating delivery options. Could be any address such as (office address) if customer e.g. want to pickup their delivery 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)
meta
hash
Generic key/value object that is used for supplying complementing information.
snippet_configuration
Snippet configuration allows using custom ids in html snippet. This useful, if there are multiple widgets embedded on the same page.
delivery_price_discount
integer
Reduces the price with the given amount for all delivery options presented to the consumer. Prices that would go below zero is set to zero.

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/Recipient address. The address information is used as recipient address information to correctly calculate the correct shipping option.
phone
string
Customer's mobile phone number where SMS notifications will be sent.
email
string
Customer's email where notifications will be sent to.
national_identification_number
string
Customer's national identification number, eg. SSN.

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:31Z07:00`
end
string
End of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31Z07: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

Error

error
string
code
integer
message
string
details

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

ListSessionsSummariesResponse

Contains the list of session IDs with result fields.

results

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

PriceComponent

Specifies a single price component.

id
string
type
value
integer
vat_rate
number
vat
integer

Result

Summary of the shipment.

shipping
Details about the delivery promise given in a Checkout session, such as specifications of the selected Carrier, Pickup Location information, Routing and Integration mapping IDs.
category
Details about the selected Delivery Category for this Delivery Promise.
pricing
Pricing information for selected Delivery Promise with currency details.
selection
Defines how result was obtained.
delivery_time
Details the Delivery time aspects of the Delivery promise given in Delivery Checkout.

ResultCategory

The Delivery Category selected by the User.

id
string
The Ingrid internal ID of the category.
name
string
Default category name. This admin name of the delivery category. This would be shown to end user if there are no translations set for the category.
external_id
string
Optional external id that can be used to map to merchant specific ids. Can be set in configuration.
tags
The category tags set in Ingrid Merchant Platform for that specific Delivery Category.
presented_category_name
string
The name of the category that was actually presented to the end user.

ResultDeliveryAddon

Specifies a single selected addon.

id
string
external_addon_id
string

ResultDeliveryTime

Listing of Delivery Time Components produced by the Ingrid Delivery Checkout.

pickup_from_merchant
The date & time when the parcel is understood by Ingrid Delivery Checkout and is possible to collect from Merchant Warehouse or Store.
customer_delivery_promise
The date & time used to present the delivery time promise to the end user. (When time is set to 00:00 it means Ingrid has presented a set of days or business days e.g. 2-3 Business days).
carrier_delivery_promise
The Date & Time response returned by Ingrid Carrier integrations that specify when carriers say they could deliver the parcel. This notion could differ from customer_delivery_promise since a carrier could have deliveries on eg. Saturdays but a user has configured Ingrid Delivery Checkout to communicate only business days. For such situation, Ingrid would move the customer_delivery_promise to the next possible business day.

ResultDeliveryTimeRange

earliest
string
latest
string

ResultPricing

The price of the delivery promise from Ingrid Delivery Checkout. Given as a total or divided into it is components for cases such as separating eg. Delivery Addons selected by the user during checkout.

currency
string
Session's currency. Example `SEK`.
price
integer
Price in cents. Example `20000` represents `200.00`.
price_components
Components which make up the price.

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.
delivery_addons
Selected delivery addons.
warehouse
Address of the warehouse from which the package will be shipped.

ResultWarehouse

address

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.

Section

name
string
columns

SectionColumnItem

items

SectionItem

icon
string
text
string
link
string

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

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. The address information is used as recipient address information to correctly calculate the correct shipping option.
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.
experiment_id
string
Identifier of an A/B testing experiment, which is related to the session. If the session is not related to any A/B testing experiment, this field is empty.

SessionSummary

Contains the result field associated with session id.

session_id
string
result

ShippingCost

Detailed information about the shipping cost.

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

ShippingDate

Information about possible shipping dates

start
string
Start of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31Z07:00`
end
string
End of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31Z07:00`.
category_tags
Multiple shipping dates with appropriate tags

ShippingDateTag

name
string
Name of the category tag.
shipping_date
Shipping date for the category tag.

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.

SnippetConfiguration

container_id
string
object_id
string
loader_id
string

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.

Tag

name
string

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. The address information is used as recipient address information to correctly calculate the correct shipping option.
search_address
Lookup address for generating delivery options. Could be any address such as (office address) if customer e.g. want to pickup their delivery 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
purchase_country
string
The country of the purchase. Example SE
purchase_currency
string
The currency of the purchase. Example SEK
locales
string[]
List of locales to load the shipping selector widget in, in order of preference (first supported one will be used)
meta
hash
Generic key/value object that is used for supplying complementing information.
snippet_configuration
Snippet configuration allows using custom ids in html snippet. This useful, if there are multiple widgets embedded on the same page.
delivery_price_discount
integer
Reduces the price with the given amount for all delivery options presented to the consumer. Prices that would go below zero is set to zero.

UpdateSessionResponse

Returns the current session state

session
Session object
html_snippet
string
HTML snippet to be included on the page
Last Updated: 11/23/2021, 9:15:27 AM