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 |
| building_name 🔗 |
string
in the UK some buildings do not have a number, only a name |
| 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 |
| floor_number 🔗 |
string
optional
Floor number |
| name 🔗 |
string
Customer or company name |
| po_box_id 🔗 |
string
optional
ID of the PO Box |
| 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 |
| subregion 🔗 |
string
optional
Further division of regions. Example countries are GB, IE, IT, LT, MX For example for The Republic Of Ireland there are 4 provinces (regions), e.g. `Connacht` and 26 counties (subregions), e.g. `Galway` Format is ISO 3166 where applicable, exceptions are e.g. Mexico |
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
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 |
| external_id 🔗 |
string
Unique address identifier |
| 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 |
| phone_country 🔗 |
string
optional
Phone number country of the recipient 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 |
| 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 or unique hashed 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.
| attributes 🔗 |
string[]
Attributes list of a single delivery group. Used to control the behaviour of the `cart_attributes()` filter rule for each group individually |
| 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
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 🔗 |
integer
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
Coordinates
Geolocation coordinates
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 |
| external_id 🔗 |
string
Unique address identifier |
| 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 |
| phone_country 🔗 |
string
optional
Phone number country of the recipient 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 |
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.
| base_price 🔗 |
integer
Base price of the carrier product for the given Delivery Promise |
| 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.
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
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` |
| net_price 🔗 |
integer
optional
Net price of the delivery option. Unit are cents |
| 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) |
| external_method_id 🔗 |
string
External method identifier, can be used for merchant-specific shipping methods mappings, eg override |
| 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 |
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.
DistanceSpec
Generic distance object used by Distance object to provide driving and walking information.
Error
GetSessionResponse
GroupContent
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.
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 🔗 |
Indicates if the component is the cost of shipping or the one of an addon |
| value 🔗 |
integer
Gross price |
| vat 🔗 |
integer
optional
Amount of tax |
| vat_rate 🔗 |
number
optional
Tax rate of the delivery option |
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
SectionColumnItem
| items 🔗 |
SectionItem
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 |
| purchase_country 🔗 |
string
The country of the purchase |
| status 🔗 |
SessionSessionStatus
readonly
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
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 |