Restaurant Reservation SPI
This document outlines the Service Provider Interface (SPI) for the Restaurant Reservation template within the Category SDK. The SPI defines the contract that you must implement to integrate with Alexa+ for enabling restaurant reservations.
Namespace
The namespace for the Restaurant Reservation SPI is com.amazon.alexa.restaurantreservation.v1.
Operations
The Restaurant Reservation SPI supports the following operations. All interfaces and fields are mandatory unless explicitly marked optional. Alexa+ performs permission checks at runtime before running the SPIs.
| Operation | Path | HTTP method | Type | Requires permissions |
|---|---|---|---|---|
|
|
GET |
Read-only |
No | |
|
|
POST |
Non-idempotent |
Yes | |
|
|
PUT |
Idempotent |
Yes | |
|
|
DELETE |
Idempotent |
No |
GetAvailability
Path: /v1/restaurants/{restaurantId}/availability
Method: GET
Type: Read-only
Retrieves available reservation times for a specified restaurant. To use this operation, you need READ access to the restaurant resource.
This operation takes input GetAvailabilityRequest and generates output GetAvailabilityResponse.
Request
| Parameter | Type | Description | Required |
|---|---|---|---|
|
restaurantId |
String |
ID of the restaurant |
Yes |
|
partySize |
Integer |
Number of people for the reservation |
Yes |
|
startDateTime |
String |
The start date and time in the format of |
Yes |
|
endDateTime |
String |
The end date and time in the format of |
Yes |
Response
A successful GetAvailabilityResponse returns the available time slots.
| Parameter | Type | Description | Required |
|---|---|---|---|
|
availableTimeSlots |
List of the available time slots |
Yes |
On error, the response returns one of the following error codes:
- RestaurantNotFoundError
- BelowMinPartySizeError
- AboveMaxPartySizeError
- CreditCardRequiredError
- RestaurantExperienceNotSupportedError
- NotFarEnoughInAdvanceError
- PastCutoffError
- TooFarInAdvanceError
- InternalServerError
- RequestThrottlingError
- RequestTimeoutError
- ValidationException
CreateReservation
Path: /v1/restaurants/{restaurantId}/reservations
Method: POST
Type: Non-idempotent
Required Permissions: READ_MOBILE_NUMBER, READ_EMAIL, READ_FULL_NAME
Creates a new restaurant reservation. Before proceeding, the system verifies that Alexa+ has permissions to access the user's mobile number, email address, and full name. If any required permissions are missing, Alexa+ initiates a permission grant flow. This flow prompts the user to authorize access to the necessary information. The operation continues after Alexa+ has obtained all required permissions.
This operation takes input CreateReservationRequest and generates output CreateReservationResponse.
Request
| Parameter | Type | Description | Required |
|---|---|---|---|
|
restaurantId |
String |
ID of the restaurant |
Yes |
|
partySize |
Integer |
Number of people for the reservation |
Yes |
|
dateTime |
String |
The date and time in the format of |
Yes |
|
user |
Details about the user. |
Yes |
Response
A successful CreateReservationResponse returns the reservation details.
| Parameter | Type | Description | Required |
|---|---|---|---|
|
reservation |
Reservation details. |
Yes |
On error, the response returns one of the following error codes:
- RestaurantNotFoundError
- BelowMinPartySizeError
- AboveMaxPartySizeError
- OverlappingReservationDetected
- ReservationSlotNotAvailable
- CreateReservationFailure
- InternalServerError
- RequestThrottlingError
- RequestTimeoutError
- ValidationException
UpdateReservation
Path: /v1/restaurants/{restaurantId}/reservations/{reservationId}
Method: PUT
Type: Idempotent
Required Permissions: READ_MOBILE_NUMBER, READ_EMAIL, READ_FULL_NAME
Updates an existing restaurant reservation. Before proceeding, the system verifies that Alexa+ has permissions to access the user's mobile number, email address, and full name. If any required permissions are missing, Alexa+ initiates a permission grant flow. This flow prompts the user to authorize access to the necessary information. The operation continues after Alexa+ has obtained all required permissions.
This operation takes input UpdateReservationRequest and generates output UpdateReservationResponse.
Request
| Parameter | Type | Description | Required |
|---|---|---|---|
|
restaurantId |
String |
ID of the restaurant |
Yes |
|
partySize |
Integer |
Number of people for the reservation |
Yes |
|
dateTime |
String |
The date and time in the format of |
Yes |
|
reservationId |
String |
ID of the reservation |
Yes |
|
user |
Details about the user. |
Yes |
Response
A successful UpdateReservationResponse returns the reservation details.
| Parameter | Type | Description | Required |
|---|---|---|---|
|
reservation |
Reservation details. |
Yes |
On error, the response returns one of the following error codes:
- BelowMinPartySizeError
- AboveMaxPartySizeError
- ReservationNotFoundError
- OverlappingReservationDetected
- ReservationSlotNotAvailable
- InternalServerError
- RequestThrottlingError
- RequestTimeoutError
- ValidationException
DeleteReservation
Path: /v1/restaurants/{restaurantId}/reservations/{reservationId}
Method: DELETE
Type: Idempotent
Deletes an existing restaurant reservation.
This operation takes input DeleteReservationRequest and generates output DeleteReservationResponse.
Request
| Parameter | Type | Description | Required |
|---|---|---|---|
|
restaurantId |
String |
ID of the restaurant |
Yes |
|
reservationId |
String |
ID of the reservation |
Yes |
Response
A successful DeleteReservationResponse returns an empty response.
On error, the response returns one of the following error codes:
- ReservationNotFoundError
- InternalServerError
- RequestThrottlingError
- RequestTimeoutError
- ValidationException
Components
AvailableTimeSlot
Time slot available for reservations from a restaurant. The availableTimeSlots list in the response can contain a maximum of 50 entries.
| Parameter | Type | Description | Required |
|---|---|---|---|
|
datetime |
String |
The date and time in the format of |
Yes |
PhoneNumber
Phone number of the user.
| Parameter | Type | Description | Required |
|---|---|---|---|
|
countryCode |
String |
Country code for the user phone number |
Yes |
|
number |
String |
Phone number of the user |
Yes |
UserDetails
Details about the user, including phone number, email, first name, and last name.
| Parameter | Type | Description | Required |
|---|---|---|---|
|
phoneNumber |
Phone number of the user |
Yes | |
|
|
String |
Email address of the user |
Yes |
|
firstName |
String |
First name of the user |
Yes |
|
lastName |
String |
Last name of the user |
Yes |
ReservationDetails
Details about the reservation, including reservation ID, number of people, date and time, and user details.
| Parameter | Type | Description | Required |
|---|---|---|---|
|
reservationId |
String |
ID of the reservation |
Yes |
|
partySize |
Integer |
Number of people for the reservation |
Yes |
|
dateTime |
String |
The date and time in the format of |
Yes |
|
user |
Details about the user |
Yes |
Error structures
All operations can return the following common errors:
| HTTP status | Error | When |
|---|---|---|
| 400 | ValidationException | The request contains malformed or missing required fields |
| 408 | RequestTimeoutError | You didn't respond within the required time limit |
| 429 | RequestThrottlingError | Rate limit exceeded |
| 500 | InternalServerError | Unexpected error on your side |
The following domain-specific error structures can include additional fields to help diagnose the issue.
BelowMinPartySizeError
Returned when the requested party size is less than the restaurant's minimum.
| Parameter | Type | Description | Required |
|---|---|---|---|
|
minPartySize |
Integer |
The minimum party size allowed by the restaurant |
No |
AboveMaxPartySizeError
Returned when the requested party size exceeds the restaurant's maximum.
| Parameter | Type | Description | Required |
|---|---|---|---|
|
maxPartySize |
Integer |
The maximum party size allowed by the restaurant |
No |
NotFarEnoughInAdvanceError
Returned when the requested reservation time doesn't meet the minimum advance booking requirement.
| Parameter | Type | Description | Required |
|---|---|---|---|
|
datetime |
String |
The earliest date and time available in the format of |
No |
TooFarInAdvanceError
Returned when the requested reservation time exceeds the maximum advance booking window.
| Parameter | Type | Description | Required |
|---|---|---|---|
|
datetime |
String |
The latest date and time available in the format of |
No |
PastCutoffError
Returned when the reservation slot's booking cutoff time has already passed.
| Parameter | Type | Description | Required |
|---|---|---|---|
|
datetime |
String |
The cutoff date and time in the format of |
No |
CreditCardRequiredError
Returned when the restaurant requires a credit card to hold the reservation and one isn't available.
RestaurantExperienceNotSupportedError
Returned when the requested restaurant experience isn't supported.
Related topics
Last updated: Jul 10, 2026
