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

Addresses

All address information related to one delivery group.

billing_address

Billing information to be sent to the payment provider

customer

Customer information received from the merchant

delivery_address

Information about delivery address of recipient of the shipment

location

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

search_address

Search Address when not in the address form flow

Any

type_url
string

value
string

BillingAddress

address_lines
string[]

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

company_name
string optional

The name of the company

country
string

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

email
string

Email address of the recipient

first_name
string

The first name of the recipient

last_name
string

The last name of the recipient

phone
string

Phone number of the recipient

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

vat
string optional

Value Added Tax identifier

vat_type
string optional

Type of the VAT number

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

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

groups
CartGroup[] optional

Specification of groups to which the cart items should be assigned

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

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

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. Multiple shipping dates with appropriate tags can be specified inside internal field `category_tags`. It applies to all cart items. If this property is not set Ingrid defaults to today's date

total_discount
integer required

Total non-negative discount amount in cents. Example `2000` is `20.00`

total_value
integer required

Total non-negative cart value in cents after discounts applying. Example `20000` represents `200.00`

vouchers
string[]

Vouchers that can be used in price/filter rules

CartGroup

Optional specification of group to which the cart items should be assigned.

cart_item_sku_list
string[] deprecated

Deprecated: use contents instead. List of cart item SKUs (unique product identifiers) that belong to the given group. SKUs in the list must match the ones provided on cart items

consolidatable
boolean

Indicates, that the group could be consolidated (merged into single group with other consolidatable groups)

contents
GroupContent[] required

List of cart item splits by each group. For example: Different sku quantities can be split between groups(orders)

group_id
string required

Unique identifier of group passed when doing split of shipments

header
string

Header text containing arbitrary information related to the group

CartItem

Product in the shopping cart

attributes
string[]

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 required

Non-negative discount for the given item. Can be used by the shipping rule engine to calculate the best shipping option

image_url
string

URL of the image of the given cart item

name
string required

Product name or title

out_of_stock
boolean

Flag indicating if the item is currently out of stock

price
integer required

Non-negative price of the item after the discount applied. Can be used by the shipping rule engine to calculate the best shipping option

quantity
integer required

Total number of the product item in the cart

shipping_date

Date the item 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 used, it overrides shipping date of a single item, remaining items have shipping date cascaded from `cart.shipping_date`

site_external_id
string

Site external ID can be used in case of marketplace configuration. If sent empty, top level site will be used

sku
string required

Unique product identifier

weight

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,01 kg

CompleteSessionRequest

checkout_session_id
string required

Checkout session 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

external_id
string optional

Connects the session with an order on the merchant side. Can be used for troubleshooting and debugging. It has to be provided before the session is completed

CompleteSessionResponse

session

Final session state

Coordinates

Geolocation coordinates

lat
number

Latitude

lng
number

Longitude

CreateSessionRequest

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

external_id
string optional

Connects the session with an order on the merchant side. Can be used for troubleshooting and debugging. It has to be provided before the session is completed

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

prefill_delivery_address

Prefill Delivery Address be used to prepopulate address form

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

CreateSessionResponse

html_snippet
string

HTML snippet to be included on the page

session

Session object

token
string

Token generated for this session

CustomerAddress

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

email
string

Email address of the customer

name
string

The name of the customer

phone
string

Phone number of the customer

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

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`

DeliveryAddress

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

company_name
string optional

The name of the company

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

email
string

Email address of the recipient

first_name
string

The first name of the recipient

last_name
string

The last name of the recipient

phone
string

Phone number of the recipient

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

DeliveryGroup

Summary of the order.

addresses

All important addresses in a single place

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

external_id
string optional

Connects the delivery group with an order on the merchant side. Can be used for troubleshooting and debugging

group_id
string

Identifier of delivery group used to perform splitting of shipments

header
string

Header text containing arbitrary information related to the delivery group

items

Cart items that belong to the delivery group

pricing

Pricing information for selected Delivery Promise with currency details

selection

Defines how selected Delivery Promise 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

tos_id
string

Identifier of order created based on completed session. By default, orders are created asynchronously so the identifier might need to be re-fetched

DeliveryGroupCategory

The Delivery Category selected by the User.

custom_text
string

User-defined custom text displayed near the category in shipping selector widget

custom_warning_text
string

User-defined custom warning text displayed near the category in shipping selector widget, that indicates e.g. edge cases related to the given category

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

DeliveryGroupDeliveryAddon

Specifies a single selected addon.

external_addon_id
string

id
string

DeliveryGroupDeliveryTime

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

DeliveryGroupDeliveryTimeRange

earliest
string

latest
string

DeliveryGroupItem

Item that belongs to a delivery group.

quantity
integer

Quantity of cart item

shipping_date

Shipping date set for the item

site_external_id
string

Site external ID can be used in case of marketplace configuration to split items by marketplace merchant. If sent empty, top level site will be used

sku
string

Unique cart item's product identifier

DeliveryGroupPricing

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

DeliveryGroupShipping

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

carrier_product_id
string

Identifier of chosen carrier product, can be used for merchant-specific shipping methods mappings. If external method identifier is defined on carrier product, its value is passed in this field. Otherwise, shipping method from carrier product is passed

delivery_addons

Selected delivery addons

delivery_type
string

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

meta
hash

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

product
string

Name of the shipping product

route

Delivery steps

supports

Contains information about the features a shipping option should support

warehouse

Address of the warehouse from which the package will be shipped

DeliveryGroupWarehouse

address

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

html_snippet
string

HTML snippet to be included on the page

session

Session object

GroupContent

quantity
integer

sku
string

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, HOME or PICKUP

ListSessionsSummariesResponse

Contains the list of session IDs with result fields.

external_id
string

result

tos_id
string

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

Route

Route represents a list of delivery steps.

shipping_legs

ShippingLegs represent a list of delivery steps. For a non-chained delivery this will contain only one element

SearchAddress

address_lines
string[]

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

apartment_number
string

Number of the apartment

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

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

Section

columns

name
string

SectionColumnItem

SectionItem

icon
string

link
string

text
string

Session

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

additional_information

Additional meta information related to the session

cart

Checkout cart details as items, their weight, dimensions, attributes, quantities as well as shipping date, cart total value and currency

checkout_session_id
string

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

delivery_groups

Delivery groups contain information about session results. Information about order, selection and price can be found here. If split shipment is disabled, delivery groups contain only one entry

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

status

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

updated_at
string

Datetime indicating when the session was last updated

SessionSummary

addresses

All important addresses in a single place

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 selected Delivery Promise was obtained

shipping

Details about the delivery promise given in a Checkout session, such as specifications of the selected Carrier, Routing and Integration mapping IDs

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

ShippingLeg represents a single step of package delivery.

delivery_type
string

Step's delivery type

from

Origin address. Can be warehouse or service point or merchant store address

shipping_method
string

Shipping product used for this step

to

Destination address. Can be warehouse or service point or merchant store address or customer's home address

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

UpdateSessionRequest

cart

Cart details as items, their weight, dimensions, attributes, quantities as well as shipping date, cart total value and currency

checkout_session_id
string required

Checkout session id

external_id
string optional

Connects the session with an order on the merchant side. Can be used for troubleshooting and debugging. It has to be provided before the session is completed

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

prefill_delivery_address

Prefill Delivery Address be used to prepopulate address form

purchase_country
string

The country of the purchase

purchase_currency
string

The currency of the purchase

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

UpdateSessionResponse

html_snippet
string

HTML snippet to be included on the page

session

Session object

Last updated: Thu, Mar 30, 06:15 AM