Console

Settings

Sign out

Notifications

Alexa

Amazon Appstore

Ring

AWS

Documentation

Support

My Cases

Console

Alexa+ Builder Docs

Get started

Category SDK

MCP toolkit

Certify

Resources

Food Ordering SPI

This document outlines the Service Provider Interface (SPI) for Food Ordering within the Category SDK framework. The SPI defines the contract you implement to integrate food ordering with Alexa+. Supported use cases include restaurant discovery, menu browsing, cart management, checkout, and order tracking.

Namespace

The namespace for the Food Ordering SPI is com.amazon.alexa.foodordering.v1.

Operations

The Food Ordering SPI supports the following operations. Alexa+ performs permission checks at runtime before running each SPI operation.

Operation	Path	HTTP method	Type	Requires permissions
BatchGetMenuItems	`/v1/foodordering/restaurants/{restaurantId}/menuItems/search`	POST	Idempotent	—
CancelPurchase	`/v1/foodordering/purchases/{purchaseId}`	DELETE	Idempotent	—
CreateCartItem	`/v1/foodordering/purchases/{purchaseId}/carts/{cartId}/cartItems`	POST	Non-idempotent	—
CreatePurchase	`/v1/foodordering/purchases`	POST	Non-idempotent	—
DeleteCartItem	`/v1/foodordering/purchases/{purchaseId}/carts/{cartId}/cartItems/{cartItemId}`	DELETE	Idempotent	—
GetAddresses	`/v1/foodordering/users/current/addresses`	GET	Read-only	`READ_DEVICE_ADDRESS`
GetMenuItem	`/v1/foodordering/restaurants/{restaurantId}/menuCategories/{menuCategoryId}/menuItems/{menuItemId}`	GET	Read-only	—
GetPaymentMethods	`/v1/foodordering/users/current/paymentMethods`	GET	Read-only	—
GetPurchase	`/v1/foodordering/purchases/{purchaseId}`	GET	Read-only	—
GetRestaurant	`/v1/foodordering/restaurants/{restaurantId}`	GET	Read-only	—
GetRestaurantAvailability	`/v1/foodordering/restaurants/availability`	POST	Idempotent	—
PreviewPurchase	`/v1/foodordering/purchases/{purchaseId}/preview`	POST	Idempotent	`READ_DEVICE_ADDRESS`, `READ_EMAIL`, `READ_MOBILE_NUMBER`, `READ_FULL_NAME`
RecreatePurchase	`/v1/foodordering/purchases/recreate`	POST	Non-idempotent	—
SearchOrders	`/v1/foodordering/orders/search`	POST	Idempotent	—
SearchPurchases	`/v1/foodordering/purchases/search`	POST	Idempotent	—
SubmitPurchase	`/v1/foodordering/purchases/{purchaseId}/submit`	POST	Non-idempotent	`WRITE_NOTIFICATIONS`
UpdateCartItem	`/v1/foodordering/purchases/{purchaseId}/carts/{cartId}/cartItems/{cartItemId}`	PUT	Idempotent	—
UpdatePurchase	`/v1/foodordering/purchases/{purchaseId}`	PATCH	Idempotent	—

Common request headers

Every operation in the Food Ordering SPI includes the following HTTP headers. These are sent by Alexa+ and available in the request context.

Header	Type	Description	Required
requestId	String	Unique identifier for the request to help with tracking and debugging	No
timestamp	Timestamp	Indicates when the request was initiated. Format: RFC 3339 date-time.	No
locale	String	The preferred language for the response content following RFC 5646 format, for example, `en-US`	No
applicationId	String	Identifier of the Alexa application making the request	No
userId	String	Unique identifier of the end user making the request. This field is sensitive and must not be exposed in exception messages or log output.	No
userAccessToken	String	Authentication token for the user's session. Provided if the user has successfully linked their account. This field is sensitive and must not be exposed in exception messages or log output.	No

BatchGetMenuItems

Path: /v1/foodordering/restaurants/{restaurantId}/menuItems/search
Method: POST
Type: Idempotent

Retrieves detailed information for multiple menu items in a single request, such as when displaying reorder candidates or resolving items that span multiple categories within a restaurant. Returns per-item issues for items that cannot be resolved (for example, item no longer available or not found).

Request

Parameter	Type	Description	Required
restaurantId	String	The restaurant whose menu items to fetch. Length: 1–256 characters.	Yes
menuItems	List(MenuItemIdentifier)	A list of item identifiers to resolve. Each identifier contains menuCategoryId and menuItemId.	Yes

Response

Parameter	Type	Description	Required
menuItems	List(MenuItemDetails)	Successfully resolved items with full detail (name, price, choices, attributes, availability)	Yes
issues	List(MenuItemIssue)	Per-item problems for items that could not be resolved	No

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

CancelPurchase

Path: /v1/foodordering/purchases/{purchaseId}
Method: DELETE
Type: Idempotent

Cancels an in-progress purchase, abandoning the checkout session. Once cancelled, the purchase and its associated cart(s) are discarded. Only applies to purchases that have NOT been submitted. Once SubmitPurchase has been called, the purchase cannot be cancelled through this operation. Returns an empty response on success.

Request

Parameter	Type	Description	Required
purchaseId	String	The ID of the purchase to cancel. Length: 1–256 characters.	Yes

Response

Empty body on success.

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

CreateCartItem

Path: /v1/foodordering/purchases/{purchaseId}/carts/{cartId}/cartItems
Method: POST
Type: Non-idempotent

Creates a cart item for the menu item selection made by the user. The cartItemSelection contains only the subset of options and choices that the user has explicitly selected, and does not represent the full menu item definition.

Request

Parameter	Type	Description	Required
purchaseId	String	Identifier for the purchase. Length: 1–256 characters.	Yes
cartId	String	Identifier for the cart. Length: 1–256 characters.	Yes
cartItemSelection	CartItemSelection	The user's selection for a specific menu item	Yes

Response

Parameter	Type	Description	Required
purchaseId	String	Identifier for the purchase	Yes
cartId	String	Identifier for the cart	Yes
cartItemId	String	Identifier for the newly created cart item	Yes

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

CreatePurchase

Path: /v1/foodordering/purchases
Method: POST
Type: Non-idempotent

Creates a new Purchase, which represents the user's intent to buy. A Purchase is a pre-payment container that encapsulates cart details (items, quantities, customizations) along with fulfillment details (delivery address, delivery type, estimated time). The v1 model supports exactly one cart per purchase.

Request

Parameter	Type	Description	Required
cartSelections	List(CartSelection)	The cart's menu item selections	Yes
fulfillment	Fulfillment	Details about how the purchase is to be fulfilled (delivery or pickup)	Yes
recipient	UserDetails	Information about the user placing the purchase	No
paymentSelections	List(PaymentSelection)	Payment method selections for the purchase	No

Response

Parameter	Type	Description	Required
purchaseId	String	A unique identifier for the newly created purchase	Yes
carts	List(CartDetails)	The cart(s) in the purchase with enriched item details	Yes

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

DeleteCartItem

Path: /v1/foodordering/purchases/{purchaseId}/carts/{cartId}/cartItems/{cartItemId}
Method: DELETE
Type: Idempotent

Deletes an existing cart item from a specific cart in a purchase. Returns an empty response upon successful deletion.

Request

Parameter	Type	Description	Required
purchaseId	String	The ID of the purchase. Length: 1–256 characters.	Yes
cartId	String	The ID of the cart. Length: 1–256 characters.	Yes
cartItemId	String	The ID of the item to be removed. Length: 1–256 characters.	Yes

Response

Empty body on success.

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

GetAddresses

Path: /v1/foodordering/users/current/addresses
Method: GET
Type: Read-only
Required Permissions: READ_DEVICE_ADDRESS

Returns the saved delivery addresses available for the authenticated user. The user is identified from the authentication token — no explicit user ID is required in the request. Returns the complete list in a single response (no pagination).

Call this operation during checkout to present delivery address options before calling UpdatePurchase or CreatePurchase with the selected address in the fulfillment.delivery.address field.

Request

No operation-specific parameters. Only common request headers are sent.

Response

Parameter	Type	Description	Required
addresses	List(AddressSummary)	A list of saved addresses with addressId, details, and optional label	Yes

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

GetMenuItem

Path: /v1/foodordering/restaurants/{restaurantId}/menuCategories/{menuCategoryId}/menuItems/{menuItemId}
Method: GET
Type: Read-only

Returns detailed information about a specific menu item, including its customization options, availability, base price, description, image, and the complete tree of choice categories for cart item customization.

Call this operation before adding an item to the cart to present customization options to the customer, or after a reorder to verify item availability and display current options.

Request

Parameter	Type	Description	Required
restaurantId	String	The restaurant the item belongs to. Length: 1–256 characters.	Yes
menuCategoryId	String	The menu category containing the item. Length: 1–256 characters.	Yes
menuItemId	String	The item to retrieve. Length: 1–256 characters.	Yes

Response

Parameter	Type	Description	Required
menuItem	MenuItemDetails	Full details of the menu item including customization options	No

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

GetPaymentMethods

Path: /v1/foodordering/users/current/paymentMethods
Method: GET
Type: Read-only

Returns the saved payment methods available for the authenticated user. The user is identified from the authentication token — no explicit user ID is required in the request. Returns the complete list in a single response (no pagination).

Call this operation during checkout to present available payment options before calling UpdatePurchase with the selected instrument.

Request

No operation-specific parameters. Only common request headers are sent.

Response

Parameter	Type	Description	Required
paymentMethods	List(PaymentMethodDetails)	A list of saved payment instruments with paymentMethodId and instrument details	Yes

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

GetPurchase

Path: /v1/foodordering/purchases/{purchaseId}
Method: GET
Type: Read-only

Retrieves the full details of an in-progress purchase by its identifier. A purchase represents an active checkout session — it contains the assembled cart(s), selected fulfillment method, charges, and optional payment/recipient information. Returns the purchase only while it is in progress (pre-submit). After SubmitPurchase is called, use SearchOrders to retrieve the resulting orders.

Call this operation to resume or inspect an in-progress checkout, or to check whether all required information (address, payment) is present before calling PreviewPurchase.

Request

Parameter	Type	Description	Required
purchaseId	String	The unique identifier of the purchase. Length: 1–256 characters.	Yes

Response

Parameter	Type	Description	Required
purchaseId	String	The purchase identifier	Yes
carts	List(CartDetails)	The cart(s) in the purchase, each containing restaurant info and items	Yes
charges	Charges	Current charge breakdown (subtotal, delivery fee, tip, taxes, grand total)	Yes
fulfillment	Fulfillment	Delivery or pickup details	Yes
recipient	UserDetails	User details for the delivery	No
payments	List(Payment)	Currently selected payment method(s)	No
estimatedFulfillmentTime	EstimatedTimeWindow	Estimated delivery/pickup window	No
issues	List(Issue)	Validation problems that need to be resolved before submission	No

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

GetRestaurant

Path: /v1/foodordering/restaurants/{restaurantId}
Method: GET
Type: Read-only

Retrieves detailed information for a restaurant using its ID, including name, address, image, default tip, currency code, fulfillment availability, and optionally menu categories.

Request

Parameter	Type	Description	Required
restaurantId	String	Unique identifier for the restaurant. Length: 1–256 characters.	Yes
includeMenuCategories	Boolean	When set to `true`, the response includes the restaurant's menu categories	No

Response

Parameter	Type	Description	Required
restaurantId	String	Unique identifier for the restaurant	Yes
name	String	Restaurant display name	Yes
isOpen	Boolean	Whether the restaurant is currently open	Yes
imageUrl	String	Restaurant image URL (HTTPS)	No
isSpecialInstructionsSupported	Boolean	Whether the restaurant supports special instructions	Yes
currencyCode	String	ISO 4217 3-letter currency code (for example, `USD`)	Yes
address	AddressDetails	Restaurant physical address with coordinates	Yes
defaultTip	TipValue	Default tip suggestion for the restaurant	No
fulfillmentAvailabilitySummary	FulfillmentAvailabilitySummary	Summary of fulfillment options available	Yes
menuCategories	List(MenuCategoryDetails)	Menu categories (present only when `includeMenuCategories=true`)	No
phoneNumber	PhoneNumber	Restaurant phone number. This field is sensitive.	No

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

GetRestaurantAvailability

Path: /v1/foodordering/restaurants/availability
Method: POST
Type: Idempotent

Returns availability information for one or more restaurants based on the specified fulfillment method. For each restaurant, returns whether it is currently open, whether delivery is available, estimated delivery time range, delivery fee, and distance. Typically called after a restaurant search to determine availability.

Request

Parameter	Type	Description	Required
restaurantIds	List(String)	A list of restaurant IDs to check	Yes
fulfillment	Fulfillment	Fulfillment method (for delivery, an address must be provided)	Yes
maxResults	Integer	Maximum number of results to return per page. Range: 1–50. Default: 20.	Yes
nextToken	String	Opaque cursor for the next page of results	No

Response

Parameter	Type	Description	Required
availabilities	List(RestaurantAvailability)	Availability details for each requested restaurant	Yes
nextToken	String	Opaque cursor for retrieving the next page. Absent when no more results are available.	No

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

PreviewPurchase

Path: /v1/foodordering/purchases/{purchaseId}/preview
Method: POST
Type: Idempotent
Required Permissions: READ_DEVICE_ADDRESS, READ_EMAIL, READ_MOBILE_NUMBER, READ_FULL_NAME

Generates a checkout preview for a purchase before final submission. Computes and returns the complete invoice breakdown — including subtotal, taxes, delivery fees, tip, discounts/savings, and grand total — so the customer can review their order before confirming. This operation does NOT charge payment or create orders. Validates completeness and returns issues if required information is missing.

Call this operation after the cart is built and before asking the user to confirm, after any change to tip, delivery address, or payment method (to refresh totals), and before calling SubmitPurchase.

Request

Parameter	Type	Description	Required
purchaseId	String	The purchase to preview. Length: 1–256 characters.	Yes

Response

Parameter	Type	Description	Required
purchaseId	String	The purchase identifier	Yes
carts	List(CartDetails)	Items in the order with restaurant info	Yes
fulfillment	Fulfillment	Delivery address and method	Yes
estimatedFulfillmentTime	EstimatedTimeWindow	When the order is expected to arrive	Yes
charges	Charges	Complete cost breakdown	Yes
payments	List(Payment)	Selected payment method(s)	No
recipient	UserDetails	User details for delivery	No
issues	List(Issue)	Validation problems that must be resolved before submission (empty if ready)	No

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

RecreatePurchase

Path: /v1/foodordering/purchases/recreate
Method: POST
Type: Non-idempotent

Recreates a new purchase based on a previously placed order. Allows a user to reorder from a previous order. If the original order contains items or options that are no longer available, those may be omitted or flagged in the response issues.

Request

Parameter	Type	Description	Required
orderId	String	The ID of the previously placed order to recreate as a purchase	Yes
fulfillment	Fulfillment	How the order will be fulfilled (delivery or pickup)	No

Response

Parameter	Type	Description	Required
purchaseId	String	Identifier for the newly created purchase	Yes
issues	List(MenuItemIssue)	Per-item issues for menu items from the original order that could not be recreated	No

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

SearchOrders

Path: /v1/foodordering/orders/search
Method: POST
Type: Idempotent

Searches for orders matching the specified criteria. Returns a paginated list of orders filtered by state, fulfillment type, and optional text matching on restaurant name, cuisine, or menu item.

Request

Parameter	Type	Description	Required
state	OrderState	Filter by order state (ACTIVE, FULFILLED, CANCELLED)	Yes
fulfillmentType	String	Fulfillment type filter (DELIVERY, PICKUP, DINE_IN)	No
menuItemName	String	Filter by menu item name	No
restaurantName	String	Filter by restaurant name	No
cuisineName	String	Filter by cuisine name	No
maxResults	Integer	Maximum number of results to return per page. Range: 1–50. Default: 20.	Yes
nextToken	String	Opaque cursor for the next page of results	No

Response

Parameter	Type	Description	Required
orders	List(OrderDetails)	Matching orders	Yes
nextToken	String	Pagination cursor for the next page. Absent when no more results are available.	No

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

SearchPurchases

Path: /v1/foodordering/purchases/search
Method: POST
Type: Idempotent

Searches for active purchases (in-progress checkouts) associated with the authenticated user. Returns only pre-submit purchases — use SearchOrders for placed orders.

Request

Parameter	Type	Description	Required
maxResults	Integer	Maximum number of results to return per page. Range: 1–50. Default: 20.	Yes
nextToken	String	Opaque cursor for the next page of results	No

Response

Parameter	Type	Description	Required
purchases	List(PurchaseSummary)	A list of purchase summaries	Yes
nextToken	String	Pagination cursor for the next page. Absent when no more results are available.	No

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

SubmitPurchase

Path: /v1/foodordering/purchases/{purchaseId}/submit
Method: POST
Type: Non-idempotent
Required Permissions: WRITE_NOTIFICATIONS

Submits the purchase, finalizing it and placing the order. This operation is NOT idempotent — calling twice may result in duplicate orders. Assumes PreviewPurchase was called and issues resolved. Returns the created order IDs for subsequent tracking via SearchOrders.

Call this operation only after PreviewPurchase returns zero issues and the user explicitly confirms. Never call without user confirmation — this charges real money.

Request

Parameter	Type	Description	Required
purchaseId	String	The purchase to submit. Length: 1–256 characters.	Yes

Response

Parameter	Type	Description	Required
orderIds	List(String)	Order identifiers created from this purchase. Multiple IDs are possible in multi-cart scenarios.	Yes

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

UpdateCartItem

Path: /v1/foodordering/purchases/{purchaseId}/carts/{cartId}/cartItems/{cartItemId}
Method: PUT
Type: Idempotent

Updates an existing cart item with new menu item selections made by the user. The cartItemSelection contains only the subset of menu item options explicitly selected by the user.

Request

Parameter	Type	Description	Required
purchaseId	String	Identifier for the purchase. Length: 1–256 characters.	Yes
cartId	String	Identifier for the cart. Length: 1–256 characters.	Yes
cartItemId	String	Identifier for the cart item. Length: 1–256 characters.	Yes
cartItemSelection	CartItemSelection	The user's updated menu item choices	Yes

Response

Empty body on success.

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

UpdatePurchase

Path: /v1/foodordering/purchases/{purchaseId}
Method: PATCH
Type: Idempotent

Updates a purchase with new payment, tip, fulfillment, or recipient details. Only payments, fulfillment, tip, and recipient updates are supported. Cart contents cannot be modified through this operation — use the CartItem operations (CreateCartItem / UpdateCartItem / DeleteCartItem) instead. Returns an empty response on success.

Request

Parameter	Type	Description	Required
purchaseId	String	Identifier of the purchase to update. Length: 1–256 characters.	Yes
paymentSelections	List(PaymentSelection)	Updated payment information	No
tip	Tip	Tip to apply. If present, fully replaces the existing tip; if omitted, the existing tip is left unchanged.	No
fulfillment	Fulfillment	How the purchase will be fulfilled (delivery or pickup)	No
recipient	UserDetails	User details for the person receiving the purchase	No

Response

Empty body on success.

Errors

400 ValidationException
400 FoodOrderingError
408 RequestTimeoutError
429 RequestThrottlingError
500 InternalServerError

Components

ActiveStateDetails

Details for an order in ACTIVE state (placed but not yet fulfilled).

Parameter	Type	Description	Required
status	String	Current progress status of the active order	Yes
estimatedFulfillmentTime	String	Estimated delivery/pickup time (RFC 3339). Maximum length: 35 characters.	Yes
lastUpdatedAt	String	When the status was last updated (RFC 3339). Maximum length: 35 characters.	No

AddressDetails

Physical address with structured postal fields and geographic coordinates.

Parameter	Type	Description	Required
addressLine1	String	Primary street address line. This field is sensitive.	No
addressLine2	String	Secondary address line (apt, suite, unit, etc.). This field is sensitive.	No
addressLine3	String	Additional address line. This field is sensitive.	No
city	String	City or locality name	No
stateOrRegion	String	State, region, or province	No
districtOrCounty	String	District or county	No
countryCode	String	ISO 3166-1 alpha-2 country code, for example, `US`. Exactly 2 characters.	No
postalCode	String	Postal or ZIP code	No
formattedAddress	String	Human-readable, locale-aware formatted address string for display purposes. Required for restaurant addresses; not required for delivery addresses.	No
coordinates	GeoCoordinates	Geographic coordinates for location-based operations. This field is sensitive.	No

AddressSummary

A saved address entry with identifier, details, and optional label.

Parameter	Type	Description	Required
addressId	String	Unique identifier for the address	Yes
details	AddressDetails	Physical address details	Yes
label	String	Human-readable label, for example, "Home" or "Work"	No

AmazonPay

Amazon Pay payment instrument. This is a marker type with no members.

CancelledStateDetails

Details for an order in CANCELLED state.

Parameter	Type	Description	Required
cancelledAt	String	When the order was cancelled (RFC 3339). Maximum length: 35 characters.	No
reason	String	Why the order was cancelled	No
cancelledBy	String	Who initiated the cancellation (USER, RESTAURANT, PLATFORM)	No

CartDetails

Full cart details including items and restaurant information.

Parameter	Type	Description	Required
cartId	String	Unique identifier for the cart	Yes
restaurantSummaries	List(RestaurantSummary)	Restaurants associated with this cart	Yes
cartItems	List(CartItemDetails)	Items in the cart	Yes

CartItemChoice

A choice within a cart item.

Parameter	Type	Description	Required
choiceId	String	Unique identifier for the choice	Yes
name	String	Display name of the choice	Yes
quantity	Integer	Quantity selected	Yes
price	MonetaryValue	Price of the choice	Yes
choiceCategories	List(CartItemChoiceCategory)	Nested sub-choice categories. Default: empty list.	Yes

CartItemChoiceCategory

A choice category within a cart item.

Parameter	Type	Description	Required
categoryId	String	Unique identifier for the category	Yes
name	String	Display name of the category	Yes
choices	List(CartItemChoice)	Choices within this category. Default: empty list.	Yes

CartItemDetails

A fully detailed cart item returned in responses. Enriches the user's original selections with assigned cartItemId and display-ready fields.

Parameter	Type	Description	Required
cartItemId	String	Unique identifier for the cart item	Yes
restaurantId	String	Restaurant identifier	Yes
menuCategoryId	String	Menu category identifier	Yes
menuItemId	String	Menu item identifier	Yes
menuItemName	String	Display name of the menu item	Yes
price	MonetaryValue	Item price	Yes
quantity	Integer	Number of this item in the cart	Yes
imageUrl	String	Item image URL (HTTPS). Minimum length: 1 character.	No
specialInstructions	String	Free-text preparation instructions	No
choiceCategories	List(CartItemChoiceCategory)	Customization choices for this item. Default: empty list.	Yes

CartItemSelection

Represents the user's explicit menu item choices. Used in requests (CreateCartItem, UpdateCartItem, CreatePurchase) and contains only what the user chose.

Parameter	Type	Description	Required
menuCategoryId	String	Menu category this item belongs to	Yes
menuItemId	String	The menu item being added/updated	Yes
quantity	Integer	Number of servings of this item	Yes
specialInstructions	String	Free-text preparation instructions (for example, "no onions, extra sauce")	No
choiceCategorySelections	List(ChoiceCategorySelection)	User's customization choices for this item. Default: empty list.	Yes

CartSelection

Cart selection containing the restaurant and item selections.

Parameter	Type	Description	Required
restaurantId	String	The restaurant this cart belongs to	Yes
cartItemSelections	List(CartItemSelection)	Item selections for the cart	No

Charges

Cost breakdown for an order or purchase. All fields are required — services MUST return values for every field (use zero amounts when a charge component does not apply).

Parameter	Type	Description	Required
subTotal	MonetaryValue	Total cost of items before fees, taxes, and discounts	Yes
deliveryFee	MonetaryValue	Fee charged for delivery. Zero for pickup orders.	Yes
tip	Tip	Tip applied to the order	Yes
taxes	MonetaryValue	Total tax amount	Yes
savings	List(Saving)	Discount/promotion savings applied. Empty list if no savings.	Yes
otherFees	List(OtherFee)	Additional fees (service fee, small order fee, etc.). Empty list if none apply.	Yes
grandTotal	MonetaryValue	Final amount charged (subTotal + deliveryFee + tip + taxes + otherFees - savings)	Yes

ChoiceCategorySelection

A selected choice category with the user's chosen options.

Parameter	Type	Description	Required
choiceCategoryId	String	ID of the choice category (for example, "toppings", "size")	Yes
choiceSelections	List(ChoiceSelection)	Choices selected within this category. Default: empty list.	Yes

ChoiceQuantityLimits

Quantity limits for a single choice option.

Parameter	Type	Description	Required
minQuantity	Integer	Minimum quantity allowed	Yes
maxQuantity	Integer	Maximum quantity allowed	Yes
defaultQuantity	Integer	Default quantity if not specified	Yes

ChoiceQuantitySumLimits

Limits on the sum of quantities across all choices in a category.

Parameter	Type	Description	Required
minSum	Integer	Minimum total quantity sum	Yes
maxSum	Integer	Maximum total quantity sum	Yes

ChoiceSelection

A single choice selected by the user within a category.

Parameter	Type	Description	Required
choiceId	String	ID of the chosen option (for example, "extra_cheese")	Yes
quantity	Integer	Quantity of this choice (for example, 2x extra cheese)	Yes
choiceCategorySelections	List(ChoiceCategorySelection)	Nested sub-choices if this choice has its own customization tree. Default: empty list.	Yes

CreditCard

Credit or debit card payment instrument details.

Parameter	Type	Description	Required
type	String	Card network identifier (for example, VISA, MASTERCARD, AMERICAN_EXPRESS, JCB, UNIONPAY)	Yes
lastFourDigits	String	Last four digits of the card number	Yes
lightImageUrl	String	Card network logo URL for light theme backgrounds (HTTPS)	No
darkImageUrl	String	Card network logo URL for dark theme backgrounds (HTTPS)	No

Delivery

Delivery fulfillment details including destination address and delivery timing.

Parameter	Type	Description	Required
address	AddressDetails	Delivery destination address	Yes
type	String	Logistics method (ASAP, SCHEDULED, MARKETPLACE_DELIVERY, RESTAURANT_DELIVERY). Any string is accepted.	No

DeliveryAvailability

Detailed delivery availability for a restaurant at a given address.

Parameter	Type	Description	Required
isOpen	Boolean	Whether the restaurant is currently open for business	Yes
isAvailable	Boolean	Whether delivery is available to the specified address right now	Yes
cutOffInMinutes	Integer	Minutes remaining before delivery orders are cut off	No
distance	Distance	Distance from the delivery address to the restaurant	No
fee	MonetaryValue	Delivery fee for this restaurant/address combination. Present when `isAvailable = true`.	No
deliveryEstimateRange	DurationRange	Estimated delivery time range (for example, 25-40 minutes). Present for ASAP delivery only.	No
unavailabilityCodes	List(UnavailabilityCode)	Reasons why delivery is unavailable. Present when `isAvailable = false`.	No

DeliveryAvailabilitySummary

Summary of delivery availability for a restaurant.

Parameter	Type	Description	Required
isOpen	Boolean	Whether the restaurant is currently open	Yes
isAvailable	Boolean	Whether delivery is available	Yes
cutOffInMinutes	Integer	Minutes remaining before delivery orders are cut off	No

Distance

A distance measurement with explicit unit.

Parameter	Type	Description	Required
value	Double	Numeric distance value (non-negative)	Yes
unit	DistanceUnit	Unit of measurement (KILOMETERS or MILES)	Yes

DistanceUnit

Unit of distance measurement.

enum DistanceUnit {
    KILOMETERS
    MILES
}

DistinctChoiceLimits

Limits on the number of distinct choices that can be selected in a category.

Parameter	Type	Description	Required
minChoices	Integer	Minimum number of distinct choices required	Yes
maxChoices	Integer	Maximum number of distinct choices allowed	Yes

DurationRange

A relative duration range in minutes (for example, estimated delivery: 25-40 minutes).

Parameter	Type	Description	Required
minMinutes	Integer	Minimum duration in minutes	Yes
maxMinutes	Integer	Maximum duration in minutes	Yes

EstimatedTimeWindow

Estimated fulfillment time — either a relative duration from now or an absolute window. Exactly one variant is present.

Parameter	Type	Description	Required
relativeMinutesRange	DurationRange	A relative duration range in minutes	No
absoluteTimeRange	TimeRange	An absolute time range between two RFC 3339 datetime points	No

Fulfillment

How the order will be fulfilled — delivery or pickup. Exactly one variant is present.

Parameter	Type	Description	Required
delivery	Delivery	Delivery fulfillment details	No
pickup	Pickup	Pickup fulfillment details	No

FulfillmentAvailability

Availability by fulfillment type for a restaurant.

Parameter	Type	Description	Required
delivery	DeliveryAvailability	Delivery availability details. Absent if delivery is not offered.	No

FulfillmentAvailabilitySummary

Summary of fulfillment availability options for a restaurant.

Parameter	Type	Description	Required
delivery	DeliveryAvailabilitySummary	Delivery availability summary	Yes

FulfilledStateDetails

Details for an order in FULFILLED state (successfully delivered or picked up).

Parameter	Type	Description	Required
placedAt	String	When the order was originally placed (RFC 3339). Maximum length: 35 characters.	Yes
fulfilledAt	String	When the order was delivered or picked up (RFC 3339). Maximum length: 35 characters.	No

GeoCoordinates

Geographic coordinates for location-based operations. This structure is sensitive and must not be exposed in exception messages or log output.

Parameter	Type	Description	Required
latitudeInDegrees	Double	Latitude in degrees (-90 to 90)	Yes
longitudeInDegrees	Double	Longitude in degrees (-180 to 180)	Yes
accuracyInMeters	Double	GPS provided accuracy value for the coordinates (in meters)	No

Issue

A validation issue or error associated with a purchase or order.

Parameter	Type	Description	Required
code	FoodOrderingErrorCode	Error code identifying the issue	Yes
metadata	String	Additional metadata about the issue	No

MenuCategoryDetails

A menu category containing item summaries.

Parameter	Type	Description	Required
restaurantId	String	Restaurant identifier	Yes
menuCategoryId	String	Unique identifier for the category	Yes
name	String	Display name of the category	Yes
menuItemSummaries	List(MenuItemSummary)	Items in this category	Yes

MenuItemAttributes

Metadata attributes for a menu item.

Parameter	Type	Description	Required
containsAlcohol	Boolean	Whether the item contains alcohol	Yes
popular	Boolean	Whether the item is popular	Yes

MenuItemChoice

A customization choice for a menu item.

Parameter	Type	Description	Required
id	String	Unique identifier for the choice	Yes
name	String	Display name of the choice	Yes
choiceCategories	List(MenuItemChoiceCategory)	Nested sub-categories for this choice	No
quantityLimits	ChoiceQuantityLimits	Quantity constraints for this choice	No
selectedByDefault	Boolean	Whether this choice is pre-selected	No
price	MonetaryValue	Price of this choice	No

MenuItemChoiceCategory

A choice category within a menu item (for example, "Size", "Toppings").

Parameter	Type	Description	Required
id	String	Unique identifier for the category	Yes
name	String	Display name of the category	Yes
choices	List(MenuItemChoice)	Available choices in this category	No
distinctChoiceLimits	DistinctChoiceLimits	Limits on distinct choices	Yes
choiceQuantitySumLimits	ChoiceQuantitySumLimits	Limits on the sum of choice quantities	No

MenuItemDetails

Full details of a menu item including customization options. Used in GetMenuItem and BatchGetMenuItems responses.

Parameter	Type	Description	Required
restaurantId	String	Restaurant identifier. Length: 1–256 characters.	Yes
menuCategoryId	String	Menu category identifier. Length: 1–256 characters.	Yes
menuItemId	String	Menu item identifier. Length: 1–256 characters.	Yes
available	Boolean	Whether the item can currently be ordered	Yes
name	String	Item display name	Yes
basePrice	MonetaryValue	Starting price before customizations	Yes
imageUrl	String	Item image URL (HTTPS)	No
attributes	MenuItemAttributes	Item metadata (contains alcohol, popular)	Yes
choiceCategories	List(MenuItemChoiceCategory)	Customization categories	No
maxQuantityPerOrder	Integer	Maximum quantity allowed per order. Present only when a limit applies.	No
description	String	Item description text	No

MenuItemIdentifier

Identifies a specific menu item by category and item ID.

Parameter	Type	Description	Required
menuCategoryId	String	Menu category identifier. Length: 1–256 characters.	Yes
menuItemId	String	Menu item identifier. Length: 1–256 characters.	Yes

MenuItemIssue

Per-item issue details for items that could not be resolved.

Parameter	Type	Description	Required
menuItem	MenuItemIdentifier	The item that has issues	Yes
issues	List(Issue)	Issues for this item	No

MenuItemSummary

Summary of a menu item for display in category listings.

Parameter	Type	Description	Required
menuItemId	String	Unique identifier for the menu item	Yes
name	String	Display name of the item	Yes
basePrice	MonetaryValue	Starting price before customizations	Yes
imageUrl	String	Item image URL (HTTPS)	No
attributes	MenuItemAttributes	Item metadata (contains alcohol, popular)	Yes
description	String	Item description text	No
maxQuantityPerOrder	Integer	Maximum quantity per order	No
hasCustomizations	Boolean	Whether the item has customization options	No

MonetaryValue

A monetary amount with currency. The value field uses a decimal string representation to avoid floating-point precision issues. Negative values are permitted (for example, discounts, refunds).

Parameter	Type	Description	Required
currencyCode	String	ISO 4217 three-letter currency code, for example, `USD`. Exactly 3 characters.	Yes
value	String	Decimal string representation of the amount, for example, `12.99`. Must match `^[+-]?[0-9]+(\.[0-9]+)?$`. Maximum length: 128 characters.	Yes

OrderDetails

Complete details of a placed order, returned by SearchOrders.

Parameter	Type	Description	Required
orderId	String	Unique identifier for this order	Yes
state	OrderState	Current lifecycle state (ACTIVE, FULFILLED, or CANCELLED)	Yes
stateDetails	OrderStateDetails	State-specific metadata	Yes
carts	List(CartDetails)	Cart(s) in this order — items, quantities, and restaurant info	Yes
charges	Charges	Cost breakdown (subtotal, delivery fee, tip, taxes, grand total)	No
fulfillment	Fulfillment	How the order is being fulfilled	Yes
recipient	UserDetails	Recipient details (name, email, phone)	No
payments	List(Payment)	Payment method(s) used	No

OrderState

Current lifecycle state of an order.

enum OrderState {
    ACTIVE
    FULFILLED
    CANCELLED
}

Value	Description
ACTIVE	Order placed but not yet fulfilled
FULFILLED	Successfully delivered or picked up
CANCELLED	Order has been cancelled

OrderStateDetails

State-specific metadata for an order. Exactly one variant is present, corresponding to the order's current OrderState.

Parameter	Type	Description	Required
active	ActiveStateDetails	Details for ACTIVE state	No
fulfilled	FulfilledStateDetails	Details for FULFILLED state	No
cancelled	CancelledStateDetails	Details for CANCELLED state	No

OtherFee

A named fee component (for example, service fee, small order fee).

Parameter	Type	Description	Required
amount	MonetaryValue	Fee amount	Yes
name	String	Display name of the fee	Yes

Payment

Payment applied to a purchase, containing one or more splits across methods.

Parameter	Type	Description	Required
scope	PaymentScope	Scope to which the payment applies	Yes
splits	List(PaymentSplit)	Payment allocations across methods	Yes

PaymentInstrument

Supported payment instrument types. Exactly one variant is present.

Parameter	Type	Description	Required
creditCard	CreditCard	Credit or debit card details	No
amazonPay	AmazonPay	Amazon Pay instrument	No
payPal	PayPal	PayPal instrument	No

PaymentMethodDetails

A saved payment method with its unique identifier and instrument details.

Parameter	Type	Description	Required
paymentMethodId	String	Unique identifier for the payment method	Yes
instrument	PaymentInstrument	Payment instrument details	Yes

PaymentScope

Scope to which a payment applies.

enum PaymentScope {
    PURCHASE
}

PaymentSelection

User's payment selection for a specific scope.

Parameter	Type	Description	Required
scope	PaymentScope	Scope to which the payment applies	Yes
splits	List(PaymentSplit)	Payment allocations	Yes

PaymentSplit

A single payment allocation — method and amount charged.

Parameter	Type	Description	Required
method	PaymentMethodDetails	The payment method used	Yes
amount	MonetaryValue	Amount charged to this method	Yes

PayPal

PayPal payment instrument.

Parameter	Type	Description	Required
login	PayPalIdentifier	Identifier for the PayPal account	Yes

PayPalIdentifier

Identifier for a PayPal account — either email or phone. Exactly one variant is present. This structure is sensitive.

Parameter	Type	Description	Required
email	String	PayPal email address. Length: 5–254 characters. This field is sensitive.	No
phone	PhoneNumber	PayPal phone number. This field is sensitive.	No

PhoneNumber

Phone number with country code separation. This structure is sensitive and must not be exposed in exception messages or log output.

Parameter	Type	Description	Required
countryCallingCode	String	Country calling code, for example, `1` for US, `91` for India. Must match `^[1-9]\d{0,2}$`. Maximum length: 3 characters.	Yes
number	String	Subscriber number without country code. Must match `^\d{4,14}$`. Length: 4–14 characters. This field is sensitive.	Yes

Pickup

Pickup fulfillment details. This is a marker type with no members.

PromotionSaving

Savings from a promotion or coupon code.

Parameter	Type	Description	Required
total	MonetaryValue	Total amount saved	Yes
breakdown	SavingBreakdown	Distribution of the saving across charge components	No
name	String	Name or description of the promotion (for example, "20% off first order")	Yes

PurchaseSummary

Summary of an in-progress purchase.

Parameter	Type	Description	Required
purchaseId	String	Unique identifier for the purchase. Length: 1–256 characters.	Yes
carts	List(CartDetails)	Cart(s) in the purchase	Yes
fulfillment	Fulfillment	How the order will be fulfilled	Yes

RestaurantAvailability

Availability information for a specific restaurant.

Parameter	Type	Description	Required
restaurantId	String	Restaurant identifier	Yes
isOpen	Boolean	Whether the restaurant is currently open	Yes
fulfillmentAvailability	FulfillmentAvailability	Availability by fulfillment type	Yes

RestaurantSummary

Summary restaurant information.

Parameter	Type	Description	Required
restaurantId	String	Unique identifier for the restaurant	Yes
name	String	Restaurant display name	Yes

Saving

A saving applied to the order. Exactly one variant is present.

Parameter	Type	Description	Required
subscription	SubscriptionSaving	Savings from an active subscription	No
promotion	PromotionSaving	Savings from a promotion or coupon code	No

SavingBreakdown

Distribution of a saving across charge components.

Parameter	Type	Description	Required
deliveryFee	MonetaryValue	Amount saved on delivery fee	Yes
taxes	MonetaryValue	Amount saved on taxes	Yes
otherFees	List(OtherFee)	Savings applied to other fees	Yes

SubscriptionSaving

Savings from an active subscription (for example, a delivery membership).

Parameter	Type	Description	Required
total	MonetaryValue	Total amount saved	Yes
breakdown	SavingBreakdown	Distribution of the saving across charge components	No
name	String	Name of the subscription (for example, "Premium Delivery", "Membership Plus")	Yes

TimeRange

An absolute time range between two RFC 3339 datetime points. Used for estimated fulfillment windows.

Parameter	Type	Description	Required
earliest	String	Earliest possible time (RFC 3339). Maximum length: 35 characters.	Yes
latest	String	Latest possible time (RFC 3339). Maximum length: 35 characters.	Yes

Tip

Tip applied to the order.

Parameter	Type	Description	Required
type	String	How the tip is applied (INCLUDED_IN_BILL, CASH, PRE_PAID, POST_DELIVERY)	No
value	TipValue	The tip amount or percentage	No

TipValue

Tip value — either a percentage of the subtotal or a fixed monetary amount. Exactly one variant is present.

Parameter	Type	Description	Required
percent	Double	Tip as a percentage (for example, 15.0 for 15%)	No
amount	MonetaryValue	Tip as a fixed monetary amount	No

UnavailabilityCode

Reason codes for why delivery is unavailable.

enum UnavailabilityCode {
    DELIVERY_CUTOFF_TIME_EXCEEDED
    DELIVERY_NOT_AVAILABLE
    DELIVERY_NOT_SUPPORTED_AT_ADDRESS
    RESTAURANT_NOT_OPEN
    RESTAURANT_NOT_FOUND
    RESTAURANT_NOT_AVAILABLE
    RESTAURANT_CLOSING_SOON_FOR_DELIVERY
    RESTAURANT_CLOSING_SOON
    RESTAURANT_OPENING_SOON
}

UserDetails

Details of the order recipient (name, email, phone). All fields are optional — presence depends on permissions granted by the user. This structure is sensitive and must not be exposed in log output.

Parameter	Type	Description	Required
name	String	User's full name. Length: 1–100 characters. This field is sensitive.	No
email	String	User's email address. Must match `^[^@\s]+@[^@\s]+\.[^@\s]+$`. Length: 5–254 characters. This field is sensitive.	No
phoneNumber	PhoneNumber	User's phone number with country code. This field is sensitive.	No

ValidationException

A standard error for input validation failures. Thrown when a member of the input structure falls outside of the modeled or documented constraints.

Parameter	Type	Description	Required
message	String	A summary of the validation failure	Yes
fieldList	List(ValidationExceptionField)	A list of specific failures encountered while validating the input	No

ValidationExceptionField

Describes one specific validation failure for an input member.

Parameter	Type	Description	Required
path	String	A JSONPointer expression to the structure member whose value failed to satisfy the modeled constraints	Yes
message	String	A detailed description of the validation failure	Yes

Errors

All operations in the Food Ordering SPI may return the following errors.

FoodOrderingError

A domain-specific error containing one or more issues. HTTP status: 400.

Parameter	Type	Description	Required
message	String	Human-readable error message	Yes
issues	List(Issue)	Structured issue details	Yes

FoodOrderingErrorCode

Code	Description
INVALID_ADDRESS	The provided address is invalid
INVALID_PAYMENT_METHOD	The payment method is invalid
ORDER_NOT_FOUND	The specified order was not found
ORDER_ALREADY_PURCHASED	The order has already been purchased
DELIVERY_CUTOFF_TIME_EXCEEDED	Delivery cutoff time has passed
DELIVERY_NOT_AVAILABLE	Delivery is not currently available
DELIVERY_NOT_SUPPORTED_AT_ADDRESS	Delivery is not supported at the given address
RESTAURANT_NOT_OPEN	The restaurant is not currently open
PAYMENT_METHOD_NOT_SUPPORTED	The payment method type is not supported
PAYMENT_METHOD_NOT_ACCEPTED	The payment method was not accepted
PAYMENT_BELOW_ORDER_AMOUNT	Payment amount is below the order total
PAYMENT_EXCEEDS_ORDER_AMOUNT	Payment amount exceeds the order total
PAYMENT_METHOD_NOT_FOUND	The specified payment method was not found
PAYMENT_METHOD_MISSING	No payment method provided
DELIVERY_ADDRESS_MISSING	No delivery address provided
USER_DETAILS_MISSING	Required user details are missing
RESTAURANT_NOT_FOUND	The specified restaurant was not found
RESTAURANT_NOT_AVAILABLE	The restaurant is not available
MENU_CATEGORY_NOT_FOUND	The specified menu category was not found
MENU_ITEM_NOT_FOUND	The specified menu item was not found
MENU_ITEM_NOT_AVAILABLE	The menu item is not currently available
MENU_ITEM_QUANTITY_LIMIT_EXCEEDED	Item quantity exceeds the allowed limit
CHOICE_NOT_FOUND	The specified choice was not found
CHOICE_QUANTITY_LIMIT_EXCEEDED	Choice quantity exceeds the allowed limit
TOTAL_CHOICES_LIMIT_EXCEEDED	Total number of choices exceeds the allowed limit
REQUIRED_CHOICES_MISSING	Required choices have not been selected
PHONE_NUMBER_REQUIRED	A phone number is required
RESTAURANT_CLOSING_SOON_FOR_DELIVERY	Restaurant is closing soon for delivery orders
MENU_ITEM_CHOICE_NOT_AVAILABLE	The selected menu item choice is not available
CHECKOUT_REQUIREMENTS_NOT_MET	Checkout requirements have not been met
RESTAURANT_UNAVAILABLE_FOR_CHECKOUT	Restaurant is unavailable for checkout
INVALID_REQUEST_DATA	The request contains invalid data
MISSING_REQUEST_DATA	The request is missing required data
PICKUP_NOT_AVAILABLE	Pickup is not currently available
PICKUP_CUTOFF_TIME_EXCEEDED	Pickup cutoff time has passed
PICKUP_INFORMATION_MISSING	Required pickup information is missing
FULFILLMENT_INFORMATION_MISSING	Required fulfillment information is missing
PAYMENT_ERROR	A payment processing error occurred
PAYMENT_METHOD_BLOCKED	The payment method is blocked
MULTIPLE_RESTAURANTS_NOT_ALLOWED	Items from multiple restaurants are not allowed in one cart
ORDER_CASH_TIP_NOT_ALLOWED	Cash tip is not allowed for this order
ORDER_TIP_MAXIMUM_EXCEEDED	Tip amount exceeds the maximum allowed
ORDER_NEGATIVE_TIP_NOT_ALLOWED	Negative tip values are not allowed
COUPON_USAGE_EXCEEDED	Coupon usage limit has been exceeded
COUPON_NOT_FOUND	The specified coupon was not found
COUPON_ERROR	A coupon processing error occurred
SCHEDULED_ORDER_NOT_SUPPORTED	Scheduled orders are not supported
CART_TOTAL_LIMIT_EXCEEDED	Cart total exceeds the maximum allowed
CART_MINIMUM_TOTAL_NOT_MET	Cart total does not meet the minimum required
NOT_AUTHORIZED	The user is not authorized for this action
ORDER_HAS_UNRESOLVED_ISSUES	The order has unresolved issues
PROVIDER_TIMEOUT	The upstream provider timed out
MENU_ITEM_UNAVAILABLE_FOR_REORDER	Menu item is unavailable for reorder
UNKNOWN	Unknown error

Common error codes

HTTP status	Error	When
400	ValidationException	The request contains malformed or missing required fields
400	FoodOrderingError	A domain-specific business logic error with structured issues
408	RequestTimeoutError	You didn't respond within the required time limit
429	RequestThrottlingError	Rate limit exceeded
500	InternalServerError	Unexpected error on your side

Was this page helpful?

Provide feedback

Last updated: Jul 21, 2026