Namespace
The namespace for the Ticketing SPI iscom.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.| Operation | Path | HTTP method | Type | Requires permissions |
|---|---|---|---|---|
| ConfirmTicket | /v1/events/{eventId}/cart/{cartId}/confirm | POST | Non-idempotent | READ_MOBILE_NUMBER, READ_EMAIL, READ_FULL_NAME, AUTOPAY |
| GetEventDetails | /v1/events/{eventId} | GET | Read-only | — |
| GetOrderSummary | /v1/orders/{orderId} | GET | Read-only | — |
| GetSeatDetails | /v1/events/{eventId}/seats | GET | Read-only | — |
| ReleaseTicket | /v1/events/{eventId}/cart/{cartId} | DELETE | Idempotent | — |
| ReserveTicket | /v1/events/{eventId}/cart | POST | Non-idempotent | READ_MOBILE_NUMBER, READ_EMAIL, READ_FULL_NAME, AUTOPAY |
| SearchEvents | /v1/events/search | GET | Read-only | — |
| SearchVenues | /v1/venues/search | POST | Non-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.| 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 |
ConfirmTicket
Path:/v1/events/{eventId}/cart/{cartId}/confirmMethod: 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
| Parameter | Type | Description | Required |
|---|---|---|---|
| cartId | String | Unique identifier of the cart | Yes |
| eventId | String | Unique identifier of the event | Yes |
| payment | Payment | Payment information for ticket purchase | Yes |
| user | User | User information for ticket purchase | Yes |
Response
A successfulConfirmTicketResponse returns order ID, total cost, and wait time to check the status of the booking.
| Parameter | Type | Description | Required |
|---|---|---|---|
| orderId | String | Unique identifier of the order | Yes |
| grandTotal | Double | Total cost for the ticket | Yes |
| waitTime | Integer | Number of seconds to wait before checking the status of the booking | No |
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
| Parameter | Type | Description | Required |
|---|---|---|---|
| eventId | String | Unique identifier for the event | Yes |
Response
A successfulGetEventDetailsResponse returns event details. The inventoryMode field determines the booking path: RESERVED → call GetSeatDetails for seat selection, GENERAL_ADMISSION → select from event.offers directly.
| Parameter | Type | Description | Required |
|---|---|---|---|
| event | Event | Event represents a concert, sports event, theater show, or a single movie showtime | Yes |
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
| Parameter | Type | Description | Required |
|---|---|---|---|
| orderId | String | Unique identifier for the order | Yes |
Response
A successfulGetOrderSummaryResponse returns order ID, order status, and ticket info.
| Parameter | Type | Description | Required |
|---|---|---|---|
| orderId | String | Unique identifier for the order | Yes |
| orderStatus | OrderStatus | Order status such as reserved, confirmed, cancelled, or expired | Yes |
| orderStatusReason | String | Reason for the order status | No |
| ticket | Ticket | Complete ticket information including event, seat, and user details | Yes |
Components
Address
Physical address with optional fields for international support.| Parameter | Type | Description | Required |
|---|---|---|---|
| addressLine1 | String | First line of the address. The maximum length is 50 characters. | Yes |
| addressLine2 | String | Second line of the address. The maximum length is 50 characters. | No |
| addressLine3 | String | Third line of the address. The maximum length is 50 characters. | No |
| countryCode | String | ISO 3166-1 alpha-2 country code. The maximum length is 2 characters. | Yes |
| stateOrRegion | String | State or region. The maximum length is 50 characters. | Yes |
| city | String | Name of the city. The maximum length is 50 characters. | Yes |
| districtOrCounty | String | District or county. The maximum length is 50 characters. | No |
| postalCode | String | Postal or zip code. The maximum length is 12 characters. | Yes |
Artist
Artist or cast member in a movie or show.| Parameter | Type | Description | Required |
|---|---|---|---|
| name | String | Actual name of the artist. The maximum length is 256 characters. | Yes |
| alias | String | Screen name or stage alias of the artist. The maximum length is 256 characters. | No |
| role | String | Role 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).| Parameter | Type | Description | Required |
|---|---|---|---|
| performance | PerformanceAttraction | Performance attraction for concerts, sports, theater, comedy, and more. Set this field for live events. | Yes (one required) |
| movie | MovieAttraction | Movie attraction for film showtimes. Set this field for movies. | Yes (one required) |
Cart
A temporary hold on selected tickets before purchase confirmation.| Parameter | Type | Description | Required |
|---|---|---|---|
| cartId | String | Unique identifier of the cart | Yes |
| ticketItems | List(TicketItem) | Ticket item details added to the cart for the event. Maximum 10 elements. | Yes |
| total | Total | Total cost for all items in the cart | Yes |
| lastUpdatedTimestamp | Timestamp | Timestamp in ISO 8601 format in UTC when the cart was last updated. The format is date-time. For example, 2025-11-17T14:30:00Z | No |
Charge
Charge or fee applied to a ticket.| Parameter | Type | Description | Required |
|---|---|---|---|
| type | String | Type of charge, for example, service_fee, processing_fee, or facility_fee. The maximum length is 50 characters. | Yes |
| amount | Double | Amount of the charge. The amount must be non-negative. | Yes |
| description | String | Description of the charge. The maximum length is 256 characters. | No |
Event
Event represents a concert, sports event, theater show, or a single movie showtime. TheinventoryMode field determines the booking path: RESERVED → call GetSeatDetails for seat selection, GENERAL_ADMISSION → select from event.offers directly.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Unique showtime ID for a movie and event ID for concerts or sports events | Yes |
| name | String | Actual name of an event or a movie, the minimum length is 1 and maximum length is 256 characters. | Yes |
| startDateTime | Timestamp | Movie showtime start timestamp and event start timestamp in ISO 8601 format in UTC. For example, 2025-11-17T14:30:00Z | Yes |
| timezone | String | IANA timezone identifier when available from the provider, for example, America/New_York. Otherwise a UTC offset string, for example, -07:00. | Yes |
| venue | Venue | Where the event is taking place | Yes |
| priceRanges | List(PriceRange) | Available price ranges for the event. Maximum 5 elements. | Yes |
| attraction | AttractionDetails | Attraction details — type-specific information about the event content | Yes |
| inventoryStatus | String | Current inventory status for the event. One of: AVAILABLE, FEW_LEFT, SOLD_OUT, OFF_SALE, CANCELED, POSTPONED, RESCHEDULED. | No |
| inventoryMode | String | Inventory 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 |
| offers | List(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.| Parameter | Type | Description |
|---|---|---|
| MUSIC | String | Music events including concerts and festivals |
| SPORTS | String | Sports events and games |
| ARTS_THEATRE | String | Arts and theater including plays, comedy shows, magic shows |
| FILM | String | Film and movie showtimes |
EventClassification
Event classification including category, genre, and sub-genre.| Parameter | Type | Description | Required |
|---|---|---|---|
| category | EventCategory | Primary event category. Determines the AttractionDetails union branch (FILM → MovieAttraction, others → PerformanceAttraction) and provider routing. | Yes |
| genre | String | Genre of the event, for example, rock, basketball, drama, action | No |
| subGenre | String | Sub-genre for more specific classification, for example, alternative rock, NBA, musical comedy | No |
Fee
Fee applied to the purchase.| Parameter | Type | Description | Required |
|---|---|---|---|
| name | String | Name of the fee, such as service fee or convenience fee. The maximum length is 50 characters. | Yes |
| value | Double | Amount of the fee. It must be non-negative | Yes |
GeneralInfo
General information and rules about the venue.| Parameter | Type | Description | Required |
|---|---|---|---|
| generalRule | String | General rules and policies for the venue. The maximum length is 100 characters. | No |
| childRule | String | Rules and policies specific to children. The maximum length is 100 characters. | No |
| accessibility | String | Accessibility information for the venue. The maximum length is 100 characters. | No |
| additionalNotes | String | Additional information about the venue. The maximum length is 100 characters. | No |
Image
An image with optional content description for accessibility.| Parameter | Type | Description | Required |
|---|---|---|---|
| contentDescription | String | Content description for accessibility purposes. The maximum length is 512 characters. | No |
| sources | List(ImageInstance) | Available image sources. Maximum 5 elements. | Yes |
ImageInstance
URL for the image.| Parameter | Type | Description | Required |
|---|---|---|---|
| url | URL | The 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.| Parameter | Type | Description | Required |
|---|---|---|---|
| images | List(Image) | List of images for the event or movie. Maximum 10 elements. | No |
| trailers | List(Video) | List of trailer videos. Maximum 10 elements. | No |
MovieAttraction
Movie attraction for film showtimes.| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Attraction ID — movie ID or event tour ID or event series ID. | Yes |
| name | String | Attraction name — movie title or event tour name or event series name. The acceptable string length is from 1 to 256. | Yes |
| classification | EventClassification | Classification of the attraction | Yes |
| durationMins | Integer | Duration in minutes. The minimum is one minute. | Yes |
| description | String | Synopsis or description of the attraction. The maximum length is 512 characters. | No |
| media | Media | Media content including images and trailers. | No |
| artists | List(Artist) | Cast and crew of the movie. Maximum 20 elements. | Yes |
| advisoryRating | String | Content 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).| Parameter | Type | Description | Required |
|---|---|---|---|
| offerId | String | Unique identifier for the offer | Yes |
| name | String | Name of the offer. The maximum length is 50 characters. | Yes |
| ticketType | String | Label indicating the ticket type or category, for example, Child, Senior, Adult, or General. The maximum length is 50 characters. | No |
| description | String | Description of the offer. The maximum length is 256 characters. | No |
| currencyCode | CurrencyCode | Currency code for the offer. Must match the regex ^[A-Z]{3}$ and comply with ISO 4217 three-letter currency code, such as USD, EUR, GBP | Yes |
| faceValue | Double | Face value of the ticket. The value must be non-negative | Yes |
| totalPrice | Double | Total price including all charges | Yes |
| charges | List(Charge) | List of charges applied to this offer. Maximum 10 elements. | Yes |
OrderStatus
Enumeration of the following: RESERVED, CONFIRMED, CANCELLED, EXPIRED.| Parameter | Type | Description |
|---|---|---|
| RESERVED | String | Order is reserved but not yet confirmed |
| CONFIRMED | String | Order is confirmed and payment processed |
| CANCELLED | String | Order is cancelled |
| EXPIRED | String | Order reservation is expired |
Payment
Payment information for ticket purchases.| Parameter | Type | Description | Required |
|---|---|---|---|
| type | String | Type of payment method, such as credit_card, debit_card, or digital_wallet | Yes |
| amount | Double | Payment amount. Minimum amount is 0.01 | Yes |
| paymentInstrument | PaymentInstrument | Payment instrument details | No |
| paymentProcessor | String | Name of the payment processor handling the transaction | No |
| externalPaymentNonce | String | External payment nonce for tokenized payments | No |
| paymentNonceType | String | Type of payment nonce used | No |
PaymentInstrument
Payment instrument containing card or payment method details. This information is marked as sensitive information with added security measures.| Parameter | Type | Description | Required |
|---|---|---|---|
| paymentMethodToken | String | External token generated using Banyan3pPaymentProvider | Yes |
| expiryMonth | Integer | Expiry month of the payment method. Acceptable values are from 1–12 | Yes |
| expiryYear | Integer | Expiry year of the payment method, for example, 2028. Acceptable range is from 2024 to 2099. | Yes |
| issuer | String | Card 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.| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Attraction ID — movie ID or event tour ID or event series ID. | Yes |
| name | String | Attraction name — movie title or event tour name or event series name. The acceptable string length is from 1 to 256. | Yes |
| classification | EventClassification | Classification of the attraction. | Yes |
| durationMins | Integer | Duration in minutes. The minimum is one minute. | Yes |
| description | String | Synopsis or description of the attraction. The maximum length is 512 characters. | No |
| media | Media | Media content including images and trailers. | No |
PriceRange
Price range for an event, with optional per-type price breakdown.| Parameter | Type | Description | Required |
|---|---|---|---|
| currencyCode | CurrencyCode | Currency code for the price range. It needs to comply with ISO 4217 three-letter currency code, such as USD, EUR, GBP. | Yes |
| min | Double | Minimum price across all ticket types. It must be non-negative. | Yes |
| max | Double | Maximum price across all ticket types. It must be non-negative. | Yes |
| ticketTypePrices | List(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.| Parameter | Type | Description | Required |
|---|---|---|---|
| attraction | AttractionDetails | The attraction details (performance or movie) | Yes |
| venue | Venue | The venue hosting the attraction | Yes |
| showtimes | List(Showtime) | All upcoming showtimes for this attraction at this venue. Maximum 30 elements. | Yes |
Seat
Individual seat in a venue.| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Unique identifier for the seat | Yes |
| name | String | Seat number or identifier, such as 11, 22A. The maximum length is 5 characters. | Yes |
| type | String | Type of seat, including companion, wheelchair, standard, noseat, loveseatleft, loveseatright for layout. The maximum length is 20 characters. | No |
| isAvailable | Boolean | Whether the seat is available | Yes |
| accessibilityDisabilityAccommodations | List(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.| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Unique identifier for this seat choice option | Yes |
| seatingType | String | Seating type. One of: RESERVED, OPEN, STANDARD. Indicates whether the choice is for specific reserved seats or open/GA. | Yes |
| section | String | Section at the venue, for example, Section1 for concerts, Screen-7 for movies. The maximum length is 50 characters. | Yes |
| row | String | Row identifier such as A, B, C, BALCONY. The maximum length is 10 characters. | Yes |
| offers | List(Offer) | List of offers available for this seat choice, supporting multiple ticket types, for example, Matinee, Child, Senior, Adult. Maximum 10 elements. | Yes |
| seats | List(Seat) | List of individual seats included in this choice for reserved seating | No |
| seatMapSnapshotUrl | URL | URL to the seat map image. Must match the regex ^https://[^\s/$.?#][^\s]*$. | No |
SelectedOffer
An offer selected by the user during ticket reservation. EitherseatIds (for reserved seating) or quantity (for general admission) must be provided, but not both.
| Parameter | Type | Description | Required |
|---|---|---|---|
| offerId | String | Identifier of the offer being selected | Yes |
| seatIds | List(String) | For reserved seating: the IDs of seats selected under this offer. Mutually exclusive with quantity. Maximum 10 elements. | No |
| quantity | Integer | For general admission: the number of tickets under this offer. Mutually exclusive with seatIds. | No |
Showtime
A showtime of an event at a venue.| Parameter | Type | Description | Required |
|---|---|---|---|
| eventId | String | Unique identifier for this specific showtime, used when reserving tickets | Yes |
| startDateTime | String | ISO 8601 local date-time string for when the showtime starts, for example, 2025-10-02T18:00:00 | Yes |
| timezone | String | IANA timezone identifier when available, for example, America/Los_Angeles. Otherwise a UTC offset string, for example, -07:00. | Yes |
| screenType | String | Screen or format type for movie showtimes, for example, IMAX, 4DX, DOLBY, STANDARD | No |
| inventoryStatus | String | Current inventory status for this showtime. One of: AVAILABLE, FEW_LEFT, SOLD_OUT, OFF_SALE, CANCELED, POSTPONED, RESCHEDULED. | No |
| inventoryMode | String | Inventory 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 |
| priceRanges | List(PriceRange) | Price ranges available for this specific showtime. Maximum 5 elements. | No |
Tax
Individual tax applied to the purchase.| Parameter | Type | Description | Required |
|---|---|---|---|
| name | String | Name of the tax, such as sales tax or VAT. The maximum length is 50 characters. | Yes |
| value | Double | Tax amount. It must be non-negative. | Yes |
Ticket
Details about the ticket information including event, seat, and user details.| Parameter | Type | Description | Required |
|---|---|---|---|
| event | Event | Event for which the ticket is purchased. | Yes |
| selectedSeatChoice | SeatChoice | One possible seating combination that is available for selection. | Yes |
| user | User | Ticket purchaser. | Yes |
TicketItem
Details about the individual ticket item in the cart.| Parameter | Type | Description | Required |
|---|---|---|---|
| eventId | String | Showtime ID for a movie or event ID for a concert. | Yes |
| selectedSeatChoice | SeatChoice | One possible seating combination that is available for selection. | Yes |
| total | Total | Total cost for this ticket item. | Yes |
TicketTypePrice
Price for a specific ticket type.| Parameter | Type | Description | Required |
|---|---|---|---|
| type | String | Ticket type. Common values include ADULT, SENIOR, CHILD, STANDARD, PREMIUM, GENERAL. You can also define custom values specific to your services. | Yes |
| price | Double | Price for this ticket type. It must be non-negative. | Yes |
Total
Total cost breakdown for tickets.| Parameter | Type | Description | Required |
|---|---|---|---|
| merchandise | Double | Total merchandise cost. It must be non-negative. | Yes |
| fees | List(Fee) | List of fees applied. Maximum 10 elements. | Yes |
| taxes | List(Tax) | List of taxes applied. Maximum 10 elements. | Yes |
| grand | Double | The grand total. It must be non-negative. | Yes |
| currencyCode | CurrencyCode | Currency 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.| Parameter | Type | Description | Required |
|---|---|---|---|
| firstName | String | First name of the user, with string length from 1 to 100. | Yes |
| lastName | String | Last name of the user, with string length from 1 to 100. | Yes |
| emailAddress | String | Valid email address of the user. Must match the regex ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$. | Yes |
| address | Address | Mailing address of the user. | No |
| phone | String | Valid 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).| Parameter | Type | Description | Required |
|---|---|---|---|
| id | String | Unique identifier for the venue. | Yes |
| name | String | Name of the venue. The maximum length is 200 characters. | Yes |
| address | Address | Physical address of the venue. | Yes |
| generalInfo | GeneralInfo | General information and rules about the venue. | No |
| lat | Double | Latitude of the venue in decimal degrees. | No |
| long | Double | Longitude of the venue in decimal degrees. | No |
| imageUrl | String | URL for the venue’s display image. | No |
| distanceMiles | Double | Distance from the search center in miles. Populated in search responses. | No |
Video
Available video source with an optional content description for accessibility.| Parameter | Type | Description | Required |
|---|---|---|---|
| contentDescription | String | Content description for accessibility purposes. The maximum length is 512 characters. | No |
| sources | List(VideoInstance) | Available video sources. Maximum 5 elements. | Yes |
VideoInstance
A URL for the video.| Parameter | Type | Description | Required |
|---|---|---|---|
| url | URL | The 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.| 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 error responses share a common structure witherrorType, errorCode, and message fields.

