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
Total non-negative discount amount in cents. Example `2000` is `20.00`. |
| total_value |
integer
required
Total non-negative 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
Non-negative 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
Non-negative price of the item. Can be used by the shipping rule engine to calculate the best shipping option. |
| quantity |
integer
Total non-negative number of 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 |
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 |
|
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.
| results |
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.
| 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 |
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
| items |
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 |
ShippingDateTag[]
optional
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 |
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 |