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
GetAvailability	`/v1/restaurants/{restaurantID}/availability`	GET	Read-only	No
CreateReservation	`/v1/restaurants/{restaurantID}/reservations`	POST	Non-idempotent	Yes
UpdateReservation	`/v1/restaurants/{restaurantID}/reservations/{reservationID}`	PUT	Idempotent	Yes
DeleteReservation	`/v1/restaurants/{restaurantID}/reservations/{reservationID}`	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 `YYYY-MM-DDTHH:MM` (for example, `1985-04-12T23:20`)	Yes
endDateTime	String	The end date and time in the format of `YYYY-MM-DDTHH:MM` (for example, `1985-04-12T23:20`)	Yes

Response

A successful GetAvailabilityResponse returns the available time slots.

Parameter	Type	Description	Required
availableTimeSlots	AvailableTimeSlot	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 `YYYY-MM-DDTHH:MM` (for example, `1985-04-12T23:20`)	Yes
user	UserDetails	Details about the user.	Yes

Response

A successful CreateReservationResponse returns the reservation details.

Parameter	Type	Description	Required
reservation	ReservationDetails	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 `YYYY-MM-DDTHH:MM` (for example, `1985-04-12T23:20`)	Yes
reservationId	String	ID of the reservation	Yes
user	UserDetails	Details about the user.	Yes

Response

A successful UpdateReservationResponse returns the reservation details.

Parameter	Type	Description	Required
reservation	ReservationDetails	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 `YYYY-MM-DDTHH:MM` (for example, `1985-04-12T23:20`).	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	PhoneNumber	Phone number of the user	Yes
email	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 `YYYY-MM-DDTHH:MM` (for example, `1985-04-12T23:20`)	Yes
user	UserDetails	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 `YYYY-MM-DDTHH:MM` (for example, `1985-04-12T23:20`)	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 `YYYY-MM-DDTHH:MM` (for example, `1985-04-12T23:20`)	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 `YYYY-MM-DDTHH:MM` (for example, `1985-04-12T23:20`)	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.

Create a Category Add-on Manually with the CLI

Get Started

Build with the MCP Toolkit

Build with the Category SDK

Testing

Certification

Reference

Namespace

Operations

GetAvailability

Request

Response

CreateReservation

Request

Response

UpdateReservation

Request

Response

DeleteReservation

Request

Response

Components

AvailableTimeSlot

PhoneNumber

UserDetails

ReservationDetails

Error structures

BelowMinPartySizeError

AboveMaxPartySizeError

NotFarEnoughInAdvanceError

TooFarInAdvanceError

PastCutoffError

CreditCardRequiredError

RestaurantExperienceNotSupportedError

​Namespace

​Operations

​GetAvailability

​Request

​Response

​CreateReservation

​Request

​Response

​UpdateReservation

​Request

​Response

​DeleteReservation

​Request

​Response

​Components

​AvailableTimeSlot

​PhoneNumber

​UserDetails

​ReservationDetails

​Error structures

​BelowMinPartySizeError

​AboveMaxPartySizeError

​NotFarEnoughInAdvanceError

​TooFarInAdvanceError

​PastCutoffError

​CreditCardRequiredError

​RestaurantExperienceNotSupportedError

​Related topics

Namespace

Operations

GetAvailability

Request

Response

CreateReservation

Request

Response

UpdateReservation

Request

Response

DeleteReservation

Request

Response

Components

AvailableTimeSlot

PhoneNumber

UserDetails

ReservationDetails

Error structures

BelowMinPartySizeError

AboveMaxPartySizeError

NotFarEnoughInAdvanceError

TooFarInAdvanceError

PastCutoffError

CreditCardRequiredError

RestaurantExperienceNotSupportedError

Related topics