Headless Checkout API - Reference
Overview
Ingrid provides HTTP endpoints returning data in JSON format. We provide you with two environments:
- Stage - is our staging and testing environment where you do all the testing and developing against
- Production - is the production environment that you switch to when it’s time to go live
Object Reference
Addon
An Addon represents an additional service or feature offered with a delivery.
| display_name 🔗 |
string
required
The display-friendly name of the addon, e.g., "Gift Wrapping", "Leave at Door" |
| price 🔗 |
string
The price of the addon in minor currency units, e.g., cents |
| addon_type 🔗 |
The type of the addon |
| preselected 🔗 |
boolean
Indicates if this addon should be preselected by default |
| chosen 🔗 |
boolean
Indicates if this addon was chosen |
| id 🔗 |
string
Unique addon identifier |
AddonAddonType
AddonType defines the specific type of addon offered.
- ADDON_TYPE_UNSPECIFIED: Addon type is unspecified or unknown.
- CUSTOM: A custom addon specified by the carrier or merchant.
- CARRY_IN: An addon for carrying the delivery item into the recipient's premises.
- LEAVE_AT_DOOR: An addon for leaving the item at the door without requiring a signature.
- UNWRAPPING: An addon for unwrapping the delivered item.
Enum Values:
- ADDON_TYPE_UNSPECIFIED
- CUSTOM
- CARRY_IN
- LEAVE_AT_DOOR
- UNWRAPPING
Address
Represents an address suitable for delivery.
| country_code 🔗 |
string
required
Refers to a ISO-3166 alpha 2 country code |
| region_code 🔗 |
string
Refers to an ISO-3166-2 subdivision code without country_code prefix, e.g., `DC` for Washington DC. Except for countries like México, Hong Kong, etc. Example region for Honk Kong - `Kowloon` |
| postal_code 🔗 |
string
Refers to a postal code or zipcode |
| city 🔗 |
string
Refers to a city, postal_town or locality |
| address_lines 🔗 |
string[]
List of strings, each a part of the address, e.g., street name, street number, building name, floor |
| coordinates 🔗 |
Geolocation of the given address |
Any
| @type 🔗 |
string
|
CompleteSessionResponse
Response message for completing a session.
Contact
Contact represents generic contact information.
| address 🔗 |
Address
required
The physical address of the contact |
| email 🔗 |
string
The email address of the contact |
| phone_number 🔗 |
The phone number of the contact, including region and optional extension |
ContactPhoneNumber
A phone number, including region and optional extension.
| country_code 🔗 |
string
required
The country code where the delivery will occur (ISO 3166-1 alpha-2) |
| number 🔗 |
string
required
The main phone number, formatted as per the region's conventions |
| extension 🔗 |
string
An optional phone number extension |
Coordinates
Represents a latitude/longitude pair. Unless specified otherwise, this must conform to the WGS84 standard. Values must be within normalized ranges.
| lat 🔗 |
number
required
The latitude in degrees. Must be within the range -90.0 to +90.0, inclusive |
| lng 🔗 |
number
required
The longitude in degrees. Must be within the range -180.0 to +180.0, inclusive |
Delivery
The delivery represents a single delivery of goods to a recipient. It includes information about the goods, the recipient details, the fulfillment methods and the delivery options.
| id 🔗 |
string
required
The unique identifier of a delivery |
| line_items 🔗 |
object[]
required
The goods that are to be delivered |
| fulfillments 🔗 |
object[]
required
The available fulfillments for the delivery. deprecated: use `delivery_nodes` instead |
| recipient_contact 🔗 |
Contact
required
The recipient's contact information |
| attributes 🔗 |
string[]
Used to control the behaviour of the filter/price rules. Equivalent of cart_attributes in the `Delivery Checkout` API |
| delivery_categories 🔗 |
object[]
The available delivery categories for this delivery |
| tos_id 🔗 |
string
ID of the TOS, only present for the session `complete` and `get` calls |
| external_id 🔗 |
string
ID assigned by the merchant to a specific delivery. Only present for the session `complete` and `get` calls. Used as external ID of the TOS |
| nodes 🔗 |
object[]
List of nodes that take part in the delivery |
DeliveryCategory
The DeliveryCategory represents a grouping of delivery options that share the same type and other characteristics.
| id 🔗 |
string
required
The unique identifier of a delivery category |
| external_id 🔗 |
string
The external identifier of a category, used for integration purposes |
| delivery_type 🔗 |
DeliveryCategoryDeliveryType
required
The delivery type associated with this category |
| display_name 🔗 |
string
required
A human-readable name of the category, which will be presented to the customer |
| sort_order 🔗 |
integer
required
Defines the order in which the category will be presented to the customer |
| options_source 🔗 |
DeliveryCategoryOptionsSource
required
The source of delivery options for this category |
| delivery_options 🔗 |
object[]
required
The delivery options available within this category |
| addons 🔗 |
object[]
Add-ons that are available for this category, e.g., gift wrapping, insurance |
| preselected 🔗 |
boolean
Indicates if this category should be preselected by default |
| chosen 🔗 |
boolean
Indicates if this category was chosen by the user |
| warehouse 🔗 |
Information about the warehouse that the category is assigned to |
DeliveryCategoryDeliveryType
DeliveryType defines the method or mode of delivery.
- DELIVERY_TYPE_UNSPECIFIED: Delivery type is unspecified or unknown.
- DELIVERY: Delivery to a customer's home or address.
- PICKUP: Delivery to a service point or locker.
- MAILBOX: Delivery to a customer's mailbox.
- INSTORE: Delivery to a merchant's store for in-store pickup.
Enum Values:
- DELIVERY_TYPE_UNSPECIFIED
- DELIVERY
- PICKUP
- MAILBOX
- INSTORE
DeliveryCategoryOptionsSource
OptionsSource specifies the origin of the delivery options.
- OPTIONS_SOURCE_UNSPECIFIED: Source of the options is unspecified.
- FALLBACK: Delivery options come from a fallback configuration.
- CARRIER: Delivery options are sourced directly from the carrier.
Enum Values:
- OPTIONS_SOURCE_UNSPECIFIED
- FALLBACK
- CARRIER
DeliveryCategoryWarehouse
Information about a warehouse. All this data is stored in the site configuration.
| id 🔗 |
string
required
Unique identifier of the warehouse |
| address 🔗 |
Address
required
The address of the warehouse |
| external_id 🔗 |
string
The external identifier of a warehouse, used for integration purposes |
DeliveryChoice
The DeliveryChoice represents what option is selected for the given delivery.
| delivery_id 🔗 |
string
required
The unique identifier of the delivery |
| option_id 🔗 |
string
required
The selected delivery option |
| addon_ids 🔗 |
string[]
The selected delivery addons, if applicable |
| external_id 🔗 |
string
ID assigned by the merchant to a specific delivery. Used as external ID of the TOS |
DeliveryNode
| handoff 🔗 |
When the node is ready for handoff |
| location 🔗 |
Where the node is physically located |
| roles 🔗 |
What roles the node can perform |
| tags 🔗 |
string[]
Additional metadata about the node. For cross-reference purposes |
DeliveryNodeHandoff
Constraints on the node's handoff.
DeliveryNodeRole
Set of available roles for the node.
- DESTINATION: TRANSIT = 3; RETURNS = 4;
Enum Values:
- ROLE_UNSPECIFIED
- ORIGIN
- DESTINATION
DeliveryOption
The DeliveryOption represents the details of a specific delivery option.
| id 🔗 |
string
required
The unique identifier of the delivery option |
| carrier 🔗 |
DeliveryOptionCarrier
required
Information about the carrier responsible for this delivery |
| pickup_location 🔗 |
The pickup location for this delivery option, if applicable |
| etd 🔗 |
ETD
required
The ETD for this option |
| preselected 🔗 |
boolean
Indicates if this delivery option should be preselected by default |
| chosen 🔗 |
boolean
Indicates if this delivery option was chosen by the customer |
| expire_time 🔗 |
string
The expiration timestamp in UTC of the delivery option |
| price 🔗 |
string
required
Price associated with the delivery option in minor currency units, e.g., cents |
DeliveryOptionCarrier
The Carrier contains details about the shipping carrier associated with this delivery option.
| name 🔗 |
string
required
The name of the carrier company, e.g., "DHL", "FedEx" |
| product_name 🔗 |
string
required
The product or service level name provided by the carrier, e.g., "Parcel", "Standard") |
| product_id 🔗 |
string
required
The product or service level identifier provided by the carrier, e.g., "dhl-par", "ups-std") |
| sort_order 🔗 |
integer
The original sort order assigned by the carrier |
| meta 🔗 |
hash
Carrier-specific metadata |
| external_id 🔗 |
string
required
Merchant-specific carrier product identifier |
DeliveryServiceCompleteSessionBody
Request message for completing a session.
| delivery_choices 🔗 |
object[]
List of choices for the given deliveries |
Distance
Generic distance
ETD
ETD stands for Estimated Time of Delivery.
| relative 🔗 |
Estimate expressed as a range of time units |
| absolute 🔗 |
Estimate expressed as a range of timestamps |
| custom 🔗 |
Estimate expressed as a custom text |
ETDAbsolute
Absolute represents an ETD as a single or pair of timestamps.
| earliest_time 🔗 |
string
The earliest possible delivery time. If unspecified, delivery is considered tp be immediate |
| latest_time 🔗 |
string
The latest possible delivery time. If unspecified, there is no guaranteed maximum time |
ETDCustom
Custom represents an ETD in a human-readable text format.
| text 🔗 |
string
required
Description in a text form, e.g., "Before Christmas", "Same day if ordered before 2PM" |
ETDRelative
Relative represents an ETD as a range of time units.
| unit 🔗 |
ETDTimeUnit
required
The unit of time used by the ETD range |
| earliest 🔗 |
integer
The minimum number of time units. If unspecified, there is no lower bound |
| latest 🔗 |
integer
Maximum number of time units. If unspecified, there is no upper bound |
ETDTimeUnit
TimeUnit specifies the unit of time measurement for ETD.
- TIME_UNIT_UNSPECIFIED: Default value. This value is unused.
- TIME_UNIT_MINUTE: Minutes
- TIME_UNIT_HOUR: Hours
- TIME_UNIT_DAY: Calendar days
- TIME_UNIT_BUSINESS_DAY: Business days (excluding weekends and holidays)
- TIME_UNIT_WEEK: Calendar weeks
- TIME_UNIT_MONTH: Calendar months
Enum Values:
- TIME_UNIT_UNSPECIFIED
- TIME_UNIT_MINUTE
- TIME_UNIT_HOUR
- TIME_UNIT_DAY
- TIME_UNIT_BUSINESS_DAY
- TIME_UNIT_WEEK
- TIME_UNIT_MONTH
Fulfillment
A Fulfillment details when a delivery can be fulfilled.
| readiness 🔗 |
FulfillmentReadiness
required
The time window when the goods will be ready for shipment |
FulfillmentReadiness
Readiness specifies a time range when the goods will be ready for shipment.
| earliest_time 🔗 |
string
required
The earliest timestamp when the goods will be ready for shipment |
| latest_time 🔗 |
string
The latest timestamp when the goods will be ready for shipment. If not specified, the goods will be ready indefinitely after start_time |
LineItem
Represents a single item.
| sku 🔗 |
string
required
The unique item identifier of the item |
| title 🔗 |
string
required
The item name or title, which is suitable for presentation to the customer |
| quantity 🔗 |
integer
required
Total quantity of the item |
| weight 🔗 |
integer
Weight of a single item in grams, must be greater than 0 |
| dimensions 🔗 |
Dimensions of the item |
| discount 🔗 |
string
Non-negative discount applied to the item, or items. Unit is cents |
| price 🔗 |
string
Non-negative price of a single item after applying discounts. Unit is cents |
| image_uri 🔗 |
string
URI of the product image, e.g., thumbnail |
| attributes 🔗 |
string[]
Used to control the behaviour of the filter/price rules. Equivalent of cart_items_attributes in the `Delivery Checkout` API |
LineItemDimensions
Represents the dimensions of the item.
| height 🔗 |
integer
required
Height of the item in millimeters, must be greater than 0 |
| length 🔗 |
integer
required
Length of the item in millimeters, must be greater than 0 |
| width 🔗 |
integer
required
Width of the item in millimeters, must be greater than 0 |
PickupLocation
The PickupLocation represents a physical location from which a delivery can be retrieved.
| id 🔗 |
string
required
Internal location identifier, used within the system |
| external_id 🔗 |
string
required
External identifier provided by the merchant or carrier |
| location_type 🔗 |
The type of the pickup location, e.g., LOCKER, STORE |
| title 🔗 |
string
required
The title of the location displayed to the customer |
| visiting_contact 🔗 |
Contact information when visiting the location for retrieving a package |
| delivery_contact 🔗 |
Contact information for delivery to the pickup location |
| operational_hours 🔗 |
Operational hours of the pickup location. If none are provided, the location is available at all times |
| sections 🔗 |
object[]
Additional informational sections about the pickup location |
| distances 🔗 |
The distances to the pickup location, e.g., walking or driving |
PickupLocationDistances
Distances define the walking and driving distances to the pickup location.
| walking 🔗 |
The walking distance to the pickup location |
| driving 🔗 |
The driving distance to the pickup location |
PickupLocationLocationType
LocationType defines the type of the pickup location.
- LOCATION_TYPE_UNSPECIFIED: Unspecified type.
- LOCKER: A locker pickup location.
- STORE: A store pickup location.
- POSTOFFICE: A post office pickup location.
- MANNED: A manned pickup location, e.g., staffed desk.
Enum Values:
- LOCATION_TYPE_UNSPECIFIED
- LOCKER
- STORE
- POSTOFFICE
- MANNED
PickupLocationOperationalHours
OperationalHours define when the pickup location is operating.
| monday 🔗 |
string[]
Opening hours for Monday |
| tuesday 🔗 |
string[]
Opening hours for Tuesday |
| wednesday 🔗 |
string[]
Opening hours for Wednesday |
| thursday 🔗 |
string[]
Opening hours for Thursday |
| friday 🔗 |
string[]
Opening hours for Friday |
| saturday 🔗 |
string[]
Opening hours for Saturday |
| sunday 🔗 |
string[]
Opening hours for Sunday |
| free_text 🔗 |
string[]
Free-text operational hours for fallback |
PickupLocationSection
Section provides extra information about the pickup location.
| title 🔗 |
string
required
The title of the section displayed to the customer |
| columns 🔗 |
object[]
required
The columns of items in the section |
ReturnsPromise
ReturnPromise contains promise for returns and exchanges for a user and a cart.
| id 🔗 |
string
Unique identifier for the return promise |
| currency_code 🔗 |
string
Currency code for the return promise, e.g., "USD", "EUR" |
| returns_enabled 🔗 |
boolean
true if returns are enabled, false if not, check return_cost for the cost for returns |
| return_cost 🔗 |
string
Non-negative cost of returning the item, or items. Unit is cents |
| exchanges_enabled 🔗 |
boolean
true if exchanges are enabled, false if not, check exchange_cost for the cost for exchanges |
| exchange_cost 🔗 |
string
|
| return_time_days 🔗 |
integer
Time in days to return or exchange the item |
| return_policy_text 🔗 |
string
Return Policy text suitable for presentation to the customer |
| return_policy_url 🔗 |
string
Return Policy URL, which is suitable for presentation to the customer |
| is_unavailable 🔗 |
boolean
is_unavailable is a flag that indicates if the return promise is missing due to api failures or other issues. In that case consider displaying "Return details unavailable" message to end user |
SectionColumn
Column contains a list of items displayed in a single section column.
| items 🔗 |
object[]
required
The items within the column |
SectionItem
Item represents a single piece of information in a section.
| icon_uri 🔗 |
string
The URI for the item's icon |
| text 🔗 |
string
The text description of the item |
| link_uri 🔗 |
string
The URI for a link associated with the item |
Session
A Session is the primary resource for handling the delivery options and the customer lifecycle.
| name 🔗 |
string
The resource name of the session. Format: sessions/{session_id} |
| state 🔗 |
The state of the session |
| purchase 🔗 |
SessionPurchase
required
The purchase for the given session |
| deliveries 🔗 |
object[]
required
The deliveries included in this session |
| create_time 🔗 |
string
The timestamp when the session was created |
| update_time 🔗 |
string
The timestamp when the session was last updated |
| etag 🔗 |
string
The current etag of the session. If an etag is provided and does not match the current etag of the session, updates and completion will be blocked and an ABORTED error will be returned |
| returns_promise 🔗 |
The returns promise for the session generated by Ingrid Returns product |
SessionPurchase
Purchase describes purchase experience. Q(grigagod): shoud we stick to a main cart concept?.
| country_code 🔗 |
string
required
The country code where the delivery will occur (ISO 3166-1 alpha-2) |
| currency_code 🔗 |
string
required
The currency code for the transaction (ISO 4217) |
| total_discount 🔗 |
string
The total discount applied to the purchase (non-negative, in cents) |
| total_value 🔗 |
string
The total value of the purchase after discounts are applied (non-negative, in cents) |
| vouchers 🔗 |
string[]
List of vouchers |
| locales 🔗 |
string[]
Locales list defined as lc-CC compliant with ISO 3166-1, in order of preference(first supported one will be chosen) |
SessionState
State defines the current state of the session.
- STATE_UNSPECIFIED: Default value. This value is unused.
- ACTIVE: Session is active and can be modified.
- COMPLETED: Session is completed and can not be modified.
Enum Values:
- STATE_UNSPECIFIED
- ACTIVE
- COMPLETED