Home Services SPI - Alexa+ Developer Docs

This document outlines the Service Provider Interface (SPI) for Home Services within the Category SDK framework. The SPI defines the contract that you can implement to integrate with Alexa+.

Namespace

The namespace for the Home Services SPI is com.amazon.alexa.homeservices.v1.

Interaction patterns

The Home Services SPI supports a number of customer-experience patterns. They fall into three categories — discovery (how the customer finds a professional), account management (how the customer’s identity is connected to your platform), and booking (how the project is handed off after matching). Discovery and account-management patterns can be combined. For example, a partner can support both BROWSE_AND_CHOOSE for some services and AUTO_MATCH for others, and either Account Linking or Automatic Account Matching as the account-management story.

Discovery Patterns

The discovery patterns describe how a customer finds the professional who will perform the project. Partners declare per-service which discovery patterns they support via the matchingStrategies field on the GetServices response.

Browse and Choose (Customer-led)

The customer describes a project, reviews matching professionals, picks one, and sends them a project request. This is the default discovery pattern (BROWSE_AND_CHOOSE). For this pattern, you must implement the following operations: GetServices, GetServiceSpecification, ListProfessionals, MessageProfessional, and GetUserInfo.

Project Definition: The customer describes the project. Alexa+ calls GetServices to identify matching service categories, then GetServiceSpecification to retrieve the per-service form. Alexa+ conducts dynamic Q&A to collect the required details.
Search Professionals: Alexa+ calls ListProfessionals with the customer’s zip code and project context. You return a ranked, paginated list with ratings, reviews, cost estimates, and response times.
Review Results: The customer reviews the professionals. Alexa+ supports voice-driven sorting and filtering by rating, response time, and cost.
Reach Out: The customer selects a professional. Alexa+ optionally calls GetUserInfo to retrieve customer details from your account, and then calls MessageProfessional to deliver the project request to the selected professional.

Category SDK home services customer-led booking workflow

Auto-Match (Platform-led)

The customer does not browse or select a professional. Instead, your platform automatically matches a professional on the customer’s behalf. This is the AUTO_MATCH discovery pattern. Browsing operations like ListProfessionals and MessageProfessional are not used in this pattern. For this pattern, you must implement these operations: GetServices, GetServiceSpecification, CreateBooking, GetUserInfo.

Project Definition: Same as Browse and Choose — Alexa+ calls GetServices and GetServiceSpecification to identify matching services and collect project details through dynamic Q&A.
Time Selection: The customer picks a preferred appointment date and time.
Account Management: If needed, Alexa+ initiates account linking or automatic account matching.
Booking Estimate: Alexa+ calls CreateBooking with stage=ESTIMATE. You return estimated charges, policies (cancellation, rescheduling), and the customer’s available payment instruments. You also return your own partnerBookingId.
Pre-Submit Confirmation: Alexa+ presents the estimate, taxes/fees, and cancellation policy. The customer selects a payment method and confirms.
Booking Confirmation: Alexa+ calls CreateBooking again with stage=CONFIRMATION, sending the same alexaBookingId along with your partnerBookingId and the chosen payment instrument.

The booking is tentative until a professional is matched. Alexa+ informs the customer and uses GetBooking to poll status until a professional is assigned.

Account-Management Patterns

The SPI supports two account-management patterns. Partners can support either or both.

Account Linking

The traditional OAuth-based linking flow. When the customer needs to be linked to the partner, Alexa+ initiates account linking via the Alexa permissions framework. The customer sees a QR code on screened devices and a notification on the Alexa mobile app, completes the OAuth flow on a second screen, and returns to the conversation. After linking, Alexa+ can call partner endpoints with the user’s access token and retrieve partner-side profile data via GetUserInfo.

Automatic Account Matching

For partners that support it, Alexa+ shares the customer’s consented contact information directly with the partner via the userInfo field on MessageProfessional and the booking operations. The partner uses this information to match the customer to an existing account — or to auto-create one server-side — without requiring the customer to go through OAuth. The customer experience differs from traditional Account Linking in that there is no QR code, no OAuth round-trip, and no second-screen step.

Booking Patterns

Booking patterns describe how the customer’s project is handed off after the customer has selected (or been matched with) a professional.

Messaging

Messaging is the default lead-generation pattern, used by the majority of partners. After Alexa+ collects the project details and the customer selects a professional, Alexa+ sends a message to the chosen professional via MessageProfessional. The professional then reaches out to the customer through their own channels to schedule and complete the work. This is the pattern that pairs naturally with the Browse and Choose discovery pattern. There is no booking-lifecycle state to track on the Alexa side — once the MessageProfessional call succeeds, the partner-side workflow takes over.

Operations

The Home Services SPI supports the following operations. Alexa+ performs permission checks and account linking checks at runtime before running the SPIs.

Operation	Path	Method	Type	Notes
GetServices	`/v1/homeservices/services`	GET	Read-only	Browse and Choose, Auto-Match
GetServiceSpecification	`/v1/homeservices/services/{serviceId}/specification`	GET	Read-only	Browse and Choose, Auto-Match
CreateBooking	`/v1/homeservices/bookings`	POST	Non-idempotent	Auto-Match only. Permissions required.
ListProfessionals	`/v1/homeservices/professionals`	POST	Read-only	Browse and Choose only
MessageProfessional	`/v1/homeservices/professionals/{professionalId}/message`	POST	Non-idempotent	Browse and Choose only. Permissions required.
GetUserInfo	`/v1/homeservices/users/current`	GET	Read-only	Browse and Choose, Auto-Match.
GetBooking	`/v1/homeservices/bookings/{partnerBookingId}`	GET	Read-only
CancelBooking	`/v1/homeservices/bookings/{partnerBookingId}/cancel`	POST	Non-idempotent	Permissions required.
ModifyBooking	`/v1/homeservices/bookings/{partnerBookingId}/modify`	POST	Non-idempotent	Permissions required.

GetServices

Path: /v1/homeservices/services
Method: GET
Type: Read-only
Account Linking: Not applicable
Applicable interaction patterns: Auto-Match and Browse and Choose Retrieves an optionally ranked list of supported services such as plumbing, house cleaning, appliance repair, based on a natural language description of a customer’s project. Amazon offers two service selection patterns:

A: Partner-driven selection

You define your service categories and select which category applies to each customer request. This option gives you the flexibility to define service categories that most closely align with your business and your existing service offerings. You influence Alexa’s decision by providing a short list, or a single service, with a confidence score greater than 0 and up to 1. If you provide a single service, Alexa+ uses this service. If you return multiple services, Alexa+ attempts to select the service that best matches the request taking into consideration the confidence scores.

B: Alexa+-driven selection

You define your service categories and Alexa+ selects which categories apply to each customer request, based on a natural language description of your customer’s project. You can return a list of all services you support, regardless of the project description, and set the confidence score to 0 for each service. Alexa+ then selects one of the services you return, using a best effort to match the project description to the description of each service you offer. The confidence scores are defined in Service. The GetServices operation takes input GetServicesRequest and generates output GetServicesResponse.

Request

Parameter	Type	Description	Required
projectDescription	String	A short natural language summary of a customer’s project	Yes
zipCode	String	Customer’s zip code for location-based provider filtering	Yes
maxResults	Integer	Maximum number of services to return	No
nextToken	String	Pagination token for fetching subsequent pages	No

Response

A successful GetServicesResponse returns a ranked list of supported services available to service the customer’s project. If the response includes no services, Alexa+ interprets this response to indicate your services don’t support the customer’s project. If the response includes more than one service, Alexa+ selects the best matching service from the list. It considers the description of each service and the confidence values you provide. If the response includes a single service with a confidence score greater than 0.0, Alexa+ interprets this response to indicate that you can support the customer’s project and that the service included in the response is the best match for the request.

Parameter	Type	Description	Required
services	Array of Service objects	List of services matching the project description, ranked by confidence	Yes
paginationContext	PaginationContext	Pagination context for result sets	No

On error, the response returns one of the following error codes:

400 ValidationExceptionResponse
400 ClientErrorResponse
408 RequestTimeoutErrorResponse
429 RequestThrottlingErrorResponse
500 InternalServerErrorResponse

GetServiceSpecification

Path: /v1/homeservices/services/{serviceId}/specification
Method: GET
Type: Read-only
Account Linking: Not applicable
Applicable interaction patterns: Auto-Match and Browse and Choose Retrieves the specification for a given service. You can define a set of parameters associated with each service you support. Alexa+ uses this specification to ask the customer related questions needed to provide the required information to create a booking, or message a professional. This operation takes input GetServiceSpecificationRequest and generates output GetServiceSpecificationResponse.

Request

Parameter	Type	Description	Required
serviceId	String	The service ID corresponding to the one selected to handle the customer’s request, based on the response to the GetServices operation	Yes

Response

A successful GetServiceSpecificationResponse returns a set of parameters that are required when creating a booking, or messaging a professional related to the selected service ID.

Parameter	Type	Description	Required
serviceSpecification	ServiceSpecification	A set of questions and answers that are required for creating a booking or messaging a professional	Yes

On error, the response returns one of the following error codes:

400 ValidationExceptionResponse
400 ClientErrorResponse
408 RequestTimeoutErrorResponse
429 RequestThrottlingErrorResponse
500 InternalServerErrorResponse

CreateBooking

Path: /v1/homeservices/bookings
Method: POST
Type: Non-idempotent
Required Permissions: READ_MOBILE_NUMBER, READ_EMAIL, READ_FULL_NAME, READ_DEVICE_ADDRESS
Applicable interaction patterns: Auto-Match Creates a new service booking. This operation takes input CreateBookingRequest and generates output CreateBookingResponse.

Request

Represents a booking that may be in one of two stages: "ESTIMATE", or "CONFIRMATION". Alexa+ first sends a request to start a booking process and generates an estimate. You must return the estimated charges and any service charges associated with the request. Also include a list of payment instruments for the customer to pick from. Alexa+ shares the estimate and the service policies with the customer and allows the customer to select the payment instrument to use to complete the booking. After the customer has selected a payment instrument and confirmed the request, Alexa+ calls CreateBooking again, sets the BookingStage parameter to CONFIRMATION.

Parameter	Type	Description	Required
project	Project	Details about the project	Yes
alexaBookingId	String	Alexa-generated stable identifier for this booking request. Generated on ESTIMATE, reused on CONFIRMATION. Serves as idempotency key.	No
partnerBookingId	String	Partner-generated booking identifier. Absent on ESTIMATE requests. Present on CONFIRMATION requests — Alexa passes back the value you returned on the ESTIMATE response.	No
appointmentDateTime	String	Appointment date and time in RFC 3339 format with timezone, for example, ‘2023-12-25T14:30:00Z’ or ‘2023-12-25T14:30:00-08:00’	Yes
paymentInstruments	List (PaymentInstrument)	List of payment instruments	Yes
stage	BookingStage	Alexa sets this parameter to either `ESTIMATE` or `CONFIRMATION` depending on the stage of the request	Yes
userInfo	UserInfo	User contact information for the booking	Yes

Response

A successful CreateBookingResponse returns purchase details, booking stage, and booking details.

Parameter	Type	Description	Required
purchaseDetails	Purchase	Purchase-related information including charges, policies, and payment methods	No
stage	BookingStage	Alexa sets the parameter to `ESTIMATE` or `CONFIRMATION` depending on the stage of the request	Yes
booking	Booking	All booking information and related data	Yes
taskProgress	String	Optional task progress notification for WebAction implementations. Values: `GETTING_READY`, `GATHERING_INFO`, `HANG_TIGHT`, `FINALIZING`, `ALMOST_DONE`.	No

On error, the response returns one of the following error codes:

400 ValidationExceptionResponse
400 ClientErrorResponse
408 RequestTimeoutErrorResponse
429 RequestThrottlingErrorResponse
500 InternalServerErrorResponse

ListProfessionals

Path: /v1/homeservices/professionals
Method: POST
Type: Read-only
Applicable interaction patterns: Browse and Choose Lists professionals who offer services for the specified project request.

Request

Parameter	Type	Description	Required
zipCode	String	Zip code where the project needs to be completed	Yes
maxResults	Integer	Maximum number of professionals to return	No
nextToken	String	Pagination token for fetching subsequent pages	No
projectDescription	String	Description of the project	Yes
projectDetails	List(ProjectDetail)	Project information containing details about the service request	No
service	Service	Service context for the request	No

Response

A successful ListProfessionalsResponse returns a list of professional matching the search criteria, along with service information and pagination metadata.

Parameter	Type	Description	Required
service	Service	The matched service	Yes
professionals	Array of Professional objects	List of professionals available to provide the requested project in the specified area	Yes
paginationContext	PaginationContext	Pagination context for result sets	No

On error, the response returns one of the following error codes:

400 ValidationExceptionResponse
400 ClientErrorResponse
408 RequestTimeoutErrorResponse
429 RequestThrottlingErrorResponse
500 InternalServerErrorResponse

MessageProfessional

Path: /v1/homeservices/professionals/{professionalId}/message
Method: POST
Type: Non-idempotent
Required Permissions: READ_MOBILE_NUMBER, READ_EMAIL, READ_FULL_NAME, READ_DEVICE_ADDRESS
Applicable interaction patterns: Browse and Choose Sends a contact request message to a professional with project information.

Request

Parameter	Type	Description	Required
professionalId	String	Unique identifier of the professional to contact	Yes
name	String	Professional’s full name	Yes
businessUrl	String	URL to the professional’s business website	No
projectDescription	String	Description of the project	Yes
projectDetails	List(ProjectDetail)	Detailed information about project requirements and preferences	Yes
userInfo	UserInfo	User contact information for the professional to reach the user	Yes
service	Service	Service context for provider to re-derive search context at message time	Yes
zipCode	String	Customer zip code for geographic context	Yes

Response

A successful MessageProfessionalResponse returns HTTP 204 with no response body. On error, the response returns one of the following error codes:

400 ValidationExceptionResponse
400 ClientErrorResponse
408 RequestTimeoutErrorResponse
429 RequestThrottlingErrorResponse
500 InternalServerErrorResponse

GetUserInfo

Path: /v1/homeservices/users/current
Method: GET
Type: Read-only Applicable interaction patterns: Auto-Match and Browse and Choose Retrieves profile information for the currently authenticated user. This operation returns personal information from your system that the user has consented to share. This operation takes input GetUserInfoRequest and generates output GetUserInfoResponse.

Request

There is no request body.

Response

A successful GetUserInfoResponse returns the current user’s profile information.

Parameter	Type	Description	Required
name	String	User’s full name in their profile	No
address	Address	Physical address of the user	No
email	String	The user’s email address	No
phone	String	The user’s primary phone number in E.164 format, for example, +1234567890	No

On error, the response returns one of the following error codes:

400 ValidationExceptionResponse
400 ClientErrorResponse
408 RequestTimeoutErrorResponse
429 RequestThrottlingErrorResponse
500 InternalServerErrorResponse

GetBooking

Path: /v1/homeservices/bookings/{partnerBookingId}
Method: GET
Type: Read-only Retrieves an existing booking by the partner’s booking identifier, including current status and the professional assigned to it. This operation takes input GetBookingRequest and generates output GetBookingResponse.

Request

Parameter	Type	Description	Required
partnerBookingId	String	The partner-generated booking identifier returned in the CreateBooking ESTIMATE response	Yes

Response

A successful GetBookingResponse returns booking details including current status and professional assignment.

Parameter	Type	Description	Required
booking	Booking	Complete booking information	Yes

On error, the response returns one of the following error codes:

400 ValidationExceptionResponse
400 ClientErrorResponse
408 RequestTimeoutErrorResponse
429 RequestThrottlingErrorResponse
500 InternalServerErrorResponse

CancelBooking

Path: /v1/homeservices/bookings/{partnerBookingId}/cancel
Method: POST
Type: Non-idempotent Required Permissions: READ_MOBILE_NUMBER, READ_EMAIL, READ_FULL_NAME, READ_DEVICE_ADDRESS Cancels an existing booking using its unique identifier. The booking must be in a cancellable status including PENDING, CONFIRMED, ASSIGNED, or RESCHEDULED. Upon successful cancellation, the system updates the booking status to CANCELLED and releases any associated resources according to the cancellation policy. This operation takes input CancelBookingRequest and generates output CancelBookingResponse.

Request

Parameter	Type	Description	Required
partnerBookingId	String	The partner-generated booking identifier returned in the CreateBooking ESTIMATE response	Yes
cancellationReason	String	Justification for the booking cancellation. Required for customer service, professional feedback, and partner business intelligence purposes.	Yes
userInfo	UserInfo	User contact information for the cancelling customer, used to validate ownership and notify the customer	Yes

Response

A successful CancelBookingResponse returns booking ID and the latest status of the booking.

Parameter	Type	Description	Required
partnerBookingId	String	Partner-generated booking identifier (echoed from request)	Yes
status	BookingStatus	Updated booking status after the cancellation operation is completed. It should be CANCELLED upon successful cancellation.	Yes

On error, the response returns one of the following error codes:

400 ValidationExceptionResponse
400 ClientErrorResponse
408 RequestTimeoutErrorResponse
429 RequestThrottlingErrorResponse
500 InternalServerErrorResponse

ModifyBooking

Path: /v1/homeservices/bookings/{partnerBookingId}/modify
Method: POST
Type: Non-idempotent Required Permissions: READ_MOBILE_NUMBER, READ_EMAIL, READ_FULL_NAME, READ_DEVICE_ADDRESS Modifies an existing booking’s appointment date and time. The booking must be in a modifiable status including PENDING, CONFIRMED, ASSIGNED, or RESCHEDULED. Upon successful modification, the booking status might remain the same or be updated based on your requirements. This operation takes input ModifyBookingRequest and generates output ModifyBookingResponse.

Request

Parameter	Type	Description	Required
partnerBookingId	String	The partner-generated booking identifier returned in the CreateBooking ESTIMATE response	Yes
newAppointmentDateTime	String	New appointment date and time in RFC 3339 format with timezone, for example, ‘2023-12-25T14:30:00Z’ or ‘2023-12-25T14:30:00-08:00’. It must be in the future and within your acceptable scheduling window.	Yes
userInfo	UserInfo	User contact information for the modifying customer, used to validate ownership and notify the customer	Yes

Response

A successful ModifyBookingResponse returns partnerBookingId and the updated status of the booking.

Parameter	Type	Description	Required
partnerBookingId	String	Partner-generated booking identifier (echoed from request)	Yes
status	BookingStatus	Updated booking status after the modification operation is complete. It might remain unchanged or updated to reflect the modification, such as CONFIRMED, PENDING.	Yes

On error, the response returns one of the following error codes:

400 ValidationExceptionResponse
400 ClientErrorResponse
408 RequestTimeoutErrorResponse
429 RequestThrottlingErrorResponse
500 InternalServerErrorResponse

Components

Address

Physical address information for the service location.

Parameter	Type	Description	Required
addressLine1	String	Primary address line	No
addressLine2	String	Secondary address line	No
addressLine3	String	Tertiary address line	No
city	String	City	No
stateOrRegion	String	State or region	No
districtOrCounty	String	District or county	No
countryCode	String	Country code	No
postalCode	String	Postal code	No

Badge

Details of a badge (display element) that may be shown together with professional detail cards on Alexa devices with a screen.

Parameter	Type	Description	Required
name	String	Name or title of the badge, for example, Top Rated Pro, Licensed Contractor	Yes

Booking

Complete booking entity containing all booking and related data.

Parameter	Type	Description	Required
alexaBookingId	String	Alexa-generated unique identifier for every booking request	Yes
partnerBookingId	String	Partner-generated unique identifier for the booking request. It may be set to the same value as the `alexaBookingId`.	Yes
status	BookingStatus	Current booking status	Yes
project	Project	Alexa provides details about the project associated with this booking request	No
appointmentDateTime	String	Scheduled date and time for the service appointment in RFC 3339 format with timezone, for example, ‘2023-12-25T14:30:00Z’ or ‘2023-12-25T14:30:00-08:00’	Yes
cancellationPolicy	Policy	Your booking cancellation policy	No
additionalPolicies	List (Policy)	List of additional policies that apply to this booking	No
assignedProfessional	ProfessionalStub	Assigned professional, present only when a professional has been assigned to the booking	No

BookingStage

Stage of a booking request. A request starts as ESTIMATE — you must respond with estimated costs, policies, and payment instruments. Alexa+ presents these to the customer. After the customer confirms, the request transitions to CONFIRMATION.

Value	Description
`ESTIMATE`	Request for cost estimate, policies, and payment instruments
`CONFIRMATION`	Booking confirmation with selected payment instrument

BookingStatus

Current booking status.

Value	Description
`PENDING`	Booking request is pending
`CONFIRMED`	Booking has been confirmed
`IN_PROGRESS`	Booking is in progress
`COMPLETED`	Booking has been completed
`ASSIGNED`	Professional has been assigned to the booking
`CANCELLED`	Booking has been cancelled
`RESCHEDULED`	Booking has been rescheduled

Charge

Specific charge or fee associated with a service booking.

Parameter	Type	Description	Required
chargeDescription	String	Description of what this charge covers	Yes
chargeCategory	ChargeCategory Enum	Category of the charge. Values: `SERVICE`, `MATERIAL`, `LABOR`, `TAX`, `FEE`, `OTHER`.	Yes
amount	MonetaryValue	Monetary value representation	Yes

Constraint

Defines constraints for a form field, such as a regular expression defining the acceptable format, or an enumeration of allowable values.

Parameter	Type	Description	Required
dataType	String	Data type enum. Accepted values: `STRING`: Free-form text value `INTEGER`: Whole number value `FLOAT`: Decimal floating-point value `BOOLEAN`: True/false value `DATE`: Calendar date value `CURRENCY`: Monetary/currency value (exact decimal) `TIME`: Time-of-day value `URI`: URI/URL value	Yes
selectionType	String	Selection type enum. Accepted values: `RADIO`: Single selection from a list (radio buttons) `CHECKBOX`: Multiple selection from a list (checkboxes) `TEXT`: Free-form text input `DROPDOWN`: Single selection from a dropdown menu	Yes
regexPattern	String	A regular expression constraint that describes allowed format for a form field	No
minLength	Integer	Minimum length allowed for a form field	No
maxLength	Integer	Maximum length allowed for a form field	No
options	List(ValueConstraint)	List of available options for selection fields	No

Condition

Conditional display logic for form fields.

Parameter	Type	Description	Required
fieldName	String	Field name to check condition against	Yes
equalsValue	String	Value that must match for condition to be true	Yes

CostEstimate

Cost estimation information for the requested project, including pricing range and unit type.

Parameter	Type	Description	Required
min	MonetaryValue	Minimum cost	Yes
max	MonetaryValue	Maximum cost (only for RANGE type)	No
costUnit	CostUnit	How cost estimate is interpreted and what unit it represents	Yes

CostUnit

Defines how the cost estimate should be interpreted and what unit it represents.

Parameter	Type	Description	Required
type	Enum of strings	Enumeration of different cost unit types for project pricing (MIN, HOURLY, FLAT, RANGE, OTHER)	Yes
description	String	Custom description of the cost unit. It is only used when type is OTHER.	No

CreditCardDetails

Detailed information about a credit card, containing sensitive payment data.

Parameter	Type	Description	Required
last4	String	Last 4 digits of the payment instrument number	Yes
network	String	Payment network of the payment instrument, for example, Visa, Mastercard, Amex.	Yes
expirationYear	Integer	Expiration year, for example, 2026.	No
expirationMonth	Integer	Expiration month from 1-12.	No

FormField

Defines one form field for collecting a parameter for a ServiceSpecification associated with a service. Each FormField enables you to define one unique question applicable to your service that needs to be answered by the customer. For example, for house cleaning services, you can define a FormField to collect information about number of bathrooms. You can have another FormField to define the cleaning type that accepts one of the following possible values: “Standard”, “Deep Cleaning”, “Move-out Cleaning”.

Parameter	Type	Description	Required
name	String	Name of the field. Must be unique on the form. Used to reference this field in Condition logic.	Yes
id	String	Your stable identifier for this form field. If your system assigns persistent IDs to form questions, set this value so that Alexa+ can map customer answers back to your internal question without relying on `name`.	Yes
errorMessage	String	Error message to display for validation failures	No
text	String	Display text for the parameter, for example “Cleaning Type”	Yes
isRequired	Boolean	Indicates whether Alexa must provide a value for this parameter	Yes
defaultValue	String	Default value for the parameter	No
groupName	String	Group name for related parameters, for example, “Service details questions”	No
condition	Condition	Condition for conditional field display	No
constraints	List(Constraint)	List of constraints, such as min/max value, or allowable values for the parameter	No

MonetaryValue

Monetary value representation.

Parameter	Type	Description	Required
currencyCode	String	3-letter currency code as specified by ISO-4217, for example, ‘USD’.	Yes
value	String	String containing a decimal representing the major unit, for example, ‘1.23’ represents 1 dollar & 23 cents. Max length is 128 characters.	Yes

PaymentInstrument

Payment instrument information including type, identifier, and detailed payment data.

Parameter	Type	Description	Required
paymentInstrumentType	Enumeration of strings	Type of payment instrument. Values: `CARD` (credit or debit card), `AMAZONPAY` (Amazon Pay).	Yes
paymentInstrumentId	String	Human-readable identifier for the payment instruments, for example, Visa `**** 1234`.	Yes
wallet	String	Wallet identifier or name associated with this payment instrument.	Yes
paymentInstrumentDetails	PaymentInstrumentDetails	Detailed payment instrument information. Optional because some partners surface limited card data.	No

PaymentInstrumentDetails

Detailed payment instrument information.

Parameter	Type	Description	Required
creditCard	CreditCardDetails	Credit card details	No

Policy

Business policy defining terms and conditions for service bookings.

Parameter	Type	Description	Required
policyDescription	String	Human-readable description of policy terms and conditions	Yes
policyType	Enumeration of strings	Enumeration of the following strings: CANCELLATION, RESCHEDULING	Yes
policyUrl	String	URL to detailed policy page with full terms and conditions	No

Professional

Represents a service professional with their business information, ratings, and service details.

Parameter	Type	Description	Required
name	String	The professional’s full name	Yes
id	String	Unique identifier for the professional in the system	Yes
rating	Number	Professional’s average rating from customer reviews (0.0 to 5.0). If there’s no review, set the value to 0.	Yes
numReviews	Integer	Total number of customer reviews received for this professional	Yes
description	String	Professional’s description or bio	No
businessUrl	String	URL to the professional’s business website	No
photoUrl	String	URL to the professional’s profile photo or business logo	No
numProjects	Integer	Total number of completed projects by this professional	No
badges	List(Badge)	Professional certifications and achievement badges	No
costEstimate	CostEstimate	Cost estimate for the project	No
responseTimeHours	Integer	Typical response time in hours	No
reviews	List(Review)	Customer reviews for this professional	No

ProfessionalStub

Lighter representation used inside Booking.assignedProfessional. Has the same required fields as Professional (name, id, rating, numReviews) and the optional businessUrl, photoUrl, numProjects, badges — but omits description, costEstimate, responseTimeHours, and reviews.

Project

Project information containing details about the service request.

Parameter	Type	Description	Required
projectId	String	Unique identifier for the project	No
projectDescription	String	Description of the project and service requirements	Yes
address	Address	Address for the service request	Yes
projectDetails	List(ProjectDetail)	Detailed information about project requirements and preferences	Yes
service	Service	Service information for describing different types of home services you offer	Yes

ProjectDetail

Project detail represents a specific aspect of the service request, for example, number of rooms, number of floors, appliance brand.

Parameter	Type	Description	Required
formFieldId	String	References the FormField.id from the service specification this answer corresponds to	Yes
description	String	Human-readable description of what this project detail represents. For example, it might represent a question asked by the Home Services provider, such as number of rooms, number of floors, appliance brand.	No
selectedValues	List(String)	User’s selected values or preferences for the project detail	Yes

Purchase

Complete purchase entity containing all purchase-related information including charges, policies, and payment methods.

Parameter	Type	Description	Required
charges	List(Charge)	List of all charges associated with this purchase	No
policies	List(Policy)	List of policies that apply to this purchase	No
paymentInstruments	List(PaymentInstrument)	List of payment instruments available for this purchase	No

PaginationContext

Pagination metadata returned in responses that support paginated result sets.

Parameter	Type	Description	Required
nextToken	String	Token for fetching the next page of results. Absent when there are no more pages.	No
totalCount	Integer	Total number of items available across all pages	No

Review

Individual customer review with rating, text, and reviewer information.

Parameter	Type	Description	Required
rating	Number	Customer rating for this specific review on a scale of 1.0 to 5.0	Yes
reviewerName	String	Name of the customer who left the review	Yes
text	String	The review text content describing the customer’s experience	Yes
timestamp	String	The review submission time (ISO 8601)	Yes

Service

Service information for describing different types of home services you offer.

Parameter	Type	Description	Required
id	String	Unique identifier for the service offered by you	Yes
name	String	User-friendly name of the service, for example, “House Cleaning”	Yes
description	String	Detailed description of the service. Used for selection when multiple services are returned.	Yes
confidence	Float	A value from 0.0 to 1.0 that represents how well this service matches a customer’s project. 0 means Alexa+ will automatically select best matching service based on the customer’s natural language description. For details, see B: Alexa+-driven selection. A score of 0.1-0.9 partially influences Alexa+‘s selection, with higher score having stronger influence. A score of 1 strongly suggests the service is the best match. For details, see A: Partner-driven selection.	No
matchingStrategies	Array of String	Service matching strategies supported for this service. Values: `BROWSE_AND_CHOOSE` (customer browses and selects a professional), `AUTO_MATCH` (system automatically matches customer with a professional). Defaults to `[BROWSE_AND_CHOOSE]` if omitted.	No

ServiceSpecification

Defines a set of parameters that need to be collected when customers book a service, or message a professional for a given service type.

Parameter	Type	Description	Required
service	Service	Details that describe various types of home services you offer	Yes
fields	List(FormField)	A collection of form fields that customers need to provide when booking a service or messaging a service professional. Each form field captures one parameter for the service. Amazon requires that you provide all parameters as List in a single request for each service. For example, for the house cleaning service, you can define a list of FormFields that collect parameters, such as number of bedrooms, number of bathrooms, square footage, whether there are pets, recurring service or not.	Yes

ValueConstraints

Defines a permitted value for a constrained parameter, similar to a value defined in enumerations.

Parameter	Type	Description	Required
value	String	Internal value passed to an API, for example, “standard” or “deep”	Yes
label	String	The display text shown on the screen or spoken through Text-to-Speech (TTS), for example, “standard cleaning”, or “deep cleaning”	Yes
id	String	Your stable identifier for this option. If your system assigns persistent IDs to answer choices, set this value so that Alexa+ can map the customer’s selection back to your internal option.	No

UserInfo

User contact information.

Parameter	Type	Description	Required
name	String	User’s full name	No
email	String	User’s email address	No
phone	String	User’s phone number	No
address	Address	User’s address	No

Errors

All error responses share a common structure with errorType, errorCode, and message fields.

Error response example

{
  "errorType": "CLIENT_ERROR",
  "errorCode": "NO_ACCOUNT_LINKED_ERROR",
  "message": "The user doesn't have a linked account"
}

Error codes

HTTP status	Error	When
400	ValidationException	The request contains malformed or missing required fields
400	ClientError (NO_ACCOUNT_LINKED_ERROR)	The user doesn’t have a linked account with your service
400	ClientError (INVALID_ZIP_CODE_ERROR)	The provided zip code isn’t valid or isn’t in your service area
400	ClientError (NO_PROFESSIONAL_ERROR)	No professionals are available for the request
400	ClientError (INVALID_PROFESSIONAL_ERROR)	The specified professional ID isn’t valid
400	ClientError (BOOKING_NOT_FOUND_ERROR)	Booking ID does not exist
400	ClientError (BOOKING_CANCELLATION_FAILED_ERROR)	Cancellation operation failed
400	ClientError (BOOKING_CANCELLATION_NOT_ALLOWED_ERROR)	Booking is not in a cancellable state
400	ClientError (BOOKING_MODIFICATION_FAILED_ERROR)	Modification operation failed
400	ClientError (BOOKING_MODIFICATION_NOT_ALLOWED_ERROR)	Booking is not in a modifiable state
400	ClientError (MISCELLANEOUS_ERROR)	A client-side error that doesn’t fit other categories
408	RequestTimeoutError	You didn’t respond within the required time limit
429	RequestThrottlingError	Rate limit exceeded
500	InternalServerError	Unexpected error on your side

Create a Category Add-on Manually with the CLI

​Namespace

​Interaction patterns

​Discovery Patterns

​Browse and Choose (Customer-led)

​Auto-Match (Platform-led)

​Account-Management Patterns

​Account Linking

​Automatic Account Matching

​Booking Patterns

​Messaging

​Operations

​GetServices

​A: Partner-driven selection

​B: Alexa+-driven selection

​Request

​Response

​GetServiceSpecification

​Request

​Response

​CreateBooking

​Request

​Response

​ListProfessionals

​Request

​Response

​MessageProfessional

​Request

​Response

​GetUserInfo

​Request

​Response

​GetBooking

​Request

​Response

​CancelBooking

​Request

​Response

​ModifyBooking

​Request

​Response

​Components

​Address

​Badge

​Booking

​BookingStage

​BookingStatus

​Charge

​Constraint

​Condition

​CostEstimate

​CostUnit

​CreditCardDetails

​FormField

​MonetaryValue

​PaymentInstrument

​PaymentInstrumentDetails

​Policy

​Professional

​ProfessionalStub

​Project

​ProjectDetail

​Purchase

​PaginationContext

​Review

​Service

​ServiceSpecification

​ValueConstraints

​UserInfo

​Errors

​Error response example

​Error codes

​Related topics

Namespace

Interaction patterns

Discovery Patterns

Browse and Choose (Customer-led)

Auto-Match (Platform-led)

Account-Management Patterns

Account Linking

Automatic Account Matching

Booking Patterns

Messaging

Operations

GetServices

A: Partner-driven selection

B: Alexa+-driven selection

Request

Response

GetServiceSpecification

Request

Response

CreateBooking

Request

Response

ListProfessionals

Request

Response

MessageProfessional

Request

Response

GetUserInfo

Request

Response

GetBooking

Request

Response

CancelBooking

Request

Response

ModifyBooking

Request

Response

Components

Address

Badge

Booking

BookingStage

BookingStatus

Charge

Constraint

Condition

CostEstimate

CostUnit

CreditCardDetails

FormField

MonetaryValue

PaymentInstrument

PaymentInstrumentDetails

Policy

Professional

ProfessionalStub

Project

ProjectDetail

Purchase

PaginationContext

Review

Service

ServiceSpecification

ValueConstraints

UserInfo

Errors

Error response example

Error codes

Related topics