{ "swagger": "2.0", "info": { "title": "Delivery API", "description": "API for managing delivery sessions, retrieving delivery options, and completing checkout.", "version": "v1" }, "tags": [ { "name": "DeliveryService" } ], "basePath": "/delivery/v1", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/sessions": { "post": { "summary": "Creates a new session.", "operationId": "DeliveryService_CreateSession", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/deliverySession" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "session", "description": "The session to create.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/deliverySession", "required": [ "session" ] } } ], "tags": [ "DeliveryService" ] } }, "/sessions:lookup": { "get": { "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", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/deliverySession" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "tos_id", "description": "The TOS ID of one of the session's deliveries.", "in": "query", "required": true, "type": "string" } ], "tags": [ "DeliveryService" ] } }, "/{name}": { "get": { "summary": "Gets a session by resource name.", "operationId": "DeliveryService_GetSession", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/deliverySession" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "name", "description": "The resource name of the shipping session to retrieve.\nFormat: sessions/{session_id}", "in": "path", "required": true, "type": "string", "pattern": "sessions/[^/]+" } ], "tags": [ "DeliveryService" ] } }, "/{name}:complete": { "post": { "summary": "Completes a session and saves the user choices.", "operationId": "DeliveryService_CompleteSession", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/deliveryCompleteSessionResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "name", "description": "The resource name of the shipping session to complete.\nFormat: sessions/{session_id}", "in": "path", "required": true, "type": "string", "pattern": "sessions/[^/]+" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/DeliveryServiceCompleteSessionBody" } } ], "tags": [ "DeliveryService" ] } }, "/{name}:convert": { "post": { "summary": "Converts session to the given format.\nUnderlying session resource stays unchanged.", "operationId": "DeliveryService_ConvertSession", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/deliveryConvertSessionResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "name", "description": "The resource name of the shipping session to retrieve.\nFormat: sessions/{session_id}", "in": "path", "required": true, "type": "string", "pattern": "sessions/[^/]+" }, { "name": "format", "description": "Target format.", "in": "query", "required": true, "type": "string", "enum": [ "FORMAT_UNSPECIFIED", "AGENTIC_CHECKOUT" ], "default": "FORMAT_UNSPECIFIED" } ], "tags": [ "DeliveryService" ] } }, "/{session.name}": { "patch": { "summary": "Updates a session.", "operationId": "DeliveryService_UpdateSession", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/deliverySession" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "session.name", "description": "The resource name of the session. Format: sessions/{session_id}", "in": "path", "required": true, "type": "string", "pattern": "sessions/[^/]+" }, { "name": "session", "description": "The session to update.", "in": "body", "required": true, "schema": { "type": "object", "properties": { "state": { "$ref": "#/definitions/SessionState", "description": "The state of the session.", "readOnly": true }, "purchase": { "$ref": "#/definitions/SessionPurchase", "description": "The purchase for the given session." }, "deliveries": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1alphadeliveryDelivery" }, "description": "The deliveries included in this session." }, "create_time": { "type": "string", "format": "date-time", "description": "The timestamp when the session was created.", "readOnly": true }, "update_time": { "type": "string", "format": "date-time", "description": "The timestamp when the session was last updated.", "readOnly": true }, "etag": { "type": "string", "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." }, "returns_promise": { "$ref": "#/definitions/deliveryReturnsPromise", "description": "The returns promise for the session generated by Ingrid Returns product.", "readOnly": true } }, "title": "The session to update.", "required": [ "purchase", "deliveries", "session" ] } } ], "tags": [ "DeliveryService" ] } } }, "definitions": { "AddonAddonType": { "type": "string", "enum": [ "ADDON_TYPE_UNSPECIFIED", "CUSTOM", "CARRY_IN", "LEAVE_AT_DOOR", "UNWRAPPING" ], "default": "ADDON_TYPE_UNSPECIFIED", "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." }, "AgenticCheckoutSessionFulfillmentOption": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the fulfillment option." }, "title": { "type": "string", "description": "Display title of the fulfillment option." }, "subtitle": { "type": "string", "description": "Additional display text, e.g., estimated delivery time." }, "carrier": { "type": "string", "description": "Name of the carrier providing this option." }, "earliest_delivery_time": { "type": "string", "format": "date-time", "description": "The earliest possible delivery time." }, "latest_delivery_time": { "type": "string", "format": "date-time", "description": "The latest possible delivery time." }, "subtotal": { "type": "string", "format": "int64", "description": "Subtotal price in minor currency units, e.g., cents." }, "tax": { "type": "string", "format": "int64", "description": "Tax amount in minor currency units, e.g., cents." }, "total": { "type": "string", "format": "int64", "description": "Total price in minor currency units, e.g., cents." }, "type": { "type": "string", "description": "Fulfillment type. Value: \"shipping\"." } }, "description": "Represents a fulfillment option in the agentic checkout format." }, "ContactPhoneNumber": { "type": "object", "properties": { "country_code": { "type": "string", "description": "\nThe country code where the delivery will occur (ISO 3166-1 alpha-2)." }, "number": { "type": "string", "description": "The main phone number, formatted as per the region's conventions." }, "extension": { "type": "string", "description": "An optional phone number extension." } }, "description": "A phone number, including region and optional extension.", "required": [ "country_code", "number" ] }, "ConvertSessionRequestFormat": { "type": "string", "enum": [ "FORMAT_UNSPECIFIED", "AGENTIC_CHECKOUT" ], "default": "FORMAT_UNSPECIFIED" }, "DeliveryCategoryDeliveryType": { "type": "string", "enum": [ "DELIVERY_TYPE_UNSPECIFIED", "DELIVERY", "PICKUP", "MAILBOX", "INSTORE" ], "default": "DELIVERY_TYPE_UNSPECIFIED", "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." }, "DeliveryCategoryOptionsSource": { "type": "string", "enum": [ "OPTIONS_SOURCE_UNSPECIFIED", "FALLBACK", "CARRIER" ], "default": "OPTIONS_SOURCE_UNSPECIFIED", "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." }, "DeliveryCategoryPriceLevels": { "type": "object", "properties": { "price_levels": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/PriceLevelsPriceLevel" }, "description": "Available price levels for the carrier product.\nOnly the base price and prices with the `total_value` price rule are included." } } }, "DeliveryCategoryWarehouse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the warehouse." }, "address": { "$ref": "#/definitions/v1alphadeliveryAddress", "description": "The address of the warehouse." }, "external_id": { "type": "string", "description": "The external identifier of a warehouse, used for integration purposes." } }, "description": "Information about a warehouse.\nAll this data is stored in the site configuration.", "required": [ "id", "address" ] }, "DeliveryNodeHandoff": { "type": "object", "properties": { "earliest_time": { "type": "string", "format": "date-time", "description": "The earliest time the node can hand off the delivery." }, "latest_time": { "type": "string", "format": "date-time", "description": "The latest time the node can hand off the delivery." } }, "description": "Constraints on the node's handoff." }, "DeliveryNodeRole": { "type": "string", "enum": [ "ROLE_UNSPECIFIED", "ORIGIN", "DESTINATION" ], "default": "ROLE_UNSPECIFIED", "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." }, "DeliveryOptionCarrier": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the carrier company, e.g., \"DHL\", \"FedEx\"." }, "product_name": { "type": "string", "description": "The product or service level name provided by the carrier, e.g., \"Parcel\", \"Standard\"." }, "product_id": { "type": "string", "description": "The product or service level identifier provided by the carrier, e.g., \"dhl-par\", \"ups-std\"." }, "sort_order": { "type": "integer", "format": "int32", "description": "The original sort order assigned by the carrier." }, "meta": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Carrier-specific metadata." }, "external_id": { "type": "string", "description": "Merchant-specific carrier product identifier." } }, "description": "The Carrier contains details about the shipping carrier associated with this delivery option.", "required": [ "name", "product_name", "product_id", "external_id" ] }, "DeliveryOptionOrigin": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the origin." }, "address": { "$ref": "#/definitions/v1alphadeliveryAddress", "description": "The address of the origin." }, "external_id": { "type": "string", "description": "External identifier of the origin, used for integration purposes." } }, "description": "Where delivery originates from.", "required": [ "id", "address" ] }, "DeliveryServiceCompleteSessionBody": { "type": "object", "properties": { "delivery_choices": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/deliveryDeliveryChoice" }, "description": "List of choices for the given deliveries." } }, "description": "Request message for completing a session." }, "ETDAbsolute": { "type": "object", "properties": { "earliest_time": { "type": "string", "format": "date-time", "description": "The earliest possible delivery time. If unspecified, delivery is considered to be immediate." }, "latest_time": { "type": "string", "format": "date-time", "description": "The latest possible delivery time. If unspecified, there is no guaranteed maximum time." } }, "description": "Absolute represents an ETD as a single or pair of timestamps." }, "ETDCustom": { "type": "object", "properties": { "text": { "type": "string", "description": "Description in a text form, e.g., \"Before Christmas\", \"Same day if ordered before 2PM\"." } }, "description": "Custom represents an ETD in a human-readable text format.", "required": [ "text" ] }, "ETDRelative": { "type": "object", "properties": { "unit": { "$ref": "#/definitions/ETDTimeUnit", "description": "The unit of time used by the ETD range." }, "earliest": { "type": "integer", "format": "int32", "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)." }, "latest": { "type": "integer", "format": "int32", "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)." } }, "description": "Relative represents an ETD as a range of time units.", "required": [ "unit" ] }, "ETDTimeUnit": { "type": "string", "enum": [ "TIME_UNIT_UNSPECIFIED", "TIME_UNIT_MINUTE", "TIME_UNIT_HOUR", "TIME_UNIT_DAY", "TIME_UNIT_BUSINESS_DAY", "TIME_UNIT_WEEK", "TIME_UNIT_MONTH" ], "default": "TIME_UNIT_UNSPECIFIED", "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" }, "FulfillmentReadiness": { "type": "object", "properties": { "earliest_time": { "type": "string", "format": "date-time", "description": "The earliest timestamp when the goods will be ready for shipment." }, "latest_time": { "type": "string", "format": "date-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." } }, "description": "Readiness specifies a time range when the goods will be ready for shipment.", "required": [ "earliest_time" ] }, "LabelLabelType": { "type": "string", "enum": [ "LABEL_TYPE_UNKNOWN", "LABEL_TYPE_SUSTAINABILITY", "LABEL_TYPE_PRIORITY", "LABEL_TYPE_CUSTOM", "LABEL_TYPE_SWAN" ], "default": "LABEL_TYPE_UNKNOWN", "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." }, "LineItemDimensions": { "type": "object", "properties": { "height": { "type": "integer", "format": "int32", "description": "Height of the item in millimeters, must be greater than 0." }, "length": { "type": "integer", "format": "int32", "description": "Length of the item in millimeters, must be greater than 0." }, "width": { "type": "integer", "format": "int32", "description": "Width of the item in millimeters, must be greater than 0." } }, "description": "Represents the dimensions of the item.", "required": [ "height", "length", "width" ] }, "LocationByRef": { "type": "object", "properties": { "external_id": { "type": "string", "description": "External identifier provided by the merchant or carrier." } }, "description": "To reference an existing location.", "required": [ "external_id" ] }, "LocationByValue": { "type": "object", "properties": { "external_id": { "type": "string", "description": "External identifier provided by the merchant or carrier." }, "delivery_contact": { "$ref": "#/definitions/v1alphadeliveryContact", "description": "Contact information for delivery purposes." }, "visiting_contact": { "$ref": "#/definitions/v1alphadeliveryContact", "description": "Contact information for visiting purposes.\nWhen missing delivery_contact is used." }, "display_name": { "type": "string", "description": "Location name that is displayed to the customer." } }, "description": "To provide full information about the location.", "required": [ "external_id", "delivery_contact" ] }, "PickupLocationDistances": { "type": "object", "properties": { "walking": { "$ref": "#/definitions/deliveryDistance", "description": "The walking distance to the pickup location." }, "driving": { "$ref": "#/definitions/deliveryDistance", "description": "The driving distance to the pickup location." } }, "description": "Distances define the walking and driving distances to the pickup location." }, "PickupLocationLocationType": { "type": "string", "enum": [ "LOCATION_TYPE_UNSPECIFIED", "LOCKER", "STORE", "POSTOFFICE", "MANNED", "AGE_VERIFICATION" ], "default": "LOCATION_TYPE_UNSPECIFIED", "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)." }, "PickupLocationOperationalHours": { "type": "object", "properties": { "monday": { "type": "array", "items": { "type": "string" }, "description": "Opening hours for Monday." }, "tuesday": { "type": "array", "items": { "type": "string" }, "description": "Opening hours for Tuesday." }, "wednesday": { "type": "array", "items": { "type": "string" }, "description": "Opening hours for Wednesday." }, "thursday": { "type": "array", "items": { "type": "string" }, "description": "Opening hours for Thursday." }, "friday": { "type": "array", "items": { "type": "string" }, "description": "Opening hours for Friday." }, "saturday": { "type": "array", "items": { "type": "string" }, "description": "Opening hours for Saturday." }, "sunday": { "type": "array", "items": { "type": "string" }, "description": "Opening hours for Sunday." }, "free_text": { "type": "array", "items": { "type": "string" }, "description": "Free-text operational hours for fallback." } }, "description": "OperationalHours define when the pickup location is operating." }, "PickupLocationSection": { "type": "object", "properties": { "title": { "type": "string", "description": "The title of the section displayed to the customer." }, "columns": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/SectionColumn" }, "description": "The columns of items in the section." } }, "description": "Section provides extra information about the pickup location.", "required": [ "title", "columns" ] }, "PriceLevelsPriceLevel": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Indicates if this price level is active." }, "base": { "type": "boolean", "description": "Indicates if this is the base price." }, "activation_price": { "type": "string", "format": "int64", "description": "The activation price for this level.\nUnit is the smallest currency unit, e.g., cents for USD, yen for JPY." }, "delivery_price": { "type": "string", "format": "int64", "description": "The delivery price for this level.\nUnit is the smallest currency unit, e.g., cents for USD, yen for JPY." } } }, "SectionColumn": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/SectionItem" }, "description": "The items within the column." } }, "description": "Column contains a list of items displayed in a single section column.", "required": [ "items" ] }, "SectionItem": { "type": "object", "properties": { "icon_uri": { "type": "string", "description": "The URI for the item's icon." }, "text": { "type": "string", "description": "The text description of the item." }, "link_uri": { "type": "string", "description": "The URI for a link associated with the item." } }, "description": "Item represents a single piece of information in a section." }, "SessionPurchase": { "type": "object", "properties": { "country_code": { "type": "string", "description": "\nThe country code where the delivery will occur (ISO 3166-1 alpha-2)." }, "currency_code": { "type": "string", "description": "The currency code for the transaction (ISO 4217)." }, "total_discount": { "type": "string", "format": "int64", "description": "The total discount applied to the purchase (non-negative, in cents)." }, "total_value": { "type": "string", "format": "int64", "description": "The total value of the purchase after discounts are applied (non-negative, in cents)." }, "vouchers": { "type": "array", "items": { "type": "string" }, "description": "List of vouchers." }, "locales": { "type": "array", "items": { "type": "string" }, "description": "Locales list defined as lc-CC compliant with ISO 3166-1, in order of preference(first supported one will be chosen)." } }, "description": "Purchase describes purchase experience.", "required": [ "country_code", "currency_code" ] }, "SessionState": { "type": "string", "enum": [ "STATE_UNSPECIFIED", "ACTIVE", "COMPLETED" ], "default": "STATE_UNSPECIFIED", "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." }, "deliveryAddon": { "type": "object", "properties": { "display_name": { "type": "string", "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." }, "price": { "type": "string", "format": "int64", "description": "The price of the addon in minor currency units, e.g., cents.", "readOnly": true }, "addon_type": { "$ref": "#/definitions/AddonAddonType", "description": "The type of the addon.", "readOnly": true }, "preselected": { "type": "boolean", "description": "Indicates if this addon should be preselected by default." }, "chosen": { "type": "boolean", "description": "Indicates if this addon was chosen." }, "id": { "type": "string", "description": "Unique addon identifier.", "readOnly": true }, "external_id": { "type": "string", "description": "The external identifier of an addon, used for integration purposes.", "readOnly": true }, "description": { "type": "string", "description": "The display-friendly description of the addon.\nDisplay name and description are localized, if translations are provided.", "readOnly": true } }, "description": "An Addon represents an additional service or feature offered with a delivery.", "required": [ "display_name" ] }, "deliveryAgenticCheckoutSession": { "type": "object", "properties": { "name": { "type": "string", "title": "The resource name of the session. Format: sessions/{session_id}" }, "deliveries": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/deliveryAgenticCheckoutSessionDelivery" }, "description": "The deliveries included in this session.", "readOnly": true } }, "description": "Represents a session in agentic checkout format." }, "deliveryAgenticCheckoutSessionAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name associated with the address." }, "line_one": { "type": "string", "description": "Primary address line, e.g., street name and number." }, "line_two": { "type": "string", "description": "Secondary address line, e.g., apartment or suite number." }, "city": { "type": "string", "description": "City or locality." }, "state": { "type": "string", "description": "State or region." }, "country": { "type": "string", "description": "Country code (ISO 3166-1 alpha-2)." }, "postal_code": { "type": "string", "description": "Postal code or ZIP code." } }, "description": "Represents an address in the agentic checkout format." }, "deliveryAgenticCheckoutSessionDelivery": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of a delivery." }, "fulfillment_address": { "$ref": "#/definitions/deliveryAgenticCheckoutSessionAddress", "description": "The address for fulfillment." }, "fulfillment_options": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/AgenticCheckoutSessionFulfillmentOption" }, "description": "Available fulfillment options." }, "fulfillment_option_id": { "type": "string", "description": "The ID of the selected fulfillment option." } } }, "deliveryCarrierAttributes": { "type": "object", "properties": { "customer_reference": { "type": "string", "description": "When set, describes a customer reference identifier that is contextually meaningful\nfor the carrier." } }, "description": "Additional attributes required by a carrier product or integration." }, "deliveryCompleteSessionResponse": { "type": "object", "properties": { "session": { "$ref": "#/definitions/deliverySession", "description": "The completed session." } }, "description": "Response message for completing a session.", "required": [ "session" ] }, "deliveryConvertSessionResponse": { "type": "object", "properties": { "ingrid": { "$ref": "#/definitions/deliverySession", "description": "The session in Ingrid's native format." }, "agentic_checkout": { "$ref": "#/definitions/deliveryAgenticCheckoutSession", "description": "The session in agentic checkout format." } }, "description": "Response message for converted session." }, "deliveryCoordinates": { "type": "object", "properties": { "lat": { "type": "number", "format": "double", "description": "The latitude in degrees. Must be within the range -90.0 to +90.0, inclusive." }, "lng": { "type": "number", "format": "double", "description": "The longitude in degrees. Must be within the range -180.0 to +180.0, inclusive." } }, "description": "Represents a latitude/longitude pair.\nUnless specified otherwise, this must conform to the WGS84 standard.\nValues must be within normalized ranges.", "required": [ "lat", "lng" ] }, "deliveryDeliveryCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of a delivery category." }, "external_id": { "type": "string", "description": "The external identifier of a category, used for integration purposes." }, "delivery_type": { "$ref": "#/definitions/DeliveryCategoryDeliveryType", "description": "The delivery type associated with this category." }, "display_name": { "type": "string", "description": "A human-readable name of the category, which will be presented to the customer." }, "sort_order": { "type": "integer", "format": "int32", "description": "Defines the order in which the category will be presented to the customer." }, "options_source": { "$ref": "#/definitions/DeliveryCategoryOptionsSource", "description": "The source of delivery options for this category." }, "delivery_options": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/deliveryDeliveryOption" }, "description": "The delivery options available within this category." }, "addons": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/deliveryAddon" }, "description": "Add-ons that are available for this category, e.g., gift wrapping, insurance." }, "preselected": { "type": "boolean", "description": "Indicates if this category should be preselected by default." }, "chosen": { "type": "boolean", "description": "Indicates if this category was chosen by the user." }, "warehouse": { "$ref": "#/definitions/DeliveryCategoryWarehouse", "description": "Information about the warehouse that the category is assigned to.\nDeprecated: use delivery_options.*.origin instead.", "readOnly": true }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags associated with the delivery category, used for cross-reference purposes.", "readOnly": true }, "labels": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/deliveryDeliveryCategoryLabel" }, "description": "Information about active labels associated with the delivery category.\nLabels name and description are localized, if translations are provided.", "readOnly": true }, "custom_text": { "type": "string", "description": "Additional text that can be displayed with the category.\nThe presence of this field depends on the locale.", "readOnly": true }, "custom_info_text": { "type": "string", "description": "Additional information that can be displayed with the category.\nThe presence of this field depends on the locale.", "readOnly": true }, "price_levels": { "type": "object", "additionalProperties": { "$ref": "#/definitions/DeliveryCategoryPriceLevels" }, "title": "Map of category's carrier product IDs to price levels", "readOnly": true } }, "description": "The DeliveryCategory represents a grouping of delivery options that share the same type and other characteristics.", "required": [ "id", "delivery_type", "display_name", "options_source", "delivery_options" ] }, "deliveryDeliveryCategoryLabel": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the label." }, "name": { "type": "string", "description": "Display name of the label." }, "description": { "type": "string", "description": "Description of the label displayed to the customer." }, "type": { "$ref": "#/definitions/LabelLabelType", "description": "The type of the label." }, "color": { "type": "string", "description": "Color code for the label, e.g., hex value." }, "icon": { "type": "string", "description": "URI or identifier for the label icon." }, "dark_mode_color": { "type": "string", "description": "Color code for the label in dark mode, e.g., hex value." } }, "description": "Labels provide additional, customer-facing information for the delivery category." }, "deliveryDeliveryChoice": { "type": "object", "properties": { "delivery_id": { "type": "string", "description": "The unique identifier of the delivery." }, "option_id": { "type": "string", "description": "The selected delivery option." }, "addon_ids": { "type": "array", "items": { "type": "string" }, "description": "The selected delivery addons, if applicable." }, "external_id": { "type": "string", "description": "ID assigned by the merchant to a specific delivery.\nUsed as external ID of the TOS." }, "carrier_attributes": { "$ref": "#/definitions/deliveryCarrierAttributes", "title": "When set, includes additional information/metadata for the selected carrier" } }, "description": "The DeliveryChoice represents what option is selected for the given delivery.", "required": [ "delivery_id", "option_id" ] }, "deliveryDeliveryNode": { "type": "object", "properties": { "handoff": { "$ref": "#/definitions/DeliveryNodeHandoff", "description": "When the node is ready for handoff." }, "location": { "$ref": "#/definitions/deliveryDeliveryNodeLocation", "description": "Where the node is physically located." }, "roles": { "type": "array", "items": { "$ref": "#/definitions/DeliveryNodeRole" }, "description": "What roles the node can perform." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Additional metadata about the node.\nFor cross-reference purposes." } }, "required": [ "location", "roles" ] }, "deliveryDeliveryNodeLocation": { "type": "object", "properties": { "by_value": { "$ref": "#/definitions/LocationByValue" }, "by_ref": { "$ref": "#/definitions/LocationByRef" } }, "description": "Where the node is physically located." }, "deliveryDeliveryOption": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the delivery option." }, "carrier": { "$ref": "#/definitions/DeliveryOptionCarrier", "description": "Information about the carrier responsible for this delivery." }, "pickup_location": { "$ref": "#/definitions/deliveryPickupLocation", "description": "The pickup location for this delivery option, if applicable." }, "etd": { "$ref": "#/definitions/deliveryETD", "description": "The ETD for this option." }, "preselected": { "type": "boolean", "description": "Indicates if this delivery option should be preselected by default." }, "chosen": { "type": "boolean", "description": "Indicates if this delivery option was chosen by the customer." }, "expire_time": { "type": "string", "format": "date-time", "description": "The expiration timestamp in UTC of the delivery option." }, "price": { "type": "string", "format": "int64", "description": "Price associated with the delivery option in minor currency units, e.g., cents." }, "origin": { "$ref": "#/definitions/DeliveryOptionOrigin", "description": "Where delivery originates from." } }, "description": "The DeliveryOption represents the details of a specific delivery option.", "required": [ "id", "carrier", "etd", "price", "origin" ] }, "deliveryDistance": { "type": "object", "properties": { "meters": { "type": "string", "format": "int64", "description": "Approximate distance in meters.", "readOnly": true }, "minutes": { "type": "string", "format": "int64", "description": "Approximate duration in minutes.", "readOnly": true } }, "description": "Represents a distance measurement with both spatial distance and estimated travel time." }, "deliveryETD": { "type": "object", "properties": { "relative": { "$ref": "#/definitions/ETDRelative", "description": "Estimate expressed as a range of time units." }, "absolute": { "$ref": "#/definitions/ETDAbsolute", "description": "Estimate expressed as a range of timestamps." }, "custom": { "$ref": "#/definitions/ETDCustom", "title": "Estimate expressed as a custom text" } }, "description": "ETD stands for Estimated Time of Delivery." }, "deliveryFulfillment": { "type": "object", "properties": { "readiness": { "$ref": "#/definitions/FulfillmentReadiness", "description": "The time window when the goods will be ready for shipment." }, "category_tags": { "type": "array", "items": { "type": "string" }, "description": "List of category tags, to which the `Readiness` applies.\nIf empty, the `Readiness` applies to all categories." } }, "description": "A Fulfillment details when a delivery can be fulfilled.", "required": [ "readiness" ] }, "deliveryLineItem": { "type": "object", "properties": { "sku": { "type": "string", "description": "The unique item identifier of the item." }, "title": { "type": "string", "description": "The item name or title, which is suitable for presentation to the customer." }, "quantity": { "type": "integer", "format": "int32", "description": "Total quantity of the item." }, "weight": { "type": "integer", "format": "int32", "description": "Weight of a single item in grams, must be greater than 0." }, "dimensions": { "$ref": "#/definitions/LineItemDimensions", "description": "Dimensions of the item." }, "discount": { "type": "string", "format": "int64", "description": "Non-negative discount applied to the item, or items. Unit is cents." }, "price": { "type": "string", "format": "int64", "description": "Non-negative price of a single item after applying discounts. Unit is cents." }, "image_uri": { "type": "string", "description": "URI of the product image, e.g., thumbnail." }, "attributes": { "type": "array", "items": { "type": "string" }, "description": "Used to control the behaviour of the filter/price rules.\nEquivalent of cart_items_attributes in the `Delivery Checkout` API." } }, "description": "Represents a single item.", "required": [ "sku", "title", "quantity" ] }, "deliveryPickupLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Internal location identifier, used within the system." }, "external_id": { "type": "string", "description": "External identifier provided by the merchant or carrier." }, "location_type": { "$ref": "#/definitions/PickupLocationLocationType", "description": "The type of the pickup location, e.g., LOCKER, STORE." }, "title": { "type": "string", "description": "The title of the location displayed to the customer." }, "visiting_contact": { "$ref": "#/definitions/v1alphadeliveryContact", "description": "Contact information when visiting the location for retrieving a package." }, "delivery_contact": { "$ref": "#/definitions/v1alphadeliveryContact", "description": "Contact information for delivery to the pickup location." }, "operational_hours": { "$ref": "#/definitions/PickupLocationOperationalHours", "description": "Operational hours of the pickup location. If none are provided, the location is available at all times." }, "sections": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/PickupLocationSection" }, "description": "Additional informational sections about the pickup location." }, "distances": { "$ref": "#/definitions/PickupLocationDistances", "description": "The distances to the pickup location, e.g., walking or driving.", "readOnly": true } }, "description": "The PickupLocation represents a physical location from which a delivery can be retrieved.", "required": [ "id", "external_id", "title" ] }, "deliveryReturnsPromise": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the return promise.", "readOnly": true }, "currency_code": { "type": "string", "description": "Currency code for the return promise, e.g., \"USD\", \"EUR\".", "readOnly": true }, "returns_enabled": { "type": "boolean", "description": "Indicates whether returns are enabled. See `return_cost` for the associated cost.", "readOnly": true }, "return_cost": { "type": "string", "format": "int64", "description": "Non-negative cost of returning the item, or items. Unit is cents.", "readOnly": true }, "exchanges_enabled": { "type": "boolean", "description": "Indicates whether exchanges are enabled. See `exchange_cost` for the associated cost.", "readOnly": true }, "exchange_cost": { "type": "string", "format": "int64", "description": "Non-negative cost of exchanging the item, or items. Unit is cents.", "readOnly": true }, "return_time_days": { "type": "integer", "format": "int32", "description": "Time in days to return or exchange the item.", "readOnly": true }, "return_policy_text": { "type": "string", "description": "Return Policy text suitable for presentation to the customer.", "readOnly": true }, "return_policy_url": { "type": "string", "description": "Return Policy URL, which is suitable for presentation to the customer.", "readOnly": true }, "is_unavailable": { "type": "boolean", "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.", "readOnly": true } }, "description": "ReturnPromise contains promise for returns and exchanges for a user and a cart." }, "deliverySession": { "type": "object", "properties": { "name": { "type": "string", "title": "The resource name of the session. Format: sessions/{session_id}" }, "state": { "$ref": "#/definitions/SessionState", "description": "The state of the session.", "readOnly": true }, "purchase": { "$ref": "#/definitions/SessionPurchase", "description": "The purchase for the given session." }, "deliveries": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1alphadeliveryDelivery" }, "description": "The deliveries included in this session." }, "create_time": { "type": "string", "format": "date-time", "description": "The timestamp when the session was created.", "readOnly": true }, "update_time": { "type": "string", "format": "date-time", "description": "The timestamp when the session was last updated.", "readOnly": true }, "etag": { "type": "string", "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." }, "returns_promise": { "$ref": "#/definitions/deliveryReturnsPromise", "description": "The returns promise for the session generated by Ingrid Returns product.", "readOnly": true } }, "description": "A Session is the primary resource for handling the delivery options and the customer lifecycle.", "required": [ "purchase", "deliveries" ] }, "protobufAny": { "type": "object", "properties": { "@type": { "type": "string" } }, "additionalProperties": {} }, "rpcStatus": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/protobufAny" } } } }, "v1alphadeliveryAddress": { "type": "object", "properties": { "country_code": { "type": "string", "description": "\nRefers to a ISO-3166 alpha 2 country code." }, "region_code": { "type": "string", "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`." }, "postal_code": { "type": "string", "description": "Refers to a postal code or zipcode." }, "city": { "type": "string", "description": "Refers to a city, postal_town or locality." }, "address_lines": { "type": "array", "items": { "type": "string" }, "description": "List of strings, each a part of the address, e.g., street name, street number, building name, floor." }, "coordinates": { "$ref": "#/definitions/deliveryCoordinates", "description": "Geolocation of the given address." } }, "description": "Represents an address suitable for delivery.", "required": [ "country_code" ] }, "v1alphadeliveryContact": { "type": "object", "properties": { "address": { "$ref": "#/definitions/v1alphadeliveryAddress", "description": "The physical address of the contact." }, "email": { "type": "string", "description": "The email address of the contact." }, "phone_number": { "$ref": "#/definitions/ContactPhoneNumber", "description": "The phone number of the contact, including region and optional extension." }, "given_name": { "type": "string", "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." }, "family_name": { "type": "string", "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." }, "company_name": { "type": "string", "description": "The company name of the recipient." } }, "description": "Contact represents generic contact information.", "required": [ "address" ] }, "v1alphadeliveryDelivery": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of a delivery." }, "line_items": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/deliveryLineItem" }, "description": "The goods that are to be delivered." }, "fulfillments": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/deliveryFulfillment" }, "description": "The available fulfillments for the delivery.\nIn the future this will be deprecated in favour of `nodes`." }, "recipient_contact": { "$ref": "#/definitions/v1alphadeliveryContact", "description": "The recipient's contact information." }, "attributes": { "type": "array", "items": { "type": "string" }, "description": "Used to control the behaviour of the filter/price rules.\nEquivalent of cart_attributes in the `Delivery Checkout` API." }, "delivery_categories": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/deliveryDeliveryCategory" }, "description": "The available delivery categories for this delivery.", "readOnly": true }, "tos_id": { "type": "string", "description": "ID of the TOS, only present for the session `complete` and `get` calls.", "readOnly": true }, "external_id": { "type": "string", "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.", "readOnly": true }, "nodes": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/deliveryDeliveryNode" }, "description": "List of nodes that take part in the 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.", "required": [ "id", "line_items", "fulfillments", "recipient_contact" ] } }, "securityDefinitions": { "Authorization": { "type": "apiKey", "name": "authorization", "in": "header" } }, "security": [ { "Authorization": [] } ] }