swagger: "2.0" info: title: Delivery API description: API for managing sessions and delivery options version: v1 tags: - name: DeliveryService schemes: - https consumes: - application/json produces: - application/json paths: /v1/sessions: post: summary: Creates a new session. operationId: DeliveryService_CreateSession responses: "200": description: A successful response. schema: $ref: '#/definitions/v1alphaSession' 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/v1alphaSession' required: - session tags: - DeliveryService /v1/{name}: get: summary: Gets a session by resource name. operationId: DeliveryService_GetSession responses: "200": description: A successful response. schema: $ref: '#/definitions/v1alphaSession' default: description: An unexpected error response. schema: $ref: '#/definitions/rpcStatus' parameters: - name: name description: |- The resource name of the shipping session to retrieve. Format: sessions/{session_id} in: path required: true type: string pattern: sessions/[^/]+ tags: - DeliveryService /v1/{name}:complete: post: summary: Completes a session and saves the user choices. operationId: DeliveryService_CompleteSession responses: "200": description: A successful response. schema: $ref: '#/definitions/v1alphaCompleteSessionResponse' default: description: An unexpected error response. schema: $ref: '#/definitions/rpcStatus' parameters: - name: name description: |- The resource name of the shipping session to complete. Format: sessions/{session_id} in: path required: true type: string pattern: sessions/[^/]+ - name: body in: body required: true schema: $ref: '#/definitions/DeliveryServiceCompleteSessionBody' tags: - DeliveryService /v1/{session.name}: patch: summary: Updates a session. operationId: DeliveryService_UpdateSession responses: "200": description: A successful response. schema: $ref: '#/definitions/v1alphaSession' 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/v1alphaDelivery' 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. If an etag is provided and does not match the current etag of the session, updates and completion will be blocked and an ABORTED error will be returned. title: The session to update. required: - purchase - deliveries - session - name: update_mask description: |- The list of fields to update. Valid field masks: purchase,purchase.total_value,deliveries. in: query required: false type: string 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. - ADDON_TYPE_UNSPECIFIED: Addon type is unspecified or unknown. - CUSTOM: A custom addon specified by the carrier or merchant. - CARRY_IN: An addon for carrying the delivery item into the recipient's premises. - LEAVE_AT_DOOR: An addon for leaving the item at the door without requiring a signature. - UNWRAPPING: An addon for unwrapping the delivered item. ContactPhoneNumber: type: object properties: country_code: type: string description: |- The 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 DeliveryCategoryDeliveryType: type: string enum: - DELIVERY_TYPE_UNSPECIFIED - DELIVERY - PICKUP - MAILBOX - INSTORE default: DELIVERY_TYPE_UNSPECIFIED description: |- DeliveryType defines the method or mode of delivery. - DELIVERY_TYPE_UNSPECIFIED: Delivery type is unspecified or unknown. - DELIVERY: Delivery to a customer's home or address. - PICKUP: Delivery to a service point or locker. - MAILBOX: Delivery to a customer's mailbox. - INSTORE: Delivery to a merchant's store for in-store pickup. DeliveryCategoryOptionsSource: type: string enum: - OPTIONS_SOURCE_UNSPECIFIED - FALLBACK - CARRIER default: OPTIONS_SOURCE_UNSPECIFIED description: |- OptionsSource specifies the origin of the delivery options. - OPTIONS_SOURCE_UNSPECIFIED: Source of the options is unspecified. - FALLBACK: Delivery options come from a fallback configuration. - CARRIER: Delivery options are sourced directly from the carrier. DeliveryCategoryWarehouse: type: object properties: id: type: string description: Unique identifier of the warehouse. address: $ref: '#/definitions/v1alphaAddress' description: The address of the warehouse. description: |- Information about a warehouse. All this data is stored in the site configuration. required: - id - address 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 DeliveryServiceCompleteSessionBody: type: object properties: delivery_choices: type: array items: type: object $ref: '#/definitions/v1alphaDeliveryChoice' 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 tp 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. latest: type: integer format: int32 description: Maximum number of time units. If unspecified, there is no upper bound. 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. - TIME_UNIT_UNSPECIFIED: Default value. This value is unused. - TIME_UNIT_MINUTE: Minutes - TIME_UNIT_HOUR: Hours - TIME_UNIT_DAY: Calendar days - TIME_UNIT_BUSINESS_DAY: Business days (excluding weekends and holidays) - TIME_UNIT_WEEK: Calendar weeks - TIME_UNIT_MONTH: Calendar months 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. If 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 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 PickupLocationDistances: type: object properties: walking: $ref: '#/definitions/v1alphaDistance' description: The walking distance to the pickup location. driving: $ref: '#/definitions/v1alphaDistance' 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 default: LOCATION_TYPE_UNSPECIFIED description: |- LocationType defines the type of the pickup location. - LOCATION_TYPE_UNSPECIFIED: Unspecified type. - LOCKER: A locker pickup location. - STORE: A store pickup location. - POSTOFFICE: A post office pickup location. - MANNED: A manned pickup location, e.g., staffed desk. 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 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: |- The 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. Q(grigagod): shoud we stick to a main cart concept?. 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. - STATE_UNSPECIFIED: Default value. This value is unused. - ACTIVE: Session is active and can be modified. - COMPLETED: Session is completed and can not be modified. prepurchasev1alphaContact: type: object properties: address: $ref: '#/definitions/v1alphaAddress' 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. description: Contact represents generic contact information. required: - address 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' v1alphaAddon: type: object properties: display_name: type: string description: The display-friendly name of the addon, e.g., "Gift Wrapping", "Leave at Door". 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 description: An Addon represents an additional service or feature offered with a delivery. required: - display_name v1alphaAddress: type: object properties: country_code: type: string description: |- Refers to a ISO-3166 alpha 2 country code. region_code: type: string title: |- Refers to an ISO-3166-2 subdivision code without country_code prefix, e.g., `DC` for Washington DC. Except for countries like México, Hong Kong, etc. Example region for Honk Kong - `Kowloon` postal_code: 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/v1alphaCoordinates' description: Geolocation of the given address. street: type: string description: Refers to a street or route name. street_number: type: string description: Refers to a street number. description: Represents an address suitable for delivery. required: - country_code - address_lines v1alphaCompleteSessionResponse: type: object properties: session: $ref: '#/definitions/v1alphaSession' description: The completed session. description: Response message for completing a session. required: - session v1alphaCoordinates: 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. Unless specified otherwise, this must conform to the WGS84 standard. Values must be within normalized ranges. required: - lat - lng v1alphaDelivery: type: object properties: id: type: string description: The unique identifier of a delivery. line_items: type: array items: type: object $ref: '#/definitions/v1alphaLineItem' description: The goods that are to be delivered. fulfillments: type: array items: type: object $ref: '#/definitions/v1alphaFulfillment' description: The available fulfillments for the delivery. recipient_contact: $ref: '#/definitions/prepurchasev1alphaContact' description: The recipient's contact information. attributes: type: array items: type: string description: |- Used to control the behaviour of the filter/price rules. Equivalent of cart_attributes in the `Delivery Checkout` API. delivery_categories: type: array items: type: object $ref: '#/definitions/v1alphaDeliveryCategory' 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 description: |- The delivery represents a single delivery of goods to a recipient. It includes information about the goods, the recipient details, the fulfillment methods and the delivery options. required: - id - line_items - fulfillments - recipient_contact v1alphaDeliveryCategory: 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/v1alphaDeliveryOption' description: The delivery options available within this category. addons: type: array items: type: object $ref: '#/definitions/v1alphaAddon' 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. 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 - sort_order - options_source - delivery_options v1alphaDeliveryChoice: 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. description: The DeliveryChoice represents what option is selected for the given delivery. required: - delivery_id - option_id v1alphaDeliveryOption: 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/v1alphaPickupLocation' description: The pickup location for this delivery option, if applicable. etd: $ref: '#/definitions/v1alphaETD' 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. description: The DeliveryOption represents the details of a specific delivery option. required: - id - carrier - etd - price v1alphaDistance: 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 title: Generic distance v1alphaETD: 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. v1alphaFulfillment: type: object properties: readiness: $ref: '#/definitions/FulfillmentReadiness' description: The time window when the goods will be ready for shipment. description: A Fulfillment details when a delivery can be fulfilled. required: - readiness v1alphaLineItem: 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. Equivalent of cart_items_attributes in the `Delivery Checkout` API. description: Represents a single item. required: - sku - title - quantity - price v1alphaPickupLocation: 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/prepurchasev1alphaContact' description: Contact information when visiting the location for retrieving a package. delivery_contact: $ref: '#/definitions/prepurchasev1alphaContact' 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 v1alphaSession: 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/v1alphaDelivery' 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. If an etag is provided and does not match the current etag of the session, updates and completion will be blocked and an ABORTED error will be returned. description: A Session is the primary resource for handling the delivery options and the customer lifecycle. required: - purchase - deliveries securityDefinitions: Authorization: type: apiKey name: authorization in: header security: - Authorization: []