# Event tickets Event tickets in a mobile wallet project are different from most other pass types. This document covers information specific to setting up events and issuing adaptive links for event tickets. While you can create and modify event ticket templates from the [mobile wallet](https://www.airship.com/docs/guides/wallet/getting-started/wallet/) dashboard, you must perform all other operations — creating and modifying events, creating [adaptive links](https://www.airship.com/docs/reference/glossary/#adaptive_link) with event and attendee information, etc. — through the API. See the [Events API](https://www.airship.com/docs/developer/rest-api/wallet/operations/events/) and [Multiple Adaptive Links APIs](https://www.airship.com/docs/developer/rest-api/wallet/operations/adaptive-links/#createboardingpassoreventticketadaptivelinks) for a complete reference of methods and payloads. ## Event Ticket Composition An event ticket is an [Adaptive Link](https://www.airship.com/docs/reference/glossary/#adaptive_link) that references an event ticket template populated with one or more events and an array of attendees per ticket. Because of the specific event and attendee information required for each event ticket, you cannot create event tickets using the standard dashboard or `/links/adaptive` methods. You must use the `/links/adaptive/multiple/project` endpoint instead. An event ticket works like a standard adaptive link, with the following differences. 1. Event ticket templates are referenced by ID. You must provide at least one iOS or Android template ID in the adaptive link payload. 1. The adaptive link payload references an `eventId`, `eventExternalId`, or contains a complete [event object](https://www.airship.com/docs/developer/rest-api/wallet/schemas/event-tickets/#eventrequest). 1. Each event in an event ticket adaptive link request includes an array of `attendees`. The endpoint generates an adaptive link for each attendee. 1. Assets referenced by ID (templates, events, etc.) must belong to the same project; you cannot specify events or templates belonging to different projects when creating an event ticket. ## Events An *Event* is the part of an event ticket representing the venue and times of an event. You can make changes to an event to easily update passes for attendees. You can create events either: * Using the `POST` method for the `/events` endpoint. * By providing an event payload when creating adaptive links. In both cases, the result of your request is an `eventId` or `eventExternalId`that you can use to reference the event. After you create an event, you can modify it from the `/events` endpoint. Any changes you make — moving the venue, pushing back event times, etc. — automatically propagate to event tickets (adaptive links) that reference the event. The example below represents a single baseball game that you can use when generating tickets for attendees. You can edit the event to update the passes of all attendees. **Event request example** ```http POST /v1/events/project//id/ HTTP/1.1 Authorization: Basic Content-Type: application/json { "fields": { "eventName": { "label": "Event", "value": "LA Dodgers at SF Giants" }, "venueTitle": { "label": "Venue", "value": "AT&T Park" }, "venueAddress": { "label": "Address", "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107" }, "doorsOpen": { "label": "Doors Open", "value": "2019-09-25T08:35:00" }, "startTime": { "label": "Start Time", "value": "2019-09-25T09:00:00" }, "endTime": { "label": "End Time", "value": "2019-09-25T11:00:00" } }, "passGroups": ["giants_2019-09-25"] } ``` ### External IDs for Events You can create an event with a custom identifier using the `/v1/events/project/id/{projectExternalId}/id/{eventExternalId}` endpoint or by providing an `eventExternalId` when you provide an event object as a part of an adaptive link request. A request specifying an external event ID returns the custom identifier as `eventExternalId`, which you can use to reference events in lieu of the standard `eventId` in subsequent payloads, including the request to create event ticket adaptive links. ### Pass Groups for Events {#pass-groups} You can group events together, so that you can modify multiple events simultaneously — something you might need to do for multiple events at the same venue, e.g., a concert with a backstage pass, baseball game with a pre-game or field-level event, etc. To do this, you can assign [events](https://www.airship.com/docs/reference/glossary/#wallet_event) to `passGroups` — plain text strings, similar to tags for passes. You can assign pass groups in any payload where you create an event or after you create an event using `/passgroups` endpoints. **Add a pass group to an existing event with an external ID** ```http POST /v1/events/project/id//id//passGroups HTTP/1.1 Authorization: Basic Content-Type: application/json { "passGroups": [ "giants_2019-09-25" ] } ``` You can get a list of, or modify, all the events belonging to a `passGroup`. When you modify a pass group, you only need to provide the individual fields that you want to update for all events in the pass group. Any passes generated from events in the group are automatically updated accordingly. **Update all events in a pass group** ```http PUT /v1/events/project/12345/passGroups/giants_2019-09-25 HTTP/1.1 Authorization: Basic Content-Type: application/json { "fields": { "venueTitle": { "value": "Oracle Park" } } } ``` ## Attendees The `attendees` array represents pass holders. Each object in the array represents an individual attendee and results in an individual adaptive link. The `attendees` array appears within an event object when creating event ticket adaptive links. **Example event ticket with attendee array** ```json { "iosTemplateExternalId": "giantsBaseballTicket-ios", "androidTemplateExternalId": "giantsBaseballTicket-android", "payload":{ "events":[ { "eventExternalId": "dodgersAtGiants-2019-09-25", "attendees":[ { "adaptiveLinkExternalId": "", "fields":{ "ticketHolderName": { "label": "Name", "value":"SMITH/JOE" }, "seat": { "value":"33" }, "ticketType": { "value":"VIP" }, "barcode_value": { "value": "1234" }, "barcodeAltText": { "value": "1234" }, "faceValue": { "value": "50" } } } ] } ] } } ``` ## Google Wallet Event Ticket Templates Event ticket templates are not as customizable as other template types. Many of the fields on an event ticket adaptive link are required and cannot be moved or customized in any way. You can set colors, logos, and otherwise customize the general feel of your event tickets. But event tickets templates take a defined set of information (from both `events` and `attendees`) and do not offer as much variance as other pass types that take a wider and more customizable range of information. In the dashboard template editor, you can provide sample event data to test the look and feel of your pass. The event data you fill out in the template editor is purely an example to help you visualize your event ticket. It is not saved as an event or used when creating event tickets. > **Important:** The event information you enter when creating your template is only to help you design your template and send test passes; it is overwritten by a [event object](https://www.airship.com/docs/developer/rest-api/wallet/schemas/event-tickets/#eventrequest) when you create event tickets. See the [Event Ticket Request object](https://www.airship.com/docs/developer/rest-api/wallet/schemas/event-tickets/#eventticketrequest) for information about the event object or ID you must provide when creating passes. > **Note:** In general, you should set > set `ignoresTimeZone: true` for template fields that take date-time values. Event > dates and times are typically UTC local to the venue; > setting `ignoresTimeZone: true` prevents Apple Wallet from modifying times > based on the time zones of attendees' devices. ## Apple Wallet Event Ticket Templates While `event` and `attendee` fields are native to Google Wallet templates, they are not native to Apple Wallet templates. You must name fields on your Apple Wallet template according to the `event` and `attendee` schemas to support event ticket adaptive links. See [Event Ticket Objects](https://www.airship.com/docs/developer/rest-api/wallet/schemas/event-tickets/) for a complete list of the field names your template should use. * If you create your Apple Wallet event ticket template through the **dashboard**, you must rename fields on your template to match `event` and `attendee` object fields through the API. * If you create your Apple Wallet event ticket template through the **API**, you must name fields identically to `event` and `attendee` objects. **Example default Apple Wallet field names and supported event ticket equivalents:** | Default field name | Rename field to | |--------------------|-------------------------------------| | `Seat` | `seat` | | `Row` | `row` | | `Vendor Name` | `venueTitle` | | `Section` | `section` | | `Ticket Details` | `finePrint` | `Location` | `venueAddress` | > **Important:** The event information you enter when creating your template is only to help you design your template and send test passes; it is overwritten by a [event object](https://www.airship.com/docs/developer/rest-api/wallet/schemas/event-tickets/#eventrequest) when you create event tickets. See the [Event Ticket Request object](https://www.airship.com/docs/developer/rest-api/wallet/schemas/event-tickets/#eventticketrequest) for information about the event object or ID you must provide when creating passes. ## Adaptive Links for Event Tickets Event ticket adaptive links are adaptive link that generate or return platform-appropriate passes of the `eventTicket` type. They are created from event ticket templates and associated with `events` and `attendees`. > **Note:** You must use the `/links/adaptive/multiple/project/` endpoint to create event tickets. > While event ticket adaptive links have a similar request structure to other > adaptive links, you cannot create event tickets through the standard > `/links/adaptive` endpoint. When you create an event ticket adaptive link, you can specify events by `eventId` (returned when creating an event), or you can create the event as a part of the adaptive link request. Creating an event as a part of an adaptive link request is the same as creating an event ticket through the `/events` endpoint: the adaptive link response will return an `eventId` or `eventExternalId` that you can use to reference or modify the event later on. > **Note:** Templates and events in an adaptive link payload must belong to the same > project. Within each event, you will specify `attendees` — an array of objects, each object representing an individual event ticket holder. In general, you should set an `adaptiveLinkExternalId` for each attendee. You will modify event ticket adaptive links with a `POST` to the `/v1/links/adaptive/multiple/id/{adaptiveLinkExternalId}` endpoint; you cannot modify an event with an `adaptiveLinkId` in the same way. **Example adaptive link request** ```http POST /v1/links/adaptive/multiple/project/id/ HTTP/1.1 Authorization: Basic Content-Type: application/json { "iosTemplateExternalId": "", "androidTemplateExternalId": "", "payload":{ "events":[ { "eventExternalId": "", "fields":{ "eventName": { "value":"LA Dodgers at SF Giants" }, "venueTitle": { "value":"AT&T Park" }, "venueAddress": { "label": "Address", "value":"24 Willie Mays Plaza\nSan Francisco, CA 94107" }, "doorsOpen": { "label": "Doors Open", "value":"2019-09-25T08:35:00" }, "startTime": { "label": "Start Time", "value":"2019-09-25T09:00:00" }, "endTime": { "label": "End Time", "value":"2019-09-25T11:00:00" } }, "attendees":[ { "adaptiveLinkExternalId": "", "fields":{ "ticketHolderName": { "label": "Name", "value":"SMITH/JOE" }, "seat": { "value":"33" }, "ticketType": { "value":"VIP" }, "barcode_value": { "value": "1234" }, "barcodeAltText": { "value": "1234" }, "faceValue": { "value": "50" } } }, { "adaptiveLinkExternalId": "", "fields":{ "ticketHolderName": { "label": "Name", "value":"SMITH/SALLY" }, "seat": { "value":"34" }, "ticketType": { "value":"VIP" }, "barcode_value": { "value": "1235" }, "barcodeAltText": { "value": "1235" }, "faceValue": { "value": "50" } } } ] } ] } } ``` **Adaptive link response** ```http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "adaptiveLinkId": "", "adaptiveLinkExternalId": "", "iosTemplateId": "iosTemplateId>", "iosTemplateExternalId": "", "androidTemplateId": "", "androidTemplateExternalId": "", "eventId": 476, "eventExternalId": "", "url": "https://wallet-api.urbanairship.com/v1/pass/", "iosUrl": "https://wallet-api.urbanairship.com/v1/pass//ios", "androidUrl": "https://wallet-api.urbanairship.com/v1/pass//android", "createdAt": "2018-09-24T09:12:32Z", "updatedAt": "2018-09-24T09:15:32Z", "isPersonalized": "false", "availablePasses": 1000000, "iosPassLinkId": "a5711a29-7b38-41f2-8202-8f792df89b0b", "androidPassLinkId": "c1f512e5-fda3-4ddf-82c6-066c5681161d", "status": 200 }, { "adaptiveLinkId": "", "adaptiveLinkExternalId": "", "iosTemplateId": "iosTemplateId>", "iosTemplateExternalId": "", "androidTemplateId": "", "androidTemplateExternalId": "", "eventId": 476, "eventExternalId": "", "url": "https://wallet-api.urbanairship.com/v1/pass/", "iosUrl": "https://wallet-api.urbanairship.com/v1/pass//ios", "androidUrl": "https://wallet-api.urbanairship.com/v1/pass//android", "createdAt": "2018-09-24T09:12:32Z", "updatedAt": "2018-09-24T09:15:32Z", "isPersonalized": "false", "availablePasses": 1000000, "iosPassLinkId": "a5711a29-7b38-41f2-8202-8f792df89b0b", "androidPassLinkId": "c1f512e5-fda3-4ddf-82c6-066c5681161d", "status": 200 }, ] ``` ## Modifying Events Any endpoint you can provide an event payload to returns an `eventId`. You can look up, modify, or delete an event using its ID in the path of the `/v1/events` endpoint, regardless of whether you created the event using the `/v1/events` endpoint or provided all event information directly in an adaptive link payload. If you assigned your events to [Pass Groups](https://www.airship.com/docs/reference/glossary/#pass_groups), you can target the pass group to modify a common field across multiple events in a group. For example, if you need to update `venueTitle` for a group of events, you could target the group and with a single update rather than updating each flight individually. When you update events in a pass group, event tickets associated with events in the group are updated accordingly. **Modify all events belonging to a pass group** ```http PUT /v1/events/project/12345/passGroups/giants_2019-09-25 HTTP/1.1 Authorization: Basic Content-Type: application/json { "fields": { "venueTitle": { "value": "Oracle Park" } } } ``` You can also modify an event while modifying corresponding event tickets, using a `POST` to `/v1/links/adaptive/multiple/project/id/{externalProjectId}`, specifying an existing event and existing `adaptiveLinkExternalId` values for the tickets you want to modify in the payload. ## Modifying, Looking-up, and Deleting Event Tickets Each attendee represents receives their own event ticket adaptive link. You can modify event ticket adaptive links using a POST to `/v1/links/adaptive/multiple/project/id/{externalProjectId}`, specifying an existing event and `adaptiveLinkExternalId` value for each event ticket you want to modify in the payload; Airship treats this call as a `PUT` and updates event tickets for the specified adaptive links. You cannot do the same with the standard `adaptiveLinkId`. Therefore, you should expect to set external IDs for your adaptive links. You can look up and delete event ticket adaptive links using the standard GET and DELETE methods for the `/v1/links/adaptive/{adaptiveLinkId}` and `/v1/links/adaptive/id/{adaptiveLinkExternalId}` endpoints.