Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Category SDK
MCP toolkit
Certify
Resources
Skip to main content
This document outlines the Service Provider Interface (SPI) for Ticketing within the Category SDK framework. The SPI defines the contract that you must implement to integrate with Alexa+.

Namespace

The namespace for the Ticketing SPI is com.amazon.alexa.ticketing.v1.

Operations

The Ticketing 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.
OperationPathHTTP methodTypeRequires permissions
ConfirmTicket/v1/events/{eventId}/cart/{cartId}/confirmPOSTNon-idempotentREAD_MOBILE_NUMBER, READ_EMAIL, READ_FULL_NAME, AUTOPAY
GetEventDetails/v1/events/{eventId}GETRead-only—
GetOrderSummary/v1/orders/{orderId}GETRead-only—
GetSeatDetails/v1/events/{eventId}/seatsGETRead-only—
ReleaseTicket/v1/events/{eventId}/cart/{cartId}DELETEIdempotent—
ReserveTicket/v1/events/{eventId}/cartPOSTNon-idempotentREAD_MOBILE_NUMBER, READ_EMAIL, READ_FULL_NAME, AUTOPAY
SearchEvents/v1/events/searchGETRead-only—
SearchVenues/v1/venues/searchPOSTNon-idempotent—

Common request headers

Every operation in the Ticketing SPI includes the following HTTP headers. These are sent by Alexa+ and available in the request context.
HeaderTypeDescriptionRequired
requestIdStringUnique identifier for the request to help with tracking and debuggingNo
timestampTimestampIndicates when the request was initiated. Format: RFC 3339 date-time.No
localeStringThe preferred language for the response content following RFC 5646 format, for example, en-USNo
applicationIdStringIdentifier of the Alexa application making the requestNo
userIdStringUnique identifier of the end user making the request. This field is sensitive and must not be exposed in exception messages or log output.No
userAccessTokenStringAuthentication 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

ConfirmTicket

Path: /v1/events/{eventId}/cart/{cartId}/confirm
Method: POST
Type: Non-idempotent
Required Permissions: READ_MOBILE_NUMBER, READ_EMAIL, READ_FULL_NAME, AUTOPAY
Confirms and completes the ticket purchase. Processes payment and returns the order confirmation. Providers MUST ensure idempotency — confirming an already-confirmed cartId returns the original order rather than processing a duplicate payment. This operation takes input ConfirmTicketRequest and generates output ConfirmTicketResponse.

Request

ParameterTypeDescriptionRequired
cartIdStringUnique identifier of the cartYes
eventIdStringUnique identifier of the eventYes
paymentPaymentPayment information for ticket purchaseYes
userUserUser information for ticket purchaseYes

Response

A successful ConfirmTicketResponse returns order ID, total cost, and wait time to check the status of the booking.
ParameterTypeDescriptionRequired
orderIdStringUnique identifier of the orderYes
grandTotalDoubleTotal cost for the ticketYes
waitTimeIntegerNumber of seconds to wait before checking the status of the bookingNo
On error, the response returns one of the following error codes: • EventNotFoundError (404): Event does not exist • SeatNotAvailableError (409): Requested seats not available • ValidationException (400): Invalid request parameters • InternalServerError (500): Internal server error • RequestThrottlingError (429): Too many requests • RequestTimeoutError (408): Request timeout • PaymentProcessorError (502): Payment processor unavailable or error • PaymentFailureError(400): Payment processing failed • InvalidPaymentDetailsError(400): Invalid payment details • CartNotFoundError(404): Cart doesn’t exist • CartExpiredError(410): Cart reservation has expired

GetEventDetails

Path: /v1/events/{eventId}
Method: GET
Type: Read-only
Returns full details of a selected event including venue, pricing, attraction info, and inventory mode. The inventoryMode field determines the next step: RESERVED → call GetSeatDetails, GENERAL_ADMISSION → select from event.offers directly. This operation takes input GetEventDetailsRequest and generates output GetEventDetailsResponse.

Request

ParameterTypeDescriptionRequired
eventIdStringUnique identifier for the eventYes

Response

A successful GetEventDetailsResponse returns event details. The inventoryMode field determines the booking path: RESERVED → call GetSeatDetails for seat selection, GENERAL_ADMISSION → select from event.offers directly.
ParameterTypeDescriptionRequired
eventEventEvent represents a concert, sports event, theater show, or a single movie showtimeYes
On error, the response returns one of the following error codes: • EventNotFoundError (404): Event does not exist • ValidationException (400): Invalid request parameters • InternalServerError (500): Internal server error • RequestThrottlingError (429): Too many requests • RequestTimeoutError (408): Request timeout

GetOrderSummary

Path: /v1/orders/{orderId}
Method: GET
Type: Read-only
Returns order status and ticket details for a completed purchase. Includes booking information with event, seat, and user details. This operation takes input GetOrderSummaryRequest and generates output GetOrderSummaryResponse.

Request

ParameterTypeDescriptionRequired
orderIdStringUnique identifier for the orderYes

Response

A successful GetOrderSummaryResponse returns order ID, order status, and ticket info.
ParameterTypeDescriptionRequired
orderIdStringUnique identifier for the orderYes
orderStatusOrderStatusOrder status such as reserved, confirmed, cancelled, or expiredYes
orderStatusReasonStringReason for the order statusNo
ticketTicketComplete ticket information including event, seat, and user detailsYes
On error, the response returns one of the following error codes: • ValidationException (400): Invalid request parameters • InternalServerError (500): Internal server error • RequestThrottlingError (429): Too many requests • RequestTimeoutError (408): Request timeout • OrderNotFoundError(404): Order does not exist

Components

Address

Physical address with optional fields for international support.
ParameterTypeDescriptionRequired
addressLine1StringFirst line of the address. The maximum length is 50 characters.Yes
addressLine2StringSecond line of the address. The maximum length is 50 characters.No
addressLine3StringThird line of the address. The maximum length is 50 characters.No
countryCodeStringISO 3166-1 alpha-2 country code. The maximum length is 2 characters.Yes
stateOrRegionStringState or region. The maximum length is 50 characters.Yes
cityStringName of the city. The maximum length is 50 characters.Yes
districtOrCountyStringDistrict or county. The maximum length is 50 characters.No
postalCodeStringPostal or zip code. The maximum length is 12 characters.Yes

Artist

Artist or cast member in a movie or show.
ParameterTypeDescriptionRequired
nameStringActual name of the artist. The maximum length is 256 characters.Yes
aliasStringScreen name or stage alias of the artist. The maximum length is 256 characters.No
roleStringRole in the movie, for example, director, actor, producer, lead. The maximum length is 256 characters.No

AttractionDetails

Union of attraction types — one of the following must be set (mutually exclusive).
ParameterTypeDescriptionRequired
performancePerformanceAttractionPerformance attraction for concerts, sports, theater, comedy, and more. Set this field for live events.Yes (one required)
movieMovieAttractionMovie attraction for film showtimes. Set this field for movies.Yes (one required)

Cart

A temporary hold on selected tickets before purchase confirmation.
ParameterTypeDescriptionRequired
cartIdStringUnique identifier of the cartYes
ticketItemsList(TicketItem)Ticket item details added to the cart for the event. Maximum 10 elements.Yes
totalTotalTotal cost for all items in the cartYes
lastUpdatedTimestampTimestampTimestamp in ISO 8601 format in UTC when the cart was last updated. The format is date-time. For example, 2025-11-17T14:30:00ZNo

Charge

Charge or fee applied to a ticket.
ParameterTypeDescriptionRequired
typeStringType of charge, for example, service_fee, processing_fee, or facility_fee. The maximum length is 50 characters.Yes
amountDoubleAmount of the charge. The amount must be non-negative.Yes
descriptionStringDescription of the charge. The maximum length is 256 characters.No

Event

Event represents a concert, sports event, theater show, or a single movie showtime. The inventoryMode field determines the booking path: RESERVED → call GetSeatDetails for seat selection, GENERAL_ADMISSION → select from event.offers directly.
ParameterTypeDescriptionRequired
idStringUnique showtime ID for a movie and event ID for concerts or sports eventsYes
nameStringActual name of an event or a movie, the minimum length is 1 and maximum length is 256 characters.Yes
startDateTimeTimestampMovie showtime start timestamp and event start timestamp in ISO 8601 format in UTC. For example, 2025-11-17T14:30:00ZYes
timezoneStringIANA timezone identifier when available from the provider, for example, America/New_York. Otherwise a UTC offset string, for example, -07:00.Yes
venueVenueWhere the event is taking placeYes
priceRangesList(PriceRange)Available price ranges for the event. Maximum 5 elements.Yes
attractionAttractionDetailsAttraction details — type-specific information about the event contentYes
inventoryStatusStringCurrent inventory status for the event. One of: AVAILABLE, FEW_LEFT, SOLD_OUT, OFF_SALE, CANCELED, POSTPONED, RESCHEDULED.No
inventoryModeStringInventory mode for this event. One of: RESERVED (specific seats must be selected), GENERAL_ADMISSION (no seat selection; quantity only). Absent for providers that don’t distinguish.No
offersList(Offer)Available offers for this event (for example, Adult, Senior, or Child tickets with offerId and pricing). Used by the general admission flow to select an offer without calling GetSeatDetails. Maximum 10 elements.No

EventCategory

Enumerated list of event categories, such as music, sports, and film.
ParameterTypeDescription
MUSICStringMusic events including concerts and festivals
SPORTSStringSports events and games
ARTS_THEATREStringArts and theater including plays, comedy shows, magic shows
FILMStringFilm and movie showtimes

EventClassification

Event classification including category, genre, and sub-genre.
ParameterTypeDescriptionRequired
categoryEventCategoryPrimary event category. Determines the AttractionDetails union branch (FILM → MovieAttraction, others → PerformanceAttraction) and provider routing.Yes
genreStringGenre of the event, for example, rock, basketball, drama, actionNo
subGenreStringSub-genre for more specific classification, for example, alternative rock, NBA, musical comedyNo

Fee

Fee applied to the purchase.
ParameterTypeDescriptionRequired
nameStringName of the fee, such as service fee or convenience fee. The maximum length is 50 characters.Yes
valueDoubleAmount of the fee. It must be non-negativeYes

GeneralInfo

General information and rules about the venue.
ParameterTypeDescriptionRequired
generalRuleStringGeneral rules and policies for the venue. The maximum length is 100 characters.No
childRuleStringRules and policies specific to children. The maximum length is 100 characters.No
accessibilityStringAccessibility information for the venue. The maximum length is 100 characters.No
additionalNotesStringAdditional information about the venue. The maximum length is 100 characters.No

Image

An image with optional content description for accessibility.
ParameterTypeDescriptionRequired
contentDescriptionStringContent description for accessibility purposes. The maximum length is 512 characters.No
sourcesList(ImageInstance)Available image sources. Maximum 5 elements.Yes

ImageInstance

URL for the image.
ParameterTypeDescriptionRequired
urlURLThe URL for the image. The URL must start with https and follow the regex pattern of ^https://[^\s/$.?#][^\s]*$.Yes

Media

Media content containing images and trailers for events and movies.
ParameterTypeDescriptionRequired
imagesList(Image)List of images for the event or movie. Maximum 10 elements.No
trailersList(Video)List of trailer videos. Maximum 10 elements.No

MovieAttraction

Movie attraction for film showtimes.
ParameterTypeDescriptionRequired
idStringAttraction ID — movie ID or event tour ID or event series ID.Yes
nameStringAttraction name — movie title or event tour name or event series name. The acceptable string length is from 1 to 256.Yes
classificationEventClassificationClassification of the attractionYes
durationMinsIntegerDuration in minutes. The minimum is one minute.Yes
descriptionStringSynopsis or description of the attraction. The maximum length is 512 characters.No
mediaMediaMedia content including images and trailers.No
artistsList(Artist)Cast and crew of the movie. Maximum 20 elements.Yes
advisoryRatingStringContent advisory rating, for example, G, PG, PG-13, R, NC-17. The maximum length is 10 characters.Yes

Offer

A purchasable ticket type at a specific price point with fee breakdown (for example, Adult, Child, Senior).
ParameterTypeDescriptionRequired
offerIdStringUnique identifier for the offerYes
nameStringName of the offer. The maximum length is 50 characters.Yes
ticketTypeStringLabel indicating the ticket type or category, for example, Child, Senior, Adult, or General. The maximum length is 50 characters.No
descriptionStringDescription of the offer. The maximum length is 256 characters.No
currencyCodeCurrencyCodeCurrency code for the offer. Must match the regex ^[A-Z]{3}$ and comply with ISO 4217 three-letter currency code, such as USD, EUR, GBPYes
faceValueDoubleFace value of the ticket. The value must be non-negativeYes
totalPriceDoubleTotal price including all chargesYes
chargesList(Charge)List of charges applied to this offer. Maximum 10 elements.Yes

OrderStatus

Enumeration of the following: RESERVED, CONFIRMED, CANCELLED, EXPIRED.
ParameterTypeDescription
RESERVEDStringOrder is reserved but not yet confirmed
CONFIRMEDStringOrder is confirmed and payment processed
CANCELLEDStringOrder is cancelled
EXPIREDStringOrder reservation is expired

Payment

Payment information for ticket purchases.
ParameterTypeDescriptionRequired
typeStringType of payment method, such as credit_card, debit_card, or digital_walletYes
amountDoublePayment amount. Minimum amount is 0.01Yes
paymentInstrumentPaymentInstrumentPayment instrument detailsNo
paymentProcessorStringName of the payment processor handling the transactionNo
externalPaymentNonceStringExternal payment nonce for tokenized paymentsNo
paymentNonceTypeStringType of payment nonce usedNo

PaymentInstrument

Payment instrument containing card or payment method details. This information is marked as sensitive information with added security measures.
ParameterTypeDescriptionRequired
paymentMethodTokenStringExternal token generated using Banyan3pPaymentProviderYes
expiryMonthIntegerExpiry month of the payment method. Acceptable values are from 1–12Yes
expiryYearIntegerExpiry year of the payment method, for example, 2028. Acceptable range is from 2024 to 2099.Yes
issuerStringCard issuer or payment method provider, for example, Visa or Mastercard. The maximum length is 100 characters.Yes

PerformanceAttraction

Performance attraction for concerts, sports, theater, comedy, and other live events.
ParameterTypeDescriptionRequired
idStringAttraction ID — movie ID or event tour ID or event series ID.Yes
nameStringAttraction name — movie title or event tour name or event series name. The acceptable string length is from 1 to 256.Yes
classificationEventClassificationClassification of the attraction.Yes
durationMinsIntegerDuration in minutes. The minimum is one minute.Yes
descriptionStringSynopsis or description of the attraction. The maximum length is 512 characters.No
mediaMediaMedia content including images and trailers.No

PriceRange

Price range for an event, with optional per-type price breakdown.
ParameterTypeDescriptionRequired
currencyCodeCurrencyCodeCurrency code for the price range. It needs to comply with ISO 4217 three-letter currency code, such as USD, EUR, GBP.Yes
minDoubleMinimum price across all ticket types. It must be non-negative.Yes
maxDoubleMaximum price across all ticket types. It must be non-negative.Yes
ticketTypePricesList(TicketTypePrice)Per-type price breakdown, for example, Adult = 14.39, Senior = 13.19. Maximum 10 elements.No

SearchEventSummary

A search result entry representing one attraction playing at one venue, with all upcoming showtimes.
ParameterTypeDescriptionRequired
attractionAttractionDetailsThe attraction details (performance or movie)Yes
venueVenueThe venue hosting the attractionYes
showtimesList(Showtime)All upcoming showtimes for this attraction at this venue. Maximum 30 elements.Yes

Seat

Individual seat in a venue.
ParameterTypeDescriptionRequired
idStringUnique identifier for the seatYes
nameStringSeat number or identifier, such as 11, 22A. The maximum length is 5 characters.Yes
typeStringType of seat, including companion, wheelchair, standard, noseat, loveseatleft, loveseatright for layout. The maximum length is 20 characters.No
isAvailableBooleanWhether the seat is availableYes
accessibilityDisabilityAccommodationsList(String)List of accessibility and disability accommodations for this seat. Maximum 10 elements.Yes

SeatChoice

A selectable grouping of seats presented as one option to the user, bundling section + row + seats + offers.
ParameterTypeDescriptionRequired
idStringUnique identifier for this seat choice optionYes
seatingTypeStringSeating type. One of: RESERVED, OPEN, STANDARD. Indicates whether the choice is for specific reserved seats or open/GA.Yes
sectionStringSection at the venue, for example, Section1 for concerts, Screen-7 for movies. The maximum length is 50 characters.Yes
rowStringRow identifier such as A, B, C, BALCONY. The maximum length is 10 characters.Yes
offersList(Offer)List of offers available for this seat choice, supporting multiple ticket types, for example, Matinee, Child, Senior, Adult. Maximum 10 elements.Yes
seatsList(Seat)List of individual seats included in this choice for reserved seatingNo
seatMapSnapshotUrlURLURL to the seat map image. Must match the regex ^https://[^\s/$.?#][^\s]*$.No

SelectedOffer

An offer selected by the user during ticket reservation. Either seatIds (for reserved seating) or quantity (for general admission) must be provided, but not both.
ParameterTypeDescriptionRequired
offerIdStringIdentifier of the offer being selectedYes
seatIdsList(String)For reserved seating: the IDs of seats selected under this offer. Mutually exclusive with quantity. Maximum 10 elements.No
quantityIntegerFor general admission: the number of tickets under this offer. Mutually exclusive with seatIds.No

Showtime

A showtime of an event at a venue.
ParameterTypeDescriptionRequired
eventIdStringUnique identifier for this specific showtime, used when reserving ticketsYes
startDateTimeStringISO 8601 local date-time string for when the showtime starts, for example, 2025-10-02T18:00:00Yes
timezoneStringIANA timezone identifier when available, for example, America/Los_Angeles. Otherwise a UTC offset string, for example, -07:00.Yes
screenTypeStringScreen or format type for movie showtimes, for example, IMAX, 4DX, DOLBY, STANDARDNo
inventoryStatusStringCurrent inventory status for this showtime. One of: AVAILABLE, FEW_LEFT, SOLD_OUT, OFF_SALE, CANCELED, POSTPONED, RESCHEDULED.No
inventoryModeStringInventory mode for this showtime. One of: RESERVED (specific seats must be selected), GENERAL_ADMISSION (no seat selection, quantity only). Consumers use this to decide between seatIds and quantity on SelectedOffer.No
priceRangesList(PriceRange)Price ranges available for this specific showtime. Maximum 5 elements.No

Tax

Individual tax applied to the purchase.
ParameterTypeDescriptionRequired
nameStringName of the tax, such as sales tax or VAT. The maximum length is 50 characters.Yes
valueDoubleTax amount. It must be non-negative.Yes

Ticket

Details about the ticket information including event, seat, and user details.
ParameterTypeDescriptionRequired
eventEventEvent for which the ticket is purchased.Yes
selectedSeatChoiceSeatChoiceOne possible seating combination that is available for selection.Yes
userUserTicket purchaser.Yes

TicketItem

Details about the individual ticket item in the cart.
ParameterTypeDescriptionRequired
eventIdStringShowtime ID for a movie or event ID for a concert.Yes
selectedSeatChoiceSeatChoiceOne possible seating combination that is available for selection.Yes
totalTotalTotal cost for this ticket item.Yes

TicketTypePrice

Price for a specific ticket type.
ParameterTypeDescriptionRequired
typeStringTicket type. Common values include ADULT, SENIOR, CHILD, STANDARD, PREMIUM, GENERAL. You can also define custom values specific to your services.Yes
priceDoublePrice for this ticket type. It must be non-negative.Yes

Total

Total cost breakdown for tickets.
ParameterTypeDescriptionRequired
merchandiseDoubleTotal merchandise cost. It must be non-negative.Yes
feesList(Fee)List of fees applied. Maximum 10 elements.Yes
taxesList(Tax)List of taxes applied. Maximum 10 elements.Yes
grandDoubleThe grand total. It must be non-negative.Yes
currencyCodeCurrencyCodeCurrency code for the total. It needs to comply with ISO 4217 three-letter currency code, such as USD, EUR, GBP.Yes

User

User information for ticket purchase. User information is treated as sensitive information with added security measures.
ParameterTypeDescriptionRequired
firstNameStringFirst name of the user, with string length from 1 to 100.Yes
lastNameStringLast name of the user, with string length from 1 to 100.Yes
emailAddressStringValid email address of the user. Must match the regex ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$.Yes
addressAddressMailing address of the user.No
phoneStringValid phone number of the user in E.164 format. Must match the regex ^\+[1-9]\d{6,14}$. Minimum length: 8 characters. Maximum length: 16 characters.No

Venue

Where the event happens (theater for movies, concert hall for concerts).
ParameterTypeDescriptionRequired
idStringUnique identifier for the venue.Yes
nameStringName of the venue. The maximum length is 200 characters.Yes
addressAddressPhysical address of the venue.Yes
generalInfoGeneralInfoGeneral information and rules about the venue.No
latDoubleLatitude of the venue in decimal degrees.No
longDoubleLongitude of the venue in decimal degrees.No
imageUrlStringURL for the venue’s display image.No
distanceMilesDoubleDistance from the search center in miles. Populated in search responses.No

Video

Available video source with an optional content description for accessibility.
ParameterTypeDescriptionRequired
contentDescriptionStringContent description for accessibility purposes. The maximum length is 512 characters.No
sourcesList(VideoInstance)Available video sources. Maximum 5 elements.Yes

VideoInstance

A URL for the video.
ParameterTypeDescriptionRequired
urlURLThe URL that points to the video resource. The URL must start with https and follow the regex pattern of ^https://[^\\s/$.?#][^\\s]*$.Yes

ValidationExceptionField

Describes one specific validation failure for an input member.
ParameterTypeDescriptionRequired
pathStringA JSONPointer expression to the structure member whose value failed to satisfy the modeled constraints.Yes
messageStringA detailed description of the validation failure.Yes

Errors

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

Error response example

Error codes

Last modified on July 21, 2026