Documentation

Object Reference

AdditionalInfo

Additional meta information related to the session.

courier_instructions
string optional

Courier instruction provided by the customer

customer_number
string optional

Optional customer number provided by the user. Sometimes required by specific shipping products. For example DHL lockers in Germany

door_code
string optional

Entrance door code provided by the customer that can be used by the courier to get in

Address

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

address_lines
string[]

List of address lines part of address such as street and building number

apartment_number
string

Number of the apartment.

attn
string optional

Attention field. Can be used to indicate an employee if the address is a company address

care_of
string optional

Care of part of address usually written as `c/o`

city
string

Name of the city

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.

country
string

Country should be specified as two uppercase letters (ISO Alpha-2). Example `SE` for Sweden, `ES` for Spain.

door_code
string optional

The door code to the main entrance of the building if applicable

name
string

Customer or company name

postal_code
string

Postal code (or zipcode in US)

region
string optional

Region can be a state or a province

street
string

Name of the street.

street_number
string

Number of the street.

Any

type_url
string

value
string

BillingItem

Individual billing item of the total shipping cost.

cost

Individual cost in cents. Example `1000` is 10 SEK

description
string

The kind of shipping cost. Can be pure shipping cost, addon or additional service.

CarrierAddon

Carrier specific addons

code
string

Identifier of the addon in carrier's system.

description
string

Description of the addon's functionality

name
string

Internal identifier of an addon.

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.

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”]

cart_id
string required

Unique cart id for the customers cart on the merchant side.

currency
string required

Cart's currency. Should be in sync with the checkout. Example `SEK`

items
CartItem[] required

Information about the individual order items. This can be used by the shipping rule engine to calculate the best shipping option.

pre_order
boolean optional

Indicated if the order can be shipped earliest on the provided shipping date

shipping_date
ShippingDate optional

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.

total_discount
integer optional

Discount amount in cents. Example `2000` is `20.00`.

total_value
integer required

Total cart value in cents. Example `20000` represents `200.00`

voucher
string deprecated

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.

vouchers
string[] optional

Vouchers that can be used in price/filter rules.

CartItem

Product in the shopping cart

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”]

dimensions

Dimensions of this cart item. Can be used by the shipping rule engine to calculate the best shipping option.

discount
integer optional

Eventual discount of the item. Can be used by the shipping rule engine to calculate the best shipping option.

name
string optional

Product name or title

out_of_stock
boolean optional

Flag indicating if the item is currently out of stock

price
integer optional

Price of the item. Can be used by the shipping rule engine to calculate the best shipping option.

quantity
integer

Total number product item in the cart.

sku
string required

Unique product identifier

weight
integer optional

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.

CompleteSessionRequest

Contains the data needed to complete a session

customer
CustomerInfo required

Customer information (name, email, phone number and address)

customer_info
CustomerInfo deprecated

Use Customer property instead

external_id
string optional

Can be used to store a unique identifier from the merchant. For example external order ID

id
string required

Session ID

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.

CompleteSessionResponse

Returns the completed session state

session

Final session state

tos_id
string deprecated

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

CreateSessionFromOrderRequest

Contains the required information to initialize session from transport order.

external_id
string optional

Can be used to store a unique identifier from the merchant. For example external order ID

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.

tos_id
string

Transport order ID from which a new session will be created

CreateSessionFromOrderResponse

Contains the session object from tos order and shipping selector HTML snippet

html_snippet
string

HTML snippet to be included on the page

session

Session object

CreateSessionRequest

Contains the required information to initialize a new session.

cart
Cart required

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.

customer_info
CustomerInfo deprecated

Use `customer` property instead

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.

external_id
string optional

Can be used to store a unique identifier from the merchant. For example external order ID

locale
string deprecated

Use `locales` property instead

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.

purchase_country
string required

The country of the purchase. Example SE

purchase_currency
string required

The currency of the purchase. Example SEK

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.

snippet_configuration

Snippet configuration allows using custom ids in html snippet. This useful, if there are multiple widgets embedded on the same page.

CreateSessionResponse

Contains the session object and shipping selector HTML snippet

html_snippet
string

HTML snippet to be included on the page

session

Session object

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.

email
string

Customer's email where notifications will be sent to.

national_identification_number
string

Customer's national identification number, eg. SSN.

phone
string

Customer's mobile phone number where SMS notifications will be sent.

DateTimeRange

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

end
string

End of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31Z`.

start
string

Start of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31Z`

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.

driving

Driving distance in minutes

walking

Walking distance in meters

DistanceSpec

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

duration
integer

Approximate duration in minutes

value
integer

Approximate distance in meters

Error

code
integer

details

error
string

message
string

GetSessionResponse

Returns the current session state and shipping selector HTML snippet

html_snippet
string

HTML snippet to be included on the page

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.

external_id
string

Possibility to set an external id for this location. Usually service point id or merchant store id

location_type

Location type. Can be UNKNOWN, WAREHOUSE, STORE or HOME

ListSessionsSummariesResponse

Contains the list of session IDs with result fields.

OperationalHours

Service points's operational hours

free_text
string[]

Free text operational hours. Used as a fallback when the operational hours cannot be parsed correctly

fri
string

mon
string

sat
string

sun
string

thu
string

tue
string

wed
string

PickupLocation

Contains information about the pickup 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.

external_id
string

Carrier specific ID of the service point location returned by the carrier.

location_type

The type of pickup location. Can be `UNKNOWN_PICKUP_LOCATION_TYPE, LOCKER, STORE, POSTOFFICE, MANNED`

meta
hash

Carrier specific metadata related to the pickup location [t:hash<string,string>]

name
string

Name or title of the service point as returned by the carrier

operational_hours

Operation hours for the service point provided by the carrier if available.

sections

PriceComponent

Specifies a single price component.

id
string

type

value
integer

vat
integer

vat_rate
number

Result

Summary of the shipment.

category

Details about the selected Delivery Category for this Delivery Promise.

delivery_time

Details the Delivery time aspects of the Delivery promise given in Delivery Checkout.

pricing

Pricing information for selected Delivery Promise with currency details.

selection

Defines how result was obtained.

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.

ResultCategory

The Delivery Category selected by the User.

external_id
string

Optional external id that can be used to map to merchant specific ids. Can be set in configuration.

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.

presented_category_name
string

The name of the category that was actually presented to the end user.

tags

The category tags set in Ingrid Merchant Platform for that specific Delivery Category.

ResultDeliveryAddon

Specifies a single selected addon.

external_addon_id
string

id
string

ResultDeliveryTime

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

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.

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

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.

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.

addons

Shipping products addons that are enabled by default. Can be configured in the Merchant Admin tool.

carrier
string

Name of the shipping company.

delivery_addons

Selected delivery addons.

delivery_time

When customer can expect package to be delivered.

delivery_type
string

Type of delivery (pickup, instore, mailbox, delivery).

external_method_id
string

External method identifier, can be used for merchant-specific shipping methods mappings, eg override.

location

Pickup location if delivery type is `pickup` or `instore`.

meta
hash

Carrier specific metadata related to the shipping option, for example addons.

product
string

Name of the shipping product.

route

Delivery steps.

shipping_method
string

Ingrid's ID of the shipping product. Example `bst-std` for BEST Delivery.

supports

Contains information about the features a shipping option should support.

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

columns

name
string

SectionColumnItem

SectionItem

icon
string

link
string

text
string

SelectedShippingOption

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

carrier
string

Company name of the shipping company

category_tags

currency
string

Shipping currency. Example `SEK`

delivery_type
string

Type of delivery (pickup, instore, mailbox, delivery)

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.

location

Service point, pre-selected by us or actively selected by the customer. Only available for delivery type 'pickup' or 'instore'

meta
hash

Carrier specific metadata related to the shipping option, for example addons. [t:hash<string,string>]

price
integer

Shipping price in cents. Example `10000` is `100.00` SEK

product
string

Name of the shipping product

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.

shipping_category
string

Shipping category under which the selected shipping options are grouped. Shipping categories are setup and configured in the merchant admin tool.

shipping_method
string

Unique identifier of the shipping product. Example `pnl-mpc` which is the id for PostNord MyPack Collect

time_slot

Information about the delivery time. Estimation on when the shipment is expected to be delivered to the customer.

Session

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

additional_information

Additional information associated with the current session such as door code and delivery notes to courier

cart
Cart required

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.

customer_info
CustomerInfo deprecated

CustomerInfo is only supported for backwards compatibility, use Customer and SearchAddress instead.

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.

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.

external_id
string

Can be used to store a unique identifier from the merchant. For example external order ID or external shipment ID.

id
string

UUIDv4 identifier of the session. Generated when session is created. Used for updating, fetching and completing the session.

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.

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.

selected_shipping_option

Currently selected shipping option. Contains information about shipping product and eventual pickup location

shipping_cost

Contains detailed information about the shipping cost such as cost for additional services

shipping_price
integer

Price of currently selected (or pre-selected) shipping option.

status
string readonly

Current session status (ACTIVE, COMPLETE). You cannot reactivate a session after it is completed

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

SessionSummary

Contains the result field associated with session id.

result

session_id
string

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

category_tags

Multiple shipping dates with appropriate tags

end
string

End of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31Z07:00`.

start
string

Start of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31Z07:00`

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.

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.

shipping_method
string

Shipping product used in this delivery step

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

loader_id
string

object_id
string

Supports

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

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.

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.

search
boolean

Indicates if search should be enabled

Tag

name
string

TimeSlot

Contains information about estimated delivery times

end
string

Latest delivery date in RFC3339 format. No specific time of day is promised if the time part is 00:00:00

expires
string

Defines the point in time when this timeslot is not valid any longer and will expire

external_id
string

External ID TODO

id
string

Unique ID of the time slot

start
string

Earliest 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

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.

customer_info
CustomerInfo deprecated

Use `customer` property instead

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.

external_id
string optional

Can be used to store a unique identifier from the merchant. For example external order ID

id
string required

Session ID

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.

purchase_country
string

The country of the purchase. Example SE

purchase_currency
string

The currency of the purchase. Example SEK

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.

snippet_configuration

Snippet configuration allows using custom ids in html snippet. This useful, if there are multiple widgets embedded on the same page.

UpdateSessionResponse

Returns the current session state

html_snippet
string

HTML snippet to be included on the page

session

Session object

Last updated: Mon, Jan 17, 09:51 AM