{ "consumes": [ "application/json" ], "produces": [ "application/json" ], "schemes": [ "https" ], "swagger": "2.0", "info": { "title": "delivery_checkout API", "version": "1.0" }, "basePath": "/v1/delivery_checkout", "paths": { "/session.complete": { "post": { "security": [ { "Bearer": [] } ], "description": "This request will also result in completing order in TOS.", "summary": "When the customer completes the purchase you also need to complete the\nsession. At this point you will have to supply us with the address and\nthe contact details of the user.", "operationId": "DeliveryCheckout_CompleteSession", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/CompleteSessionRequest" } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/CompleteSessionResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Status" } } } } }, "/session.create": { "post": { "security": [ { "Bearer": [] } ], "description": "The API will return a representation of the newly created session. The\nresponse will contain a session id which you can use to update and\nretrieve the session data.\n\nThe response will also contain a snippet of HTML with all the necessary code for\nbootstrapping the Ingrid widget. Simple render the HTML snippet on your checkout page.", "summary": "To add the Ingrid widget to the checkout page you will need to create a\nnew session. This can be done by this call. When doing this you will need\nto provide some required information.", "operationId": "DeliveryCheckout_CreateSession", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/CreateSessionRequest" } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/CreateSessionResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Status" } } } } }, "/session.get": { "get": { "security": [ { "Bearer": [] } ], "summary": "Fetches a session by ID. Can be used for loading a previously\ncreated session that have been stored together with a customer's\nshopping cart from a previous visit. It can contain obsolete data.\nTo get the session with the freshest data, use /session.pull endpoint.", "operationId": "DeliveryCheckout_GetSession", "parameters": [ { "type": "string", "description": "Checkout session id.", "name": "checkout_session_id", "in": "query", "required": true } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/GetSessionResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Status" } } } } }, "/session.pull": { "get": { "security": [ { "Bearer": [] } ], "summary": "Pulls a session by ID. Can be used for loading a previously\ncreated session that have been stored together with a customer's\nshopping cart from a previous visit. Session will be refreshed if its in active state and if\nconfiguration has changed or delivery promise expires.", "operationId": "DeliveryCheckout_PullSession", "parameters": [ { "type": "string", "description": "Checkout session id.", "name": "checkout_session_id", "in": "query", "required": true } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/GetSessionResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Status" } } } } }, "/session.update": { "post": { "security": [ { "Bearer": [] } ], "summary": "Update the session with new information. Useful for cases where the\ncustomer or cart information is changed. The later being the most\ncommon case.", "operationId": "DeliveryCheckout_UpdateSession", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/UpdateSessionRequest" } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/UpdateSessionResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Status" } } } } }, "/sessions_summaries.list": { "get": { "security": [ { "Bearer": [] } ], "summary": "Allows the merchant to get shipping data (session IDs and result fields) associated with tos ID.", "operationId": "DeliveryCheckout_ListSessionsSummaries", "parameters": [ { "type": "string", "name": "tos_id", "in": "query" } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/ListSessionsSummariesResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Status" } } } } } }, "definitions": { "AdditionalInfo": { "description": "Additional meta information related to the session.", "type": "object", "properties": { "courier_instructions": { "type": "string", "title": "Courier instruction provided by the customer [optional]" }, "customer_number": { "type": "string", "title": "Optional customer number provided by the user. Sometimes required by specific\nshipping products. For example DHL lockers in Germany [optional]" }, "door_code": { "type": "string", "title": "Entrance door code provided by the customer that can be used by the courier to get in [optional]" } } }, "Address": { "description": "Common address entity that used almost everywhere in Ingrid's API.", "type": "object", "properties": { "address_lines": { "type": "array", "title": "List of address lines part of address such as street and building number", "items": { "type": "string" } }, "apartment_number": { "description": "Number of the apartment.", "type": "string" }, "attn": { "type": "string", "title": "Attention field. Can be used to indicate an employee if the address is a\ncompany address [optional]" }, "building_name": { "type": "string", "title": "in the UK some buildings do not have a number, only a name" }, "care_of": { "type": "string", "title": "Care of part of address usually written as `c/o` [optional]" }, "city": { "type": "string", "title": "Name of the city" }, "coordinates": { "description": "Geolocation coordinates of the address. If reverse geolocation lookup of the\naddress was successful this property will be populated. If coordinates are\navailable they will be used to in service point search. In case of\n`search_address` coordinates can also be set by merchant if known.", "$ref": "#/definitions/Coordinates" }, "country": { "description": "Country should be specified as two uppercase letters (ISO Alpha-2).\nExample `SE` for Sweden, `ES` for Spain.", "type": "string" }, "door_code": { "type": "string", "title": "The door code to the main entrance of the building if applicable [optional]" }, "floor_number": { "type": "string", "title": "Floor number [optional]" }, "name": { "type": "string", "title": "Customer or company name" }, "po_box_id": { "type": "string", "title": "ID of the PO Box [optional]" }, "postal_code": { "type": "string", "title": "Postal code (or zipcode in US)" }, "region": { "type": "string", "title": "Region can be a state or a province [optional]" }, "street": { "description": "Name of the street.", "type": "string" }, "street_number": { "description": "Number of the street.", "type": "string" }, "subregion": { "type": "string", "title": "Further division of regions. Example countries are GB, IE, IT, LT, MX\nFor example for The Republic Of Ireland there are 4 provinces (regions),\ne.g. `Connacht` and 26 counties (subregions), e.g. `Galway`\nFormat is ISO 3166 where applicable, exceptions are e.g. Mexico [optional]" } } }, "Addresses": { "description": "All address information related to one delivery group.", "type": "object", "properties": { "billing_address": { "description": "Billing information to be sent to the payment provider.", "$ref": "#/definitions/BillingAddress" }, "customer": { "description": "Customer information received from the merchant.", "$ref": "#/definitions/CustomerAddress" }, "delivery_address": { "description": "Information about delivery address of recipient of the shipment.", "$ref": "#/definitions/DeliveryAddress" }, "location": { "description": "Pickup location if delivery type is `pickup` or `instore`.", "$ref": "#/definitions/PickupLocation" }, "search_address": { "description": "Search Address when not in the address form flow.", "$ref": "#/definitions/SearchAddress" } } }, "Any": { "type": "object", "properties": { "@type": { "type": "string" } }, "additionalProperties": {} }, "BillingAddress": { "type": "object", "properties": { "address_lines": { "type": "array", "items": { "type": "string" } }, "apartment_number": { "description": "Number of the apartment.", "type": "string" }, "attn": { "type": "string", "title": "Attention field. Can be used to indicate an employee if the address is a\ncompany address [optional]" }, "care_of": { "type": "string", "title": "Care of part of address usually written as `c/o` [optional]" }, "city": { "type": "string", "title": "Name of the city" }, "company_name": { "type": "string", "title": "The name of the company [optional]" }, "country": { "description": "Country should be specified as two uppercase letters (ISO Alpha-2).\nExample `SE` for Sweden, `ES` for Spain.", "type": "string" }, "customs_number": { "type": "string", "title": "identification number used for customs clearance purposes" }, "email": { "description": "Email address of the recipient.", "type": "string" }, "external_id": { "type": "string", "title": "Unique address identifier" }, "first_name": { "type": "string", "title": "The first name of the recipient" }, "last_name": { "type": "string", "title": "The last name of the recipient" }, "phone": { "description": "Phone number of the recipient.", "type": "string" }, "phone_country": { "description": "Phone number country of the recipient [optional]\nExample `SE` for Sweden, `ES` for Spain.", "type": "string" }, "po_box_id": { "type": "string", "title": "ID of the PO Box [optional]" }, "postal_code": { "type": "string", "title": "Postal code (or zipcode in US)" }, "region": { "type": "string", "title": "Region can be a state or a province [optional]" }, "street": { "description": "Name of the street.", "type": "string" }, "street_number": { "description": "Number of the street.", "type": "string" }, "vat": { "type": "string", "title": "Value Added Tax identifier [optional]" }, "vat_type": { "type": "string", "title": "Type of the VAT number [optional]" } } }, "CarrierAddon": { "type": "object", "title": "Carrier specific addons", "properties": { "code": { "description": "Identifier of the addon in carrier's system.", "type": "string" }, "description": { "type": "string", "title": "Description of the addon's functionality" }, "name": { "description": "Internal identifier of an addon.", "type": "string" } } }, "Cart": { "description": "Cart information from the e-commerce store. Information in here is used by the shipping rule engine\nto calculate the best shipping option for the customer.", "type": "object", "required": [ "total_value", "items", "cart_id", "total_discount" ], "properties": { "attributes": { "description": "Attributes of the Cart. Cart level attributes are specific to the cart or for the full cart contents.\nIngrid Delivery Checkout can set varied delivery scenarios based on such attributes. Ex. [“PRIO”, “AB-testID”].", "type": "array", "items": { "type": "string" } }, "cart_id": { "description": "Unique cart id or unique hashed cart id for the customers cart on the merchant side.", "type": "string" }, "groups": { "type": "array", "title": "Specification of groups to which the cart items should be assigned.[optional]", "items": { "type": "object", "$ref": "#/definitions/CartGroup" } }, "items": { "description": "Information about the individual order items. This can be used by the shipping\nrule engine to calculate the best shipping option.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/CartItem" } }, "pre_order": { "description": "Indicated if the order can be shipped earliest on the provided shipping date.", "type": "boolean" }, "shipping_date": { "description": "Date the order is expected to be dispatched from the warehouse. For orders containing\nout of stock items or items available for pre-order only. Multiple shipping dates with appropriate tags\ncan be specified inside internal field `category_tags`. It applies to all cart items.\nIf this property is not set Ingrid defaults to today's date.", "$ref": "#/definitions/ShippingDate" }, "total_discount": { "description": "Total non-negative discount amount in cents. Example `2000` is `20.00`.", "type": "integer", "format": "int32" }, "total_value": { "description": "Total non-negative cart value in cents after discounts applying. Example `20000` represents `200.00`.", "type": "integer", "format": "int32" }, "vouchers": { "description": "Vouchers that can be used in price/filter rules.", "type": "array", "items": { "type": "string" } } } }, "CartGroup": { "description": "Optional specification of group to which the cart items should be assigned.", "type": "object", "required": [ "group_id", "contents" ], "properties": { "attributes": { "description": "Attributes list of a single delivery group.\nUsed to control the behaviour of the `cart_attributes()` filter rule for each group individually.", "type": "array", "items": { "type": "string" } }, "cart_item_sku_list": { "description": "Deprecated: use contents instead.\nList of cart item SKUs (unique product identifiers) that belong to the given group.\nSKUs in the list must match the ones provided on cart items [deprecated].", "type": "array", "items": { "type": "string" } }, "consolidatable": { "description": "Indicates, that the group could be consolidated (merged into single group with other consolidatable groups).", "type": "boolean" }, "contents": { "type": "array", "title": "List of cart item splits by each group.\nFor example: Different sku quantities can be split between groups(orders)", "items": { "type": "object", "$ref": "#/definitions/GroupContent" } }, "group_id": { "description": "Unique identifier of group passed when doing split of shipments.", "type": "string" }, "header": { "description": "Header text containing arbitrary information related to the group.", "type": "string" }, "origins": { "description": "From where the contents of that delivery group can be sent from.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/Origin" } } } }, "CartItem": { "type": "object", "title": "Product in the shopping cart", "required": [ "sku", "name", "quantity", "price" ], "properties": { "attributes": { "description": "Attributes of Cart items. Often referred to as ‘tags’.\nCart Item level attributes are specific to that particular item and can be set to adjust delivery scenarios in Ingrid Delivery Checkout.\nA typical scenario is disabling of one or many delivery options based on cart containing cart items with certain attributes.\nEx. [“SendAsLetter”, “Prescription”, “Hazmat”].", "type": "array", "items": { "type": "string" } }, "dimensions": { "description": "Dimensions of this cart item. Can be used by the shipping rule engine to\ncalculate the best shipping option.", "$ref": "#/definitions/Dimensions" }, "discount": { "description": "Non-negative discount for the given item. Can be used by the shipping rule engine to calculate the best shipping option.", "type": "integer", "format": "int32" }, "image_url": { "description": "URL of the image of the given cart item.", "type": "string" }, "name": { "description": "Product name or title.", "type": "string" }, "out_of_stock": { "description": "Flag indicating if the item is currently out of stock.", "type": "boolean" }, "price": { "description": "Non-negative price of the item after the discount applied. Can be used by the shipping rule engine to calculate the best shipping option.", "type": "integer", "format": "int32" }, "quantity": { "description": "Total number of the product item in the cart.", "type": "integer", "format": "int32" }, "shipping_date": { "description": "Date the item is expected to be dispatched from the warehouse. For orders containing out of stock items or items available for pre-order only.\nMultiple shipping dates with appropriate tags can be specified inside internal field `category_tags`.\nIf used, it overrides shipping date of a single item, remaining items have shipping date cascaded from `cart.shipping_date`.", "$ref": "#/definitions/ShippingDate" }, "site_external_id": { "description": "Site external ID can be used in case of marketplace configuration.\nIf sent empty, top level site will be used.", "type": "string" }, "sku": { "description": "Unique product identifier.", "type": "string" }, "weight": { "description": "Weight of the item in grams. Can be used by the shipping rule engine to calculate the best shipping option.\nExample `1000` is 1 kg and `10` is 0,01 kg.", "type": "integer", "format": "int32" } } }, "CompleteSessionRequest": { "type": "object", "required": [ "checkout_session_id" ], "properties": { "checkout_session_id": { "description": "Checkout session id.", "type": "string" }, "customer": { "description": "Information about the customer such as name, email, phone and address. This information is required\nwhen completing a session. The address information is used as recipient address information\nto correctly calculate the correct shipping option.", "$ref": "#/definitions/CustomerAddress" }, "external_id": { "type": "string", "title": "Connects the session with an order on the merchant side.\nCan be used for troubleshooting and debugging. It has to be provided before the session is completed.[optional]" } } }, "CompleteSessionResponse": { "type": "object", "properties": { "session": { "title": "Final session state", "$ref": "#/definitions/Session" } } }, "ConsentLevel": { "description": " - UNSPECIFIED: No consent given, no data collection allowed.\n - STATISTICAL: Statistical consent given, data can be collected for statistical purposes only.\n - PERSONALIZATION: Personalization consent given, data can be collected for personalization purposes.", "type": "string", "default": "UNSPECIFIED", "enum": [ "UNSPECIFIED", "STATISTICAL", "PERSONALIZATION" ] }, "Coordinates": { "type": "object", "title": "Geolocation coordinates", "properties": { "lat": { "type": "number", "format": "double", "title": "Latitude" }, "lng": { "type": "number", "format": "double", "title": "Longitude" } } }, "CreateSessionRequest": { "type": "object", "required": [ "purchase_country", "purchase_currency", "cart", "locales" ], "properties": { "additional_information": { "description": "Additional information associated with the current session such as door code and delivery notes to courier.", "$ref": "#/definitions/AdditionalInfo" }, "cart": { "description": "Cart details as items, their weight, dimensions, attributes, quantities as well as\nshipping date, cart total value and currency.", "$ref": "#/definitions/Cart" }, "consent_level": { "description": "Consent level for the session. This is used to determine what data can be collected and how it can be used.", "$ref": "#/definitions/ConsentLevel" }, "external_id": { "type": "string", "title": "Connects the session with an order on the merchant side.\nCan be used for troubleshooting and debugging. It has to be provided before the session is completed.[optional]" }, "locales": { "description": "List of locales to load the shipping selector widget in, in order of preference (first supported one will be used).", "type": "array", "items": { "type": "string" } }, "meta": { "description": "Generic key/value object that is used for supplying complementing information.", "type": "object", "additionalProperties": { "type": "string" } }, "origins": { "description": "List of origins that can fulfill given cart.\nLimited to a single origin if you're interested in multiple origins contact support.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/Origin" } }, "prefill_delivery_address": { "description": "Prefill Delivery Address be used to prepopulate address form.", "$ref": "#/definitions/DeliveryAddress" }, "purchase_country": { "description": "The country of the purchase. Example SE.", "type": "string" }, "purchase_currency": { "description": "The currency of the purchase. Example SEK.", "type": "string" }, "search_address": { "description": "Lookup address for generating delivery options. Could be any address such as (office address)\nif customer e.g. want to pickup their delivery package close to his/her work place.\nMinimum required field is country and postal code.", "$ref": "#/definitions/Address" } } }, "CreateSessionResponse": { "type": "object", "properties": { "html_snippet": { "type": "string", "title": "HTML snippet to be included on the page" }, "session": { "title": "Session object", "$ref": "#/definitions/Session" }, "token": { "description": "Token generated for this session.", "type": "string" } } }, "CustomerAddress": { "type": "object", "properties": { "address_lines": { "type": "array", "title": "List of address lines part of address such as street and building number", "items": { "type": "string" } }, "apartment_number": { "description": "Number of the apartment.", "type": "string" }, "attn": { "type": "string", "title": "Attention field. Can be used to indicate an employee if the address is a\ncompany address [optional]" }, "care_of": { "type": "string", "title": "Care of part of address usually written as `c/o` [optional]" }, "city": { "type": "string", "title": "Name of the city" }, "coordinates": { "description": "Geolocation coordinates of the address. If reverse geolocation lookup of the\naddress was successful this property will be populated. If coordinates are\navailable they will be used to in service point search. In case of\n`search_address` coordinates can also be set by merchant if known.", "$ref": "#/definitions/Coordinates" }, "country": { "description": "Country should be specified as two uppercase letters (ISO Alpha-2).\nExample `SE` for Sweden, `ES` for Spain.", "type": "string" }, "customs_number": { "type": "string", "title": "identification number used for customs clearance purposes" }, "door_code": { "type": "string", "title": "The door code to the main entrance of the building if applicable [optional]" }, "email": { "description": "Email address of the customer.", "type": "string" }, "name": { "type": "string", "title": "The name of the customer" }, "phone": { "description": "Phone number of the customer.", "type": "string" }, "postal_code": { "type": "string", "title": "Postal code (or zipcode in US)" }, "region": { "type": "string", "title": "Region can be a state or a province [optional]" }, "street": { "description": "Name of the street.", "type": "string" }, "street_number": { "description": "Number of the street.", "type": "string" } } }, "DateTimeRange": { "description": "Provides a date interval. Depending on a case, `start` and `end` parts are not guaranteed to be present.", "type": "object", "properties": { "end": { "description": "End of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31Z`.", "type": "string" }, "start": { "type": "string", "title": "Start of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31Z`" } } }, "DeliveryAddress": { "type": "object", "properties": { "address_lines": { "type": "array", "title": "List of address lines part of address such as street and building number", "items": { "type": "string" } }, "apartment_number": { "description": "Number of the apartment.", "type": "string" }, "attn": { "type": "string", "title": "Attention field. Can be used to indicate an employee if the address is a\ncompany address [optional]" }, "care_of": { "type": "string", "title": "Care of part of address usually written as `c/o` [optional]" }, "city": { "type": "string", "title": "Name of the city" }, "company_name": { "type": "string", "title": "The name of the company [optional]" }, "coordinates": { "description": "Geolocation coordinates of the address. If reverse geolocation lookup of the\naddress was successful this property will be populated. If coordinates are\navailable they will be used to in service point search. In case of\n`search_address` coordinates can also be set by merchant if known.", "$ref": "#/definitions/Coordinates" }, "country": { "description": "Country should be specified as two uppercase letters (ISO Alpha-2).\nExample `SE` for Sweden, `ES` for Spain.", "type": "string" }, "customs_number": { "type": "string", "title": "identification number used for customs clearance purposes" }, "door_code": { "type": "string", "title": "The door code to the main entrance of the building if applicable [optional]" }, "email": { "description": "Email address of the recipient.", "type": "string" }, "external_id": { "type": "string", "title": "Unique address identifier" }, "first_name": { "type": "string", "title": "The first name of the recipient" }, "last_name": { "type": "string", "title": "The last name of the recipient" }, "phone": { "description": "Phone number of the recipient.", "type": "string" }, "phone_country": { "description": "Phone number country of the recipient [optional]\nExample `SE` for Sweden, `ES` for Spain.", "type": "string" }, "po_box_id": { "type": "string", "title": "ID of the PO Box [optional]" }, "postal_code": { "type": "string", "title": "Postal code (or zipcode in US)" }, "region": { "type": "string", "title": "Region can be a state or a province [optional]" }, "street": { "description": "Name of the street.", "type": "string" }, "street_number": { "description": "Number of the street.", "type": "string" } } }, "DeliveryGroup": { "description": "Summary of the order.", "type": "object", "properties": { "addresses": { "title": "All important addresses in a single place", "$ref": "#/definitions/Addresses" }, "category": { "description": "Details about the selected Delivery Category for this Delivery Promise.", "$ref": "#/definitions/DeliveryGroupCategory" }, "delivery_time": { "description": "Details the Delivery time aspects of the Delivery promise given in Delivery Checkout.", "$ref": "#/definitions/DeliveryGroupDeliveryTime" }, "external_id": { "type": "string", "title": "Connects the delivery group with an order on the merchant\nside. Can be used for troubleshooting and debugging.[optional]" }, "group_id": { "description": "Identifier of delivery group used to perform splitting of shipments.", "type": "string" }, "header": { "description": "Header text containing arbitrary information related to the delivery group.", "type": "string" }, "items": { "description": "Cart items that belong to the delivery group.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/DeliveryGroupItem" } }, "pricing": { "description": "Pricing information for selected Delivery Promise with currency details.", "$ref": "#/definitions/DeliveryGroupPricing" }, "selection": { "description": "Defines how selected Delivery Promise was obtained.", "$ref": "#/definitions/DeliveryGroupSelection" }, "shipping": { "description": "Details about the delivery promise given in a Checkout session, such as specifications of the selected Carrier, Pickup Location information, Routing and Integration mapping IDs.", "$ref": "#/definitions/DeliveryGroupShipping" }, "tos_id": { "description": "Identifier of order created based on completed session. By default, orders are created asynchronously\nso the identifier might need to be re-fetched.", "type": "string" } } }, "DeliveryGroupCategory": { "description": "The Delivery Category selected by the User.", "type": "object", "properties": { "base_price": { "description": "Base price of the carrier product for the given Delivery Promise.", "type": "integer", "format": "int32" }, "custom_text": { "description": "User-defined custom text displayed near the category in shipping selector widget.", "type": "string" }, "custom_warning_text": { "description": "User-defined custom warning text displayed near the category in shipping selector widget, that indicates e.g. edge cases related to the given category.", "type": "string" }, "external_id": { "type": "string", "title": "External ID that can be used to map to merchant specific ids. Can be set in configuration.[optional]" }, "id": { "description": "The Ingrid internal ID of the category.", "type": "string" }, "name": { "description": "Default category name. This admin name of the delivery category. This would be shown to end user if there are no translations set for the category.", "type": "string" }, "presented_category_name": { "description": "The name of the category that was actually presented to the end user.", "type": "string" }, "tags": { "description": "The category tags set in Ingrid Merchant Platform for that specific Delivery Category.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/Tag" } } } }, "DeliveryGroupDeliveryAddon": { "description": "Specifies a single selected addon.", "type": "object", "properties": { "external_addon_id": { "type": "string" }, "id": { "type": "string" } } }, "DeliveryGroupDeliveryTime": { "description": "Listing of Delivery Time Components produced by the Ingrid Delivery Checkout.", "type": "object", "properties": { "carrier_delivery_promise": { "description": "The Date \u0026 Time response returned by Ingrid Carrier integrations that specify when carriers say they could deliver the parcel. This notion could differ from customer_delivery_promise since a carrier could have deliveries on eg. Saturdays but a user has configured Ingrid Delivery Checkout to communicate only business days. For such situation, Ingrid would move the customer_delivery_promise to the next possible business day.", "$ref": "#/definitions/DeliveryGroupDeliveryTimeRange" }, "customer_delivery_promise": { "description": "The date \u0026 time used to present the delivery time promise to the end user. (When time is set to 00:00 it means Ingrid has presented a set of days or business days e.g. 2-3 Business days).", "$ref": "#/definitions/DeliveryGroupDeliveryTimeRange" }, "pickup_from_merchant": { "description": "The date \u0026 time when the parcel is understood by Ingrid Delivery Checkout and is possible to collect from Merchant Warehouse or Store.", "$ref": "#/definitions/DeliveryGroupDeliveryTimeRange" } } }, "DeliveryGroupDeliveryTimeRange": { "type": "object", "properties": { "earliest": { "type": "string" }, "latest": { "type": "string" } } }, "DeliveryGroupItem": { "description": "Item that belongs to a delivery group.", "type": "object", "properties": { "quantity": { "type": "integer", "format": "int32", "title": "Quantity of cart item" }, "shipping_date": { "description": "Shipping date set for the item.", "$ref": "#/definitions/ShippingDate" }, "site_external_id": { "description": "Site external ID can be used in case of marketplace configuration to split items by marketplace merchant.\nIf sent empty, top level site will be used.", "type": "string" }, "sku": { "description": "Unique cart item's product identifier.", "type": "string" } } }, "DeliveryGroupPricing": { "description": "The price of the delivery promise from Ingrid Delivery Checkout. Given as a total or divided into it is components for cases such as separating eg. Delivery Addons selected by the user during checkout.", "type": "object", "properties": { "currency": { "description": "Session's currency. Example `SEK`.", "type": "string" }, "net_price": { "type": "integer", "format": "int32", "title": "Net price of the delivery option. Unit are cents [optional]" }, "price": { "description": "Price in cents. Example `20000` represents `200.00`.", "type": "integer", "format": "int32" }, "price_components": { "description": "Components which make up the price.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/PriceComponent" } } } }, "DeliveryGroupSelection": { "description": "Specifies how selection of Delivery Promise was obtained.\n\n - DELIVERY_GROUP_SELECTION_UNDEFINED: Delivery Checkout failed to compute the selection reason for the delivery option use.\n - USER_CHOICE: Delivery option selection was done by the end user.\n - PRESELECTED_CHOICE: The preselected delivery option was used for selection. End user did not change delivery option from what was preselected.\n - FALLBACK_FROM_USER_CHOICE: The user choice could not be respected when completing the session. Eg. due to carrier not covering the delivery address used for completing the session.\n - FALLBACK_FROM_PRESELECTED_CHOICE: The preselected choice could not be respected when completing the session. Eg. due to carrier not covering the delivery address used for completing the session.\n - FALLBACK_FAILED_FOR_USER_CHOICE: Selection was made based on user choice and fallback failing.\n - FALLBACK_FAILED_FOR_PRESELECTED_CHOICE: Selection was made based on preselected choice and fallback failing.", "type": "string", "default": "DELIVERY_GROUP_SELECTION_UNDEFINED", "enum": [ "DELIVERY_GROUP_SELECTION_UNDEFINED", "USER_CHOICE", "PRESELECTED_CHOICE", "FALLBACK_FROM_USER_CHOICE", "FALLBACK_FROM_PRESELECTED_CHOICE", "FALLBACK_FAILED_FOR_USER_CHOICE", "FALLBACK_FAILED_FOR_PRESELECTED_CHOICE" ] }, "DeliveryGroupShipping": { "description": "How the package should be shipped to the end customer.", "type": "object", "properties": { "addons": { "description": "Shipping products addons that are enabled by default. Can be configured in the Merchant Admin tool.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/CarrierAddon" } }, "carrier": { "description": "Name of the shipping company.", "type": "string" }, "carrier_product_id": { "description": "Identifier of chosen carrier product, can be used for merchant-specific shipping methods mappings.\nIf external method identifier is defined on carrier product, its value is passed in this field. Otherwise, shipping method from carrier product is passed.", "type": "string" }, "delivery_addons": { "description": "Selected delivery addons.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/DeliveryGroupDeliveryAddon" } }, "delivery_type": { "description": "Type of delivery (pickup, instore, mailbox, delivery).", "type": "string" }, "external_method_id": { "description": "External method identifier, can be used for merchant-specific shipping methods mappings, eg override.", "type": "string" }, "meta": { "description": "Carrier specific metadata related to the shipping option, for example addons.", "type": "object", "additionalProperties": { "type": "string" } }, "product": { "description": "Name of the shipping product.", "type": "string" }, "route": { "description": "Delivery steps.", "$ref": "#/definitions/Route" }, "shipping_method": { "description": "Ingrid's ID of the shipping product. Example `bst-std` for BEST Delivery.", "type": "string" }, "supports": { "description": "Contains information about the features a shipping option should support.", "$ref": "#/definitions/Supports" }, "warehouse": { "description": "Address of the warehouse from which the package will be shipped.", "$ref": "#/definitions/DeliveryGroupWarehouse" } } }, "DeliveryGroupWarehouse": { "description": "Contains information about warehouse.", "type": "object", "properties": { "address": { "$ref": "#/definitions/DeliveryAddress" }, "external_id": { "type": "string" } } }, "Dimensions": { "description": "Dimensions of an item in millimeters.", "type": "object", "properties": { "height": { "description": "Height of the item in millimeters.", "type": "integer", "format": "int32" }, "length": { "description": "Length of the item in millimeters.", "type": "integer", "format": "int32" }, "width": { "description": "Width of the item in millimeters.", "type": "integer", "format": "int32" } } }, "Distance": { "description": "Walking and driving distance information (if available). This depends if we\ncould reverse geolocate supplied address and succeeded in finding a nearest\nroute from A to B. Usually only available for distance information between\naddress provided by the customer and service point address.", "type": "object", "properties": { "driving": { "title": "Driving distance in minutes", "$ref": "#/definitions/DistanceSpec" }, "walking": { "title": "Walking distance in meters", "$ref": "#/definitions/DistanceSpec" } } }, "DistanceSpec": { "description": "Generic distance object used by Distance object to provide driving and walking information.", "type": "object", "properties": { "duration": { "type": "integer", "format": "int32", "title": "Approximate duration in minutes" }, "value": { "type": "integer", "format": "int32", "title": "Approximate distance in meters" } } }, "GetSessionResponse": { "type": "object", "properties": { "html_snippet": { "type": "string", "title": "HTML snippet to be included on the page" }, "session": { "title": "Session object", "$ref": "#/definitions/Session" } } }, "GroupContent": { "type": "object", "properties": { "quantity": { "type": "integer", "format": "int32" }, "sku": { "type": "string" } } }, "LegLocation": { "description": "LegLocation represents a location that takes part in a delivery.", "type": "object", "properties": { "address": { "description": "Address of a location.\nThis is optional when LocationType is LOCATION_TYPE_WAREHOUSE or LOCATION_TYPE_HOME,\nsince these values can be obtained from the session.", "$ref": "#/definitions/Address" }, "external_id": { "type": "string", "title": "Possibility to set an external id for this location. Usually service point\nid or merchant store id" }, "location_type": { "description": "Location type.", "$ref": "#/definitions/LegLocationLocationType" } } }, "LegLocationLocationType": { "description": "LocationType represents a type of a location that takes part in a delivery.", "type": "string", "default": "LOCATION_TYPE_UNKNOWN", "enum": [ "LOCATION_TYPE_UNKNOWN", "LOCATION_TYPE_WAREHOUSE", "LOCATION_TYPE_STORE", "LOCATION_TYPE_HOME", "LOCATION_TYPE_PICKUP" ] }, "ListSessionsSummariesResponse": { "description": "Contains the list of session IDs with result fields.", "type": "object", "properties": { "external_id": { "type": "string" }, "purchase_country": { "type": "string" }, "result": { "$ref": "#/definitions/SessionSummary" }, "tos_id": { "type": "string" } } }, "OperationalHours": { "type": "object", "title": "Service points's operational hours", "properties": { "free_text": { "type": "array", "title": "Free text operational hours. Used as a fallback when the\noperational hours cannot be parsed correctly", "items": { "type": "string" } }, "fri": { "type": "string", "title": "Friday" }, "mon": { "type": "string", "title": "Monday" }, "sat": { "type": "string", "title": "Saturday" }, "sun": { "type": "string", "title": "Sunday" }, "thu": { "type": "string", "title": "Thursday" }, "tue": { "type": "string", "title": "Tuesday" }, "wed": { "type": "string", "title": "Wednesday" } } }, "Origin": { "description": "Where the goods will be delivered from.", "type": "object", "required": [ "external_id" ], "properties": { "address": { "description": "Physical location of the given origin.", "$ref": "#/definitions/OriginAddress" }, "external_id": { "description": "External reference of the given origin.", "type": "string" }, "handoff": { "description": "Time range when the given origin is ready for hand-off.\nOverwrites shipping date related calculations.", "$ref": "#/definitions/OriginHandoff" } } }, "OriginAddress": { "description": "Physical location of the given origin.", "type": "object", "required": [ "country" ], "properties": { "address_lines": { "type": "array", "title": "List of address lines part of address such as street and building number", "items": { "type": "string" } }, "building_name": { "description": "For buildings that do not have a number, only a name.", "type": "string" }, "city": { "type": "string", "title": "Name of the city" }, "coordinates": { "description": "Geolocation coordinates of the address.", "$ref": "#/definitions/Coordinates" }, "country": { "description": "Country should be specified as two uppercase letters (ISO Alpha-2).\nExample `SE` for Sweden, `ES` for Spain.", "type": "string" }, "name": { "type": "string", "title": "Customer or company name" }, "postal_code": { "description": "Postal code (or zipcode in US).", "type": "string" }, "region": { "description": "Region can be a state or a province.", "type": "string" }, "street": { "description": "Name of the street.", "type": "string" }, "street_number": { "description": "Number of the street.", "type": "string" }, "subregion": { "type": "string", "title": "Further division of regions. Example countries are GB, IE, IT, LT, MX\nFor example for The Republic Of Ireland there are 4 provinces (regions),\ne.g. `Connacht` and 26 counties (subregions), e.g. `Galway`\nFormat is ISO 3166 where applicable, exceptions are e.g. Mexico [optional]" } } }, "OriginHandoff": { "description": "Time range when the given origin is ready for hand-off.", "type": "object", "required": [ "earliest", "latest" ], "properties": { "earliest": { "description": "Start of the interval. Date is returned in RFC3339 format.", "type": "string" }, "latest": { "description": "End of the interval. Date is returned in RFC3339 format.", "type": "string" } } }, "PickupLocation": { "description": "Contains information about the pickup service point as returned by the carrier.", "type": "object", "properties": { "address": { "title": "Visiting address of the service point", "$ref": "#/definitions/DeliveryAddress" }, "distance": { "description": "Distance between the service point location and customer's delivery address if available.", "$ref": "#/definitions/Distance" }, "external_id": { "description": "Carrier specific ID of the service point location returned by the carrier.", "type": "string" }, "location_type": { "title": "The type of pickup location. Can be `UNKNOWN_PICKUP_LOCATION_TYPE, LOCKER, STORE, POSTOFFICE, MANNED`", "$ref": "#/definitions/PickupLocationType" }, "meta": { "type": "object", "title": "Carrier specific metadata related to the pickup location [t:hash\u003cstring,string\u003e]", "additionalProperties": { "type": "string" } }, "name": { "type": "string", "title": "Name or title of the service point as returned by the carrier" }, "operational_hours": { "description": "Operation hours for the service point provided by the carrier if available.", "$ref": "#/definitions/OperationalHours" }, "sections": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/Section" } } } }, "PickupLocationType": { "description": "- UNKNOWN_PICKUP_LOCATION_TYPE: Location type is not known for some reason\n - LOCKER: Locker location type. Example Instabox or a DHL locker\n - STORE: Can be a merchant's store or any other store that handles logistics\n - POSTOFFICE: Postal office\n - MANNED: A manned service point", "type": "string", "title": "Indicates the kind of pickup location", "default": "UNKNOWN_PICKUP_LOCATION_TYPE", "enum": [ "UNKNOWN_PICKUP_LOCATION_TYPE", "LOCKER", "STORE", "POSTOFFICE", "MANNED" ] }, "PriceComponent": { "description": "Specifies a single price component.", "type": "object", "properties": { "id": { "type": "string" }, "type": { "title": "Indicates if the component is the cost of shipping or the one of an addon", "$ref": "#/definitions/PriceComponentType" }, "value": { "type": "integer", "format": "int32", "title": "Gross price" }, "vat": { "type": "integer", "format": "int32", "title": "Amount of tax [optional]" }, "vat_rate": { "type": "number", "format": "float", "title": "Tax rate of the delivery option [optional]" } } }, "PriceComponentType": { "type": "string", "default": "PRICE_COMPONENT_TYPE_UNDEFINED", "enum": [ "PRICE_COMPONENT_TYPE_UNDEFINED", "PRICE_COMPONENT_TYPE_SHIPPING", "PRICE_COMPONENT_TYPE_ADDON", "PRICE_COMPONENT_TYPE_RETURN" ] }, "Route": { "description": "Route represents a list of delivery steps.", "type": "object", "properties": { "shipping_legs": { "description": "ShippingLegs represent a list of delivery steps. For a non-chained delivery this will contain only one element.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/ShippingLeg" } } } }, "SearchAddress": { "type": "object", "properties": { "address_lines": { "type": "array", "title": "List of address lines part of address such as street and building number", "items": { "type": "string" } }, "apartment_number": { "description": "Number of the apartment.", "type": "string" }, "city": { "type": "string", "title": "Name of the city" }, "coordinates": { "description": "Geolocation coordinates of the address. If reverse geolocation lookup of the\naddress was successful this property will be populated. If coordinates are\navailable they will be used to in service point search. In case of\n`search_address` coordinates can also be set by merchant if known.", "$ref": "#/definitions/Coordinates" }, "country": { "description": "Country should be specified as two uppercase letters (ISO Alpha-2).\nExample `SE` for Sweden, `ES` for Spain.", "type": "string" }, "postal_code": { "type": "string", "title": "Postal code (or zipcode in US)" }, "region": { "type": "string", "title": "Region can be a state or a province [optional]" }, "street": { "description": "Name of the street.", "type": "string" }, "street_number": { "description": "Number of the street.", "type": "string" } } }, "Section": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/SectionColumnItem" } }, "name": { "type": "string" } } }, "SectionColumnItem": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/SectionItem" } } } }, "SectionItem": { "type": "object", "properties": { "icon": { "type": "string" }, "link": { "type": "string" }, "text": { "type": "string" } } }, "Session": { "type": "object", "title": "Contains information about the current session. Each session is unique for\nevery customer transaction", "properties": { "additional_information": { "description": "Additional meta information related to the session.", "$ref": "#/definitions/AdditionalInfo" }, "cart": { "description": "Checkout cart details as items, their weight, dimensions, attributes, quantities as well as\nshipping date, cart total value and currency.", "$ref": "#/definitions/Cart" }, "checkout_session_id": { "description": "Identifier of the session. Generated when session is created. Used\nfor updating, fetching and completing the session.", "type": "string" }, "consent_level": { "description": "Consent level for the session. This is used to determine what data can be collected and how it can be used.", "$ref": "#/definitions/ConsentLevel" }, "delivery_groups": { "description": "Delivery groups contain information about session results.\nInformation about order, selection and price can be found here.\nIf split shipment is disabled, delivery groups contain only one entry.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/DeliveryGroup" } }, "experiment_id": { "description": "Identifier of an A/B testing experiment, which is related to the session.\nIf the session is not related to any A/B testing experiment, this field is empty.", "type": "string" }, "origins": { "description": "List of origins that can fulfill given cart.\nLimited to a single origin if you're interested in multiple origins contact support.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/Origin" } }, "purchase_country": { "description": "The country of the purchase.", "type": "string" }, "status": { "title": "Current session status (ACTIVE, COMPLETE). You cannot reactivate a session\nafter it is completed [readonly]", "$ref": "#/definitions/SessionSessionStatus" }, "updated_at": { "description": "Datetime indicating when the session was last updated.", "type": "string" } } }, "SessionSessionStatus": { "type": "string", "default": "UNKNOWN", "enum": [ "UNKNOWN", "ACTIVE", "COMPLETE" ] }, "SessionSummary": { "type": "object", "properties": { "addresses": { "title": "All important addresses in a single place", "$ref": "#/definitions/Addresses" }, "category": { "description": "Details about the selected Delivery Category for this Delivery Promise.", "$ref": "#/definitions/DeliveryGroupCategory" }, "delivery_time": { "description": "Details the Delivery time aspects of the Delivery promise given in Delivery Checkout.", "$ref": "#/definitions/DeliveryGroupDeliveryTime" }, "pricing": { "description": "Pricing information for selected Delivery Promise with currency details.", "$ref": "#/definitions/DeliveryGroupPricing" }, "selection": { "description": "Defines how selected Delivery Promise was obtained.", "$ref": "#/definitions/DeliveryGroupSelection" }, "shipping": { "description": "Details about the delivery promise given in a Checkout session, such as specifications of the selected Carrier, Routing and Integration mapping IDs.", "$ref": "#/definitions/DeliveryGroupShipping" } } }, "ShippingDate": { "description": "Information about possible shipping dates.", "type": "object", "properties": { "category_tags": { "description": "Multiple shipping dates with appropriate tags.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/ShippingDateTag" } }, "end": { "description": "End of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31Z`.", "type": "string" }, "start": { "type": "string", "title": "Start of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31Z`" } } }, "ShippingDateTag": { "type": "object", "properties": { "name": { "description": "Name of the category tag.", "type": "string" }, "shipping_date": { "description": "Shipping date for the category tag.", "$ref": "#/definitions/DateTimeRange" } } }, "ShippingLeg": { "description": "ShippingLeg represents a single step of package delivery.", "type": "object", "properties": { "delivery_type": { "type": "string", "title": "Step's delivery type" }, "from": { "description": "Origin address. Can be warehouse or service point or merchant store address.", "$ref": "#/definitions/LegLocation" }, "shipping_method": { "type": "string", "title": "Shipping product used for this step" }, "to": { "description": "Destination address. Can be warehouse or service point or merchant store\naddress or customer's home address.", "$ref": "#/definitions/LegLocation" } } }, "Status": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "details": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/Any" } }, "message": { "type": "string" } } }, "Supports": { "description": "Contains information about features that a shipping option supports. Configurable in Merchant Admin tool.", "type": "object", "properties": { "courier_instructions": { "description": "Indicates if shipping option supports courier notes. If true, a courier\ninstructions input will be displayed in the shipping selector widget. Only\napplicable for home delivery type.", "type": "boolean" }, "customer_number": { "description": "Indicates if shipping option supports carrier specific customer number. If\ntrue, a carrier number input will be displayed in the shipping selector\nwidget. Only applicable for DHL Germany at this moment, where customer has\nto provide a number that identifies a pickup locker.", "type": "boolean" }, "door_code": { "description": "Indicates if shipping option supports door code. If true, a door code input\nwill be displayed in the shipping selector widget. Only applicable for home\ndelivery type.", "type": "boolean" }, "search": { "type": "boolean", "title": "Indicates if search should be enabled" } } }, "Tag": { "type": "object", "properties": { "name": { "type": "string" } } }, "UpdateSessionRequest": { "type": "object", "required": [ "checkout_session_id" ], "properties": { "cart": { "description": "Cart details as items, their weight, dimensions, attributes, quantities as well as\nshipping date, cart total value and currency.", "$ref": "#/definitions/Cart" }, "checkout_session_id": { "description": "Checkout session id.", "type": "string" }, "consent_level": { "description": "Consent level for the session. This is used to determine what data can be collected and how it can be used.", "$ref": "#/definitions/ConsentLevel" }, "external_id": { "type": "string", "title": "Connects the session with an order on the merchant side.\nCan be used for troubleshooting and debugging. It has to be provided before the session is completed.[optional]" }, "locales": { "description": "List of locales to load the shipping selector widget in, in order of preference (first supported one will be used).", "type": "array", "items": { "type": "string" } }, "meta": { "description": "Generic key/value object that is used for supplying complementing information.", "type": "object", "additionalProperties": { "type": "string" } }, "origins": { "description": "List of origins that can fulfill given cart.\nLimited to a single origin if you're interested in multiple origins contact support.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/Origin" } }, "prefill_delivery_address": { "description": "Prefill Delivery Address be used to prepopulate address form.", "$ref": "#/definitions/DeliveryAddress" }, "purchase_country": { "description": "The country of the purchase.", "type": "string" }, "purchase_currency": { "description": "The currency of the purchase.", "type": "string" }, "search_address": { "description": "Lookup address for generating delivery options. Could be any address such as (office address)\nif customer e.g. want to pickup their delivery package close to his/her work place.\nMinimum required field is country and postal code.", "$ref": "#/definitions/SearchAddress" } } }, "UpdateSessionResponse": { "type": "object", "properties": { "html_snippet": { "type": "string", "title": "HTML snippet to be included on the page" }, "session": { "title": "Session object", "$ref": "#/definitions/Session" } } } }, "securityDefinitions": { "Bearer": { "type": "apiKey", "name": "Authorization", "in": "header" } } }