{ "consumes": [ "application/json" ], "produces": [ "application/json" ], "schemes": [ "https" ], "swagger": "2.0", "info": { "description": "API for managing delivery sessions, retrieving delivery options, and completing checkout.", "title": "Delivery API", "version": "v1" }, "basePath": "/delivery/v1", "paths": { "/sessions": { "post": { "security": [ { "Bearer": [] } ], "summary": "Creates a new session.", "operationId": "DeliveryService_CreateSession", "parameters": [ { "description": "The session to create.", "name": "session", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Session" } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Session" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Error" } } } } }, "/sessions:lookup": { "get": { "security": [ { "Bearer": [] } ], "summary": "Looks up a session by one of its deliveries' TOS IDs (the persistent\nidentifier returned on session completion). Returns the full session,\nincluding all deliveries, identical to the GetSession payload.", "operationId": "DeliveryService_LookupSession", "parameters": [ { "type": "string", "description": "The TOS ID of one of the session's deliveries.", "name": "tos_id", "in": "query", "required": true } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Session" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Error" } } } } }, "/{name}": { "get": { "security": [ { "Bearer": [] } ], "summary": "Gets a session by resource name.", "operationId": "DeliveryService_GetSession", "parameters": [ { "pattern": "sessions/[^/]+", "type": "string", "description": "The resource name of the shipping session to retrieve.\nFormat: sessions/{session_id}", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Session" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Error" } } } } }, "/{name}:complete": { "post": { "security": [ { "Bearer": [] } ], "summary": "Completes a session and saves the user choices.", "operationId": "DeliveryService_CompleteSession", "parameters": [ { "pattern": "sessions/[^/]+", "type": "string", "description": "The resource name of the shipping session to complete.\nFormat: sessions/{session_id}", "name": "name", "in": "path", "required": true }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/DeliveryServiceCompleteSessionBody" } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/CompleteSessionResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Error" } } } } }, "/{name}:convert": { "post": { "security": [ { "Bearer": [] } ], "summary": "Converts session to the given format.\nUnderlying session resource stays unchanged.", "operationId": "DeliveryService_ConvertSession", "parameters": [ { "pattern": "sessions/[^/]+", "type": "string", "description": "The resource name of the shipping session to retrieve.\nFormat: sessions/{session_id}", "name": "name", "in": "path", "required": true }, { "enum": [ "FORMAT_UNSPECIFIED", "AGENTIC_CHECKOUT" ], "type": "string", "default": "FORMAT_UNSPECIFIED", "description": "Target format.", "name": "format", "in": "query", "required": true } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/ConvertSessionResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Error" } } } } }, "/{session.name}": { "patch": { "security": [ { "Bearer": [] } ], "summary": "Updates a session.", "operationId": "DeliveryService_UpdateSession", "parameters": [ { "pattern": "sessions/[^/]+", "type": "string", "description": "The resource name of the session. Format: sessions/{session_id}", "name": "session.name", "in": "path", "required": true }, { "description": "The session to update.", "name": "session", "in": "body", "required": true, "schema": { "type": "object", "title": "The session to update.", "required": [ "purchase", "deliveries" ], "properties": { "create_time": { "description": "The timestamp when the session was created.", "type": "string", "format": "date-time", "readOnly": true }, "deliveries": { "description": "The deliveries included in this session.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/Delivery" } }, "etag": { "description": "The current etag of the session.\nIf an etag is provided and does not match the current etag of the session,\nupdates and completion will be blocked and an ABORTED error will be returned.", "type": "string" }, "purchase": { "description": "The purchase for the given session.", "$ref": "#/definitions/SessionPurchase" }, "returns_promise": { "description": "The returns promise for the session generated by Ingrid Returns product.", "$ref": "#/definitions/ReturnsPromise", "readOnly": true }, "state": { "description": "The state of the session.", "$ref": "#/definitions/SessionState", "readOnly": true }, "update_time": { "description": "The timestamp when the session was last updated.", "type": "string", "format": "date-time", "readOnly": true } } } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Session" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Error" } } } } } }, "definitions": { "Addon": { "description": "An Addon represents an additional service or feature offered with a delivery.", "type": "object", "required": [ "display_name" ], "properties": { "addon_type": { "description": "The type of the addon.", "$ref": "#/definitions/AddonAddonType", "readOnly": true }, "chosen": { "description": "Indicates if this addon was chosen.", "type": "boolean" }, "description": { "description": "The display-friendly description of the addon.\nDisplay name and description are localized, if translations are provided.", "type": "string", "readOnly": true }, "display_name": { "description": "The display-friendly name of the addon, e.g., \"Gift Wrapping\", \"Leave at Door\".\nDisplay name and description are localized, if translations are provided.", "type": "string" }, "external_id": { "description": "The external identifier of an addon, used for integration purposes.", "type": "string", "readOnly": true }, "id": { "description": "Unique addon identifier.", "type": "string", "readOnly": true }, "preselected": { "description": "Indicates if this addon should be preselected by default.", "type": "boolean" }, "price": { "description": "The price of the addon in minor currency units, e.g., cents.", "type": "string", "format": "int64", "readOnly": true } } }, "AddonAddonType": { "description": "AddonType defines the specific type of addon offered.\n\n - ADDON_TYPE_UNSPECIFIED: Addon type is unspecified or unknown.\n - CUSTOM: A custom addon specified by the carrier or merchant.\n - CARRY_IN: An addon for carrying the delivery item into the recipient's premises.\n - LEAVE_AT_DOOR: An addon for leaving the item at the door without requiring a signature.\n - UNWRAPPING: An addon for unwrapping the delivered item.", "type": "string", "default": "ADDON_TYPE_UNSPECIFIED", "enum": [ "ADDON_TYPE_UNSPECIFIED", "CUSTOM", "CARRY_IN", "LEAVE_AT_DOOR", "UNWRAPPING" ] }, "Address": { "description": "Represents an address suitable for delivery.", "type": "object", "required": [ "country_code" ], "properties": { "address_lines": { "description": "List of strings, each a part of the address, e.g., street name, street number, building name, floor.", "type": "array", "items": { "type": "string" } }, "city": { "description": "Refers to a city, postal_town or locality.", "type": "string" }, "coordinates": { "description": "Geolocation of the given address.", "$ref": "#/definitions/Coordinates" }, "country_code": { "description": "\nRefers to a ISO-3166 alpha 2 country code.", "type": "string" }, "postal_code": { "description": "Refers to a postal code or zipcode.", "type": "string" }, "region_code": { "description": "Refers to a first-level administrative subdivision code (ISO-3166-2) without the country_code prefix.\nExample: region for Washington, D.C. = `DC` (from `US-DC`).\nException: for some countries (e.g. Mexico, Hong Kong) the subdivision name is used instead.\nExample: region for Hong Kong = `Kowloon`.", "type": "string" } } }, "AgenticCheckoutSession": { "description": "Represents a session in agentic checkout format.", "type": "object", "properties": { "deliveries": { "description": "The deliveries included in this session.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/AgenticCheckoutSessionDelivery" }, "readOnly": true }, "name": { "type": "string", "title": "The resource name of the session. Format: sessions/{session_id}" } } }, "AgenticCheckoutSessionAddress": { "description": "Represents an address in the agentic checkout format.", "type": "object", "properties": { "city": { "description": "City or locality.", "type": "string" }, "country": { "description": "Country code (ISO 3166-1 alpha-2).", "type": "string" }, "line_one": { "description": "Primary address line, e.g., street name and number.", "type": "string" }, "line_two": { "description": "Secondary address line, e.g., apartment or suite number.", "type": "string" }, "name": { "description": "Full name associated with the address.", "type": "string" }, "postal_code": { "description": "Postal code or ZIP code.", "type": "string" }, "state": { "description": "State or region.", "type": "string" } } }, "AgenticCheckoutSessionDelivery": { "type": "object", "properties": { "fulfillment_address": { "description": "The address for fulfillment.", "$ref": "#/definitions/AgenticCheckoutSessionAddress" }, "fulfillment_option_id": { "description": "The ID of the selected fulfillment option.", "type": "string" }, "fulfillment_options": { "description": "Available fulfillment options.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/AgenticCheckoutSessionFulfillmentOption" } }, "id": { "description": "The unique identifier of a delivery.", "type": "string" } } }, "AgenticCheckoutSessionFulfillmentOption": { "description": "Represents a fulfillment option in the agentic checkout format.", "type": "object", "properties": { "carrier": { "description": "Name of the carrier providing this option.", "type": "string" }, "earliest_delivery_time": { "description": "The earliest possible delivery time.", "type": "string", "format": "date-time" }, "id": { "description": "Unique identifier of the fulfillment option.", "type": "string" }, "latest_delivery_time": { "description": "The latest possible delivery time.", "type": "string", "format": "date-time" }, "subtitle": { "description": "Additional display text, e.g., estimated delivery time.", "type": "string" }, "subtotal": { "description": "Subtotal price in minor currency units, e.g., cents.", "type": "string", "format": "int64" }, "tax": { "description": "Tax amount in minor currency units, e.g., cents.", "type": "string", "format": "int64" }, "title": { "description": "Display title of the fulfillment option.", "type": "string" }, "total": { "description": "Total price in minor currency units, e.g., cents.", "type": "string", "format": "int64" }, "type": { "description": "Fulfillment type. Value: \"shipping\".", "type": "string" } } }, "CarrierAttributes": { "description": "Additional attributes required by a carrier product or integration.", "type": "object", "properties": { "customer_reference": { "description": "When set, describes a customer reference identifier that is contextually meaningful\nfor the carrier.", "type": "string" } } }, "CompleteSessionResponse": { "description": "Response message for completing a session.", "type": "object", "required": [ "session" ], "properties": { "session": { "description": "The completed session.", "$ref": "#/definitions/Session" } } }, "Contact": { "description": "Contact represents generic contact information.", "type": "object", "required": [ "address" ], "properties": { "address": { "description": "The physical address of the contact.", "$ref": "#/definitions/Address" }, "company_name": { "description": "The company name of the recipient.", "type": "string" }, "email": { "description": "The email address of the contact.", "type": "string" }, "family_name": { "description": "The family name of the recipient.\nUses AIP-148 terminology; prefer family_name over last_name as the family name\nis not placed last in many cultures.", "type": "string" }, "given_name": { "description": "The given name of the recipient.\nUses AIP-148 terminology; prefer given_name over first_name as the given name\nis not placed first in many cultures.\nIf the integrator cannot differentiate between given and family name,\nthe entire name may be supplied in this field.", "type": "string" }, "phone_number": { "description": "The phone number of the contact, including region and optional extension.", "$ref": "#/definitions/ContactPhoneNumber" } } }, "ContactPhoneNumber": { "description": "A phone number, including region and optional extension.", "type": "object", "required": [ "country_code", "number" ], "properties": { "country_code": { "description": "\nThe country code where the delivery will occur (ISO 3166-1 alpha-2).", "type": "string" }, "extension": { "description": "An optional phone number extension.", "type": "string" }, "number": { "description": "The main phone number, formatted as per the region's conventions.", "type": "string" } } }, "ConvertSessionResponse": { "description": "Response message for converted session.", "type": "object", "properties": { "agentic_checkout": { "description": "The session in agentic checkout format.", "$ref": "#/definitions/AgenticCheckoutSession" }, "ingrid": { "description": "The session in Ingrid's native format.", "$ref": "#/definitions/Session" } } }, "Coordinates": { "description": "Represents a latitude/longitude pair.\nUnless specified otherwise, this must conform to the WGS84 standard.\nValues must be within normalized ranges.", "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "description": "The latitude in degrees. Must be within the range -90.0 to +90.0, inclusive.", "type": "number", "format": "double" }, "lng": { "description": "The longitude in degrees. Must be within the range -180.0 to +180.0, inclusive.", "type": "number", "format": "double" } } }, "Delivery": { "description": "The delivery represents a single delivery of goods to a recipient.\nIt includes information about the goods, the recipient details, the fulfillment methods and the delivery options.", "type": "object", "required": [ "id", "line_items", "fulfillments", "recipient_contact" ], "properties": { "attributes": { "description": "Used to control the behaviour of the filter/price rules.\nEquivalent of cart_attributes in the `Delivery Checkout` API.", "type": "array", "items": { "type": "string" } }, "delivery_categories": { "description": "The available delivery categories for this delivery.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/DeliveryCategory" }, "readOnly": true }, "external_id": { "description": "ID assigned by the merchant to a specific delivery.\nOnly present for the session `complete` and `get` calls.\nUsed as external ID of the TOS.", "type": "string", "readOnly": true }, "fulfillments": { "description": "The available fulfillments for the delivery.\nIn the future this will be deprecated in favour of `nodes`.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/Fulfillment" } }, "id": { "description": "The unique identifier of a delivery.", "type": "string" }, "line_items": { "description": "The goods that are to be delivered.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/LineItem" } }, "nodes": { "description": "List of nodes that take part in the delivery.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/DeliveryNode" } }, "recipient_contact": { "description": "The recipient's contact information.", "$ref": "#/definitions/Contact" }, "tos_id": { "description": "ID of the TOS, only present for the session `complete` and `get` calls.", "type": "string", "readOnly": true } } }, "DeliveryCategory": { "description": "The DeliveryCategory represents a grouping of delivery options that share the same type and other characteristics.", "type": "object", "required": [ "id", "delivery_type", "display_name", "options_source", "delivery_options" ], "properties": { "addons": { "description": "Add-ons that are available for this category, e.g., gift wrapping, insurance.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/Addon" } }, "chosen": { "description": "Indicates if this category was chosen by the user.", "type": "boolean" }, "custom_info_text": { "description": "Additional information that can be displayed with the category.\nThe presence of this field depends on the locale.", "type": "string", "readOnly": true }, "custom_text": { "description": "Additional text that can be displayed with the category.\nThe presence of this field depends on the locale.", "type": "string", "readOnly": true }, "delivery_options": { "description": "The delivery options available within this category.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/DeliveryOption" } }, "delivery_type": { "description": "The delivery type associated with this category.", "$ref": "#/definitions/DeliveryCategoryDeliveryType" }, "display_name": { "description": "A human-readable name of the category, which will be presented to the customer.", "type": "string" }, "external_id": { "description": "The external identifier of a category, used for integration purposes.", "type": "string" }, "id": { "description": "The unique identifier of a delivery category.", "type": "string" }, "labels": { "description": "Information about active labels associated with the delivery category.\nLabels name and description are localized, if translations are provided.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/DeliveryCategoryLabel" }, "readOnly": true }, "options_source": { "description": "The source of delivery options for this category.", "$ref": "#/definitions/DeliveryCategoryOptionsSource" }, "preselected": { "description": "Indicates if this category should be preselected by default.", "type": "boolean" }, "price_levels": { "type": "object", "title": "Map of category's carrier product IDs to price levels", "additionalProperties": { "$ref": "#/definitions/DeliveryCategoryPriceLevels" }, "readOnly": true }, "sort_order": { "description": "Defines the order in which the category will be presented to the customer.", "type": "integer", "format": "int32" }, "tags": { "description": "Tags associated with the delivery category, used for cross-reference purposes.", "type": "array", "items": { "type": "string" }, "readOnly": true }, "warehouse": { "description": "Information about the warehouse that the category is assigned to.\nDeprecated: use delivery_options.*.origin instead.", "$ref": "#/definitions/DeliveryCategoryWarehouse", "readOnly": true } } }, "DeliveryCategoryDeliveryType": { "description": "DeliveryType defines the method or mode of delivery.\n\n - DELIVERY_TYPE_UNSPECIFIED: Delivery type is unspecified or unknown.\n - DELIVERY: Delivery to a customer's home or address.\n - PICKUP: Delivery to a service point or locker.\n - MAILBOX: Delivery to a customer's mailbox.\n - INSTORE: Delivery to a merchant's store for in-store pickup.", "type": "string", "default": "DELIVERY_TYPE_UNSPECIFIED", "enum": [ "DELIVERY_TYPE_UNSPECIFIED", "DELIVERY", "PICKUP", "MAILBOX", "INSTORE" ] }, "DeliveryCategoryLabel": { "description": "Labels provide additional, customer-facing information for the delivery category.", "type": "object", "properties": { "color": { "description": "Color code for the label, e.g., hex value.", "type": "string" }, "dark_mode_color": { "description": "Color code for the label in dark mode, e.g., hex value.", "type": "string" }, "description": { "description": "Description of the label displayed to the customer.", "type": "string" }, "icon": { "description": "URI or identifier for the label icon.", "type": "string" }, "id": { "description": "Unique identifier of the label.", "type": "string" }, "name": { "description": "Display name of the label.", "type": "string" }, "type": { "description": "The type of the label.", "$ref": "#/definitions/LabelLabelType" } } }, "DeliveryCategoryOptionsSource": { "description": "OptionsSource specifies the origin of the delivery options.\n\n - OPTIONS_SOURCE_UNSPECIFIED: Source of the options is unspecified.\n - FALLBACK: Delivery options come from a fallback configuration.\n - CARRIER: Delivery options are sourced directly from the carrier.", "type": "string", "default": "OPTIONS_SOURCE_UNSPECIFIED", "enum": [ "OPTIONS_SOURCE_UNSPECIFIED", "FALLBACK", "CARRIER" ] }, "DeliveryCategoryPriceLevels": { "type": "object", "properties": { "price_levels": { "description": "Available price levels for the carrier product.\nOnly the base price and prices with the `total_value` price rule are included.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/PriceLevelsPriceLevel" } } } }, "DeliveryCategoryWarehouse": { "description": "Information about a warehouse.\nAll this data is stored in the site configuration.", "type": "object", "required": [ "id", "address" ], "properties": { "address": { "description": "The address of the warehouse.", "$ref": "#/definitions/Address" }, "external_id": { "description": "The external identifier of a warehouse, used for integration purposes.", "type": "string" }, "id": { "description": "Unique identifier of the warehouse.", "type": "string" } } }, "DeliveryChoice": { "description": "The DeliveryChoice represents what option is selected for the given delivery.", "type": "object", "required": [ "delivery_id", "option_id" ], "properties": { "addon_ids": { "description": "The selected delivery addons, if applicable.", "type": "array", "items": { "type": "string" } }, "carrier_attributes": { "title": "When set, includes additional information/metadata for the selected carrier", "$ref": "#/definitions/CarrierAttributes" }, "delivery_id": { "description": "The unique identifier of the delivery.", "type": "string" }, "external_id": { "description": "ID assigned by the merchant to a specific delivery.\nUsed as external ID of the TOS.", "type": "string" }, "option_id": { "description": "The selected delivery option.", "type": "string" } } }, "DeliveryNode": { "type": "object", "required": [ "location", "roles" ], "properties": { "handoff": { "description": "When the node is ready for handoff.", "$ref": "#/definitions/DeliveryNodeHandoff" }, "location": { "description": "Where the node is physically located.", "$ref": "#/definitions/DeliveryNodeLocation" }, "roles": { "description": "What roles the node can perform.", "type": "array", "items": { "$ref": "#/definitions/DeliveryNodeRole" } }, "tags": { "description": "Additional metadata about the node.\nFor cross-reference purposes.", "type": "array", "items": { "type": "string" } } } }, "DeliveryNodeHandoff": { "description": "Constraints on the node's handoff.", "type": "object", "properties": { "earliest_time": { "description": "The earliest time the node can hand off the delivery.", "type": "string", "format": "date-time" }, "latest_time": { "description": "The latest time the node can hand off the delivery.", "type": "string", "format": "date-time" } } }, "DeliveryNodeLocation": { "description": "Where the node is physically located.", "type": "object", "properties": { "by_ref": { "$ref": "#/definitions/LocationByRef" }, "by_value": { "$ref": "#/definitions/LocationByValue" } } }, "DeliveryNodeRole": { "description": "Set of available roles for the node.\n\n - ROLE_UNSPECIFIED: Role is unspecified.\n - ORIGIN: The node is the origin of the delivery.\n - DESTINATION: The node is the destination of the delivery.", "type": "string", "default": "ROLE_UNSPECIFIED", "enum": [ "ROLE_UNSPECIFIED", "ORIGIN", "DESTINATION" ] }, "DeliveryOption": { "description": "The DeliveryOption represents the details of a specific delivery option.", "type": "object", "required": [ "id", "carrier", "etd", "price", "origin" ], "properties": { "carrier": { "description": "Information about the carrier responsible for this delivery.", "$ref": "#/definitions/DeliveryOptionCarrier" }, "chosen": { "description": "Indicates if this delivery option was chosen by the customer.", "type": "boolean" }, "etd": { "description": "The ETD for this option.", "$ref": "#/definitions/ETD" }, "expire_time": { "description": "The expiration timestamp in UTC of the delivery option.", "type": "string", "format": "date-time" }, "id": { "description": "The unique identifier of the delivery option.", "type": "string" }, "origin": { "description": "Where delivery originates from.", "$ref": "#/definitions/DeliveryOptionOrigin" }, "pickup_location": { "description": "The pickup location for this delivery option, if applicable.", "$ref": "#/definitions/PickupLocation" }, "preselected": { "description": "Indicates if this delivery option should be preselected by default.", "type": "boolean" }, "price": { "description": "Price associated with the delivery option in minor currency units, e.g., cents.", "type": "string", "format": "int64" } } }, "DeliveryOptionCarrier": { "description": "The Carrier contains details about the shipping carrier associated with this delivery option.", "type": "object", "required": [ "name", "product_name", "product_id", "external_id" ], "properties": { "external_id": { "description": "Merchant-specific carrier product identifier.", "type": "string" }, "meta": { "description": "Carrier-specific metadata.", "type": "object", "additionalProperties": { "type": "string" } }, "name": { "description": "The name of the carrier company, e.g., \"DHL\", \"FedEx\".", "type": "string" }, "product_id": { "description": "The product or service level identifier provided by the carrier, e.g., \"dhl-par\", \"ups-std\".", "type": "string" }, "product_name": { "description": "The product or service level name provided by the carrier, e.g., \"Parcel\", \"Standard\".", "type": "string" }, "sort_order": { "description": "The original sort order assigned by the carrier.", "type": "integer", "format": "int32" } } }, "DeliveryOptionOrigin": { "description": "Where delivery originates from.", "type": "object", "required": [ "id", "address" ], "properties": { "address": { "description": "The address of the origin.", "$ref": "#/definitions/Address" }, "external_id": { "description": "External identifier of the origin, used for integration purposes.", "type": "string" }, "id": { "description": "Unique identifier of the origin.", "type": "string" } } }, "DeliveryServiceCompleteSessionBody": { "description": "Request message for completing a session.", "type": "object", "properties": { "delivery_choices": { "description": "List of choices for the given deliveries.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/DeliveryChoice" } } } }, "Distance": { "description": "Represents a distance measurement with both spatial distance and estimated travel time.", "type": "object", "properties": { "meters": { "description": "Approximate distance in meters.", "type": "string", "format": "int64", "readOnly": true }, "minutes": { "description": "Approximate duration in minutes.", "type": "string", "format": "int64", "readOnly": true } } }, "ETD": { "description": "ETD stands for Estimated Time of Delivery.", "type": "object", "properties": { "absolute": { "description": "Estimate expressed as a range of timestamps.", "$ref": "#/definitions/ETDAbsolute" }, "custom": { "title": "Estimate expressed as a custom text", "$ref": "#/definitions/ETDCustom" }, "relative": { "description": "Estimate expressed as a range of time units.", "$ref": "#/definitions/ETDRelative" } } }, "ETDAbsolute": { "description": "Absolute represents an ETD as a single or pair of timestamps.", "type": "object", "properties": { "earliest_time": { "description": "The earliest possible delivery time. If unspecified, delivery is considered to be immediate.", "type": "string", "format": "date-time" }, "latest_time": { "description": "The latest possible delivery time. If unspecified, there is no guaranteed maximum time.", "type": "string", "format": "date-time" } } }, "ETDCustom": { "description": "Custom represents an ETD in a human-readable text format.", "type": "object", "required": [ "text" ], "properties": { "text": { "description": "Description in a text form, e.g., \"Before Christmas\", \"Same day if ordered before 2PM\".", "type": "string" } } }, "ETDRelative": { "description": "Relative represents an ETD as a range of time units.", "type": "object", "required": [ "unit" ], "properties": { "earliest": { "description": "The minimum number of time units. If unspecified, there is no lower bound.\nValue of zero means delivery within the same time unit period (e.g., same day if unit is DAY).", "type": "integer", "format": "int32" }, "latest": { "description": "Maximum number of time units. If unspecified, there is no upper bound.\nValue of zero means delivery within the same time unit period (e.g., same day if unit is DAY).", "type": "integer", "format": "int32" }, "unit": { "description": "The unit of time used by the ETD range.", "$ref": "#/definitions/ETDTimeUnit" } } }, "ETDTimeUnit": { "description": "TimeUnit specifies the unit of time measurement for ETD.\n\n - TIME_UNIT_UNSPECIFIED: Default value. This value is unused.\n - TIME_UNIT_MINUTE: Minutes\n - TIME_UNIT_HOUR: Hours\n - TIME_UNIT_DAY: Calendar days\n - TIME_UNIT_BUSINESS_DAY: Business days (excluding weekends and holidays)\n - TIME_UNIT_WEEK: Calendar weeks\n - TIME_UNIT_MONTH: Calendar months", "type": "string", "default": "TIME_UNIT_UNSPECIFIED", "enum": [ "TIME_UNIT_UNSPECIFIED", "TIME_UNIT_MINUTE", "TIME_UNIT_HOUR", "TIME_UNIT_DAY", "TIME_UNIT_BUSINESS_DAY", "TIME_UNIT_WEEK", "TIME_UNIT_MONTH" ] }, "Fulfillment": { "description": "A Fulfillment details when a delivery can be fulfilled.", "type": "object", "required": [ "readiness" ], "properties": { "category_tags": { "description": "List of category tags, to which the `Readiness` applies.\nIf empty, the `Readiness` applies to all categories.", "type": "array", "items": { "type": "string" } }, "readiness": { "description": "The time window when the goods will be ready for shipment.", "$ref": "#/definitions/FulfillmentReadiness" } } }, "FulfillmentReadiness": { "description": "Readiness specifies a time range when the goods will be ready for shipment.", "type": "object", "required": [ "earliest_time" ], "properties": { "earliest_time": { "description": "The earliest timestamp when the goods will be ready for shipment.", "type": "string", "format": "date-time" }, "latest_time": { "description": "The latest timestamp when the goods will be ready for shipment.\nIf not specified, the goods will be ready indefinitely after start_time.", "type": "string", "format": "date-time" } } }, "LabelLabelType": { "description": "LabelType defines the type of label.\n\n - LABEL_TYPE_UNKNOWN: Label type is unknown.\n - LABEL_TYPE_SUSTAINABILITY: A sustainability-related label.\n - LABEL_TYPE_PRIORITY: A priority delivery label.\n - LABEL_TYPE_CUSTOM: A custom label defined by the merchant.\n - LABEL_TYPE_SWAN: A Nordic Swan eco-label.", "type": "string", "default": "LABEL_TYPE_UNKNOWN", "enum": [ "LABEL_TYPE_UNKNOWN", "LABEL_TYPE_SUSTAINABILITY", "LABEL_TYPE_PRIORITY", "LABEL_TYPE_CUSTOM", "LABEL_TYPE_SWAN" ] }, "LineItem": { "description": "Represents a single item.", "type": "object", "required": [ "sku", "title", "quantity" ], "properties": { "attributes": { "description": "Used to control the behaviour of the filter/price rules.\nEquivalent of cart_items_attributes in the `Delivery Checkout` API.", "type": "array", "items": { "type": "string" } }, "dimensions": { "description": "Dimensions of the item.", "$ref": "#/definitions/LineItemDimensions" }, "discount": { "description": "Non-negative discount applied to the item, or items. Unit is cents.", "type": "string", "format": "int64" }, "image_uri": { "description": "URI of the product image, e.g., thumbnail.", "type": "string" }, "price": { "description": "Non-negative price of a single item after applying discounts. Unit is cents.", "type": "string", "format": "int64" }, "quantity": { "description": "Total quantity of the item.", "type": "integer", "format": "int32" }, "sku": { "description": "The unique item identifier of the item.", "type": "string" }, "title": { "description": "The item name or title, which is suitable for presentation to the customer.", "type": "string" }, "weight": { "description": "Weight of a single item in grams, must be greater than 0.", "type": "integer", "format": "int32" } } }, "LineItemDimensions": { "description": "Represents the dimensions of the item.", "type": "object", "required": [ "height", "length", "width" ], "properties": { "height": { "description": "Height of the item in millimeters, must be greater than 0.", "type": "integer", "format": "int32" }, "length": { "description": "Length of the item in millimeters, must be greater than 0.", "type": "integer", "format": "int32" }, "width": { "description": "Width of the item in millimeters, must be greater than 0.", "type": "integer", "format": "int32" } } }, "LocationByRef": { "description": "To reference an existing location.", "type": "object", "required": [ "external_id" ], "properties": { "external_id": { "description": "External identifier provided by the merchant or carrier.", "type": "string" } } }, "LocationByValue": { "description": "To provide full information about the location.", "type": "object", "required": [ "external_id", "delivery_contact" ], "properties": { "delivery_contact": { "description": "Contact information for delivery purposes.", "$ref": "#/definitions/Contact" }, "display_name": { "description": "Location name that is displayed to the customer.", "type": "string" }, "external_id": { "description": "External identifier provided by the merchant or carrier.", "type": "string" }, "visiting_contact": { "description": "Contact information for visiting purposes.\nWhen missing delivery_contact is used.", "$ref": "#/definitions/Contact" } } }, "PickupLocation": { "description": "The PickupLocation represents a physical location from which a delivery can be retrieved.", "type": "object", "required": [ "id", "external_id", "title" ], "properties": { "delivery_contact": { "description": "Contact information for delivery to the pickup location.", "$ref": "#/definitions/Contact" }, "distances": { "description": "The distances to the pickup location, e.g., walking or driving.", "$ref": "#/definitions/PickupLocationDistances", "readOnly": true }, "external_id": { "description": "External identifier provided by the merchant or carrier.", "type": "string" }, "id": { "description": "Internal location identifier, used within the system.", "type": "string" }, "location_type": { "description": "The type of the pickup location, e.g., LOCKER, STORE.", "$ref": "#/definitions/PickupLocationLocationType" }, "operational_hours": { "description": "Operational hours of the pickup location. If none are provided, the location is available at all times.", "$ref": "#/definitions/PickupLocationOperationalHours" }, "sections": { "description": "Additional informational sections about the pickup location.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/PickupLocationSection" } }, "title": { "description": "The title of the location displayed to the customer.", "type": "string" }, "visiting_contact": { "description": "Contact information when visiting the location for retrieving a package.", "$ref": "#/definitions/Contact" } } }, "PickupLocationDistances": { "description": "Distances define the walking and driving distances to the pickup location.", "type": "object", "properties": { "driving": { "description": "The driving distance to the pickup location.", "$ref": "#/definitions/Distance" }, "walking": { "description": "The walking distance to the pickup location.", "$ref": "#/definitions/Distance" } } }, "PickupLocationLocationType": { "description": "LocationType defines the type of the pickup location.\n\n - LOCATION_TYPE_UNSPECIFIED: Unspecified type.\n - LOCKER: A locker pickup location.\n - STORE: A store pickup location.\n - POSTOFFICE: A post office pickup location.\n - MANNED: A manned pickup location, e.g., staffed desk.\n - AGE_VERIFICATION: A pickup location that supports age verification (age check).", "type": "string", "default": "LOCATION_TYPE_UNSPECIFIED", "enum": [ "LOCATION_TYPE_UNSPECIFIED", "LOCKER", "STORE", "POSTOFFICE", "MANNED", "AGE_VERIFICATION" ] }, "PickupLocationOperationalHours": { "description": "OperationalHours define when the pickup location is operating.", "type": "object", "properties": { "free_text": { "description": "Free-text operational hours for fallback.", "type": "array", "items": { "type": "string" } }, "friday": { "description": "Opening hours for Friday.", "type": "array", "items": { "type": "string" } }, "monday": { "description": "Opening hours for Monday.", "type": "array", "items": { "type": "string" } }, "saturday": { "description": "Opening hours for Saturday.", "type": "array", "items": { "type": "string" } }, "sunday": { "description": "Opening hours for Sunday.", "type": "array", "items": { "type": "string" } }, "thursday": { "description": "Opening hours for Thursday.", "type": "array", "items": { "type": "string" } }, "tuesday": { "description": "Opening hours for Tuesday.", "type": "array", "items": { "type": "string" } }, "wednesday": { "description": "Opening hours for Wednesday.", "type": "array", "items": { "type": "string" } } } }, "PickupLocationSection": { "description": "Section provides extra information about the pickup location.", "type": "object", "required": [ "title", "columns" ], "properties": { "columns": { "description": "The columns of items in the section.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/SectionColumn" } }, "title": { "description": "The title of the section displayed to the customer.", "type": "string" } } }, "PriceLevelsPriceLevel": { "type": "object", "properties": { "activation_price": { "description": "The activation price for this level.\nUnit is the smallest currency unit, e.g., cents for USD, yen for JPY.", "type": "string", "format": "int64" }, "active": { "description": "Indicates if this price level is active.", "type": "boolean" }, "base": { "description": "Indicates if this is the base price.", "type": "boolean" }, "delivery_price": { "description": "The delivery price for this level.\nUnit is the smallest currency unit, e.g., cents for USD, yen for JPY.", "type": "string", "format": "int64" } } }, "ReturnsPromise": { "description": "ReturnPromise contains promise for returns and exchanges for a user and a cart.", "type": "object", "properties": { "currency_code": { "description": "Currency code for the return promise, e.g., \"USD\", \"EUR\".", "type": "string", "readOnly": true }, "exchange_cost": { "description": "Non-negative cost of exchanging the item, or items. Unit is cents.", "type": "string", "format": "int64", "readOnly": true }, "exchanges_enabled": { "description": "Indicates whether exchanges are enabled. See `exchange_cost` for the associated cost.", "type": "boolean", "readOnly": true }, "id": { "description": "Unique identifier for the return promise.", "type": "string", "readOnly": true }, "is_unavailable": { "description": "Indicates if the return promise is unavailable due to API failures or other issues.\nWhen true, consider displaying a \"Return details unavailable\" message to the end user.", "type": "boolean", "readOnly": true }, "return_cost": { "description": "Non-negative cost of returning the item, or items. Unit is cents.", "type": "string", "format": "int64", "readOnly": true }, "return_policy_text": { "description": "Return Policy text suitable for presentation to the customer.", "type": "string", "readOnly": true }, "return_policy_url": { "description": "Return Policy URL, which is suitable for presentation to the customer.", "type": "string", "readOnly": true }, "return_time_days": { "description": "Time in days to return or exchange the item.", "type": "integer", "format": "int32", "readOnly": true }, "returns_enabled": { "description": "Indicates whether returns are enabled. See `return_cost` for the associated cost.", "type": "boolean", "readOnly": true } } }, "SectionColumn": { "description": "Column contains a list of items displayed in a single section column.", "type": "object", "required": [ "items" ], "properties": { "items": { "description": "The items within the column.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/SectionItem" } } } }, "SectionItem": { "description": "Item represents a single piece of information in a section.", "type": "object", "properties": { "icon_uri": { "description": "The URI for the item's icon.", "type": "string" }, "link_uri": { "description": "The URI for a link associated with the item.", "type": "string" }, "text": { "description": "The text description of the item.", "type": "string" } } }, "Session": { "description": "A Session is the primary resource for handling the delivery options and the customer lifecycle.", "type": "object", "required": [ "purchase", "deliveries" ], "properties": { "create_time": { "description": "The timestamp when the session was created.", "type": "string", "format": "date-time", "readOnly": true }, "deliveries": { "description": "The deliveries included in this session.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/Delivery" } }, "etag": { "description": "The current etag of the session.\nIf an etag is provided and does not match the current etag of the session,\nupdates and completion will be blocked and an ABORTED error will be returned.", "type": "string" }, "name": { "type": "string", "title": "The resource name of the session. Format: sessions/{session_id}" }, "purchase": { "description": "The purchase for the given session.", "$ref": "#/definitions/SessionPurchase" }, "returns_promise": { "description": "The returns promise for the session generated by Ingrid Returns product.", "$ref": "#/definitions/ReturnsPromise", "readOnly": true }, "state": { "description": "The state of the session.", "$ref": "#/definitions/SessionState", "readOnly": true }, "update_time": { "description": "The timestamp when the session was last updated.", "type": "string", "format": "date-time", "readOnly": true } } }, "SessionPurchase": { "description": "Purchase describes purchase experience.", "type": "object", "required": [ "country_code", "currency_code" ], "properties": { "country_code": { "description": "\nThe country code where the delivery will occur (ISO 3166-1 alpha-2).", "type": "string" }, "currency_code": { "description": "The currency code for the transaction (ISO 4217).", "type": "string" }, "locales": { "description": "Locales list defined as lc-CC compliant with ISO 3166-1, in order of preference(first supported one will be chosen).", "type": "array", "items": { "type": "string" } }, "total_discount": { "description": "The total discount applied to the purchase (non-negative, in cents).", "type": "string", "format": "int64" }, "total_value": { "description": "The total value of the purchase after discounts are applied (non-negative, in cents).", "type": "string", "format": "int64" }, "vouchers": { "description": "List of vouchers.", "type": "array", "items": { "type": "string" } } } }, "SessionState": { "description": "State defines the current state of the session.\n\n - STATE_UNSPECIFIED: Default value. This value is unused.\n - ACTIVE: Session is active and can be modified.\n - COMPLETED: Session is completed and can not be modified.", "type": "string", "default": "STATE_UNSPECIFIED", "enum": [ "STATE_UNSPECIFIED", "ACTIVE", "COMPLETED" ] }, "Error": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "details": { "description": "Optional structured error payload. Most APIs use the fields below; some endpoints return endpoint-specific objects.", "type": "object", "properties": { "cause": { "description": "Numeric error cause code; cause_text carries its symbolic name.", "type": "integer", "format": "int32" }, "cause_text": { "type": "string" }, "msg": { "type": "string" }, "source": { "type": "string" } }, "additionalProperties": true }, "error": { "type": "string" }, "message": { "type": "string" }, "trace_id": { "type": "string" } } } }, "securityDefinitions": { "Bearer": { "type": "apiKey", "name": "Authorization", "in": "header" } }, "security": [ { "Bearer": [] } ] }