The Tixly ticketing system is used in combination with a website from the venue. This article describes the possibilities and best approach to integrate the venue website and Tixly. There are multiple methods to do this, from simple manual links to a fully automated setup. Manual links Automated setup Webhook User login status and basket information Data in the session information Using personalised information to give pre-sale access and different ticket types to some customers Skins Manual links It is possible to use direct links to the production, event or subscription sales pages and place these on your website by hand. These links can be found in the Box Office sales screens in Tixly and also on the Internet tab of the event edit screens. Of Course, this depends on the cms how this is done. Link to a production https://tix.theatreexample.com/en/buyingflow/tickets/1290/ Link to an event in this production https://tix.theatreexample.com/en/buyingflow/tickets/1290/18417/ Link to an subscription https://tix.uk/en/theatreexample/buyingflow/subscription/15/ The first two examples show a Tixly setup on the subdomain of the venue, the last one uses the Tixly domain. Automated setup The website database holds the events or subscriptions with all information that the venue wants to publish on their website. There can be a calendar page, a page per production. A common approach is to have a setup that does the following: The website periodically imports all future events into their database with help of the Tixly Event API. This ensures that the event information from Tixly is present in the website database. add new events to the local database update existing events  mark the local events the are not in the output anymore as deleted.  The more information is used the better, the PurchaseURL's, OnlineSaleStart, OnlineSaleEnd and SaleStatus are probably needed. The cms is used to add more information, videos, reviews etc to the event groups (productions) or to individual event dates. The website publishes the event. From now it is visible to the visitors. A [buy tickets] button is shown with the Purchase url when the current date is between OnlineSaleStart and OnlineSaleEnd When the user clicks on [buy tickets] the Tixly flow is opened in the same browser window. A reasonable interval for the import in step 1 depends on the situation, once every hour is reasonable. You can add minimized=  true to the event api url to get an output with the minimal version, this only has SaleStatus. You can use this to sync the status more frequently, and build a lighter script the does not need to check if other properties of events are changed.  Webhook It seems a bit of a waste to do the import very often, when most of the time nothing has changed. But on the other hand, you don't want to wait 2 hours for a change in Tixly to be visible on your website. This is when you can use the webhook functionality to solve this. Tixly will call a url on your website, the webhook url, every time in Tixly a change to an event has been made. As a response to the webhook request your website can start an import job. There is no information in the webhook on what event has been changed and Tixly does no do anything with the data the webhook may return. Valid webhook url examples are: https://www.theaterxyx.nl/import/trigger https://username:[email protected]/admin/tix-importer.php Pro tip: The webhook is called whenever something changes. If the venue staff is editing prices, genres etc. this can result in your webhook being called several times a minute. And then for hours, when nothing changes it is not called at all. Instead of running your import routine every time the webhook is called, it is better to wait a minute or two, and if no more webhook calls have been made during this period, then do the import. To start using this, contact Tixly support and give them your website webhook url and we configure this to be used. User login status and basket information Important: Due to restrictions of most browsers, your Tixly instance needs to be on a subdomain of your venue website. e.g. tix.venuewebsite.se  That means this session sharing feature only works on what we call hosted skins. It is possible to show on the venue website that a user is logged into Tixly and if they have a basket. Also the basket contents can be shown on the website. Like this example: This is achieved by sharing session data from Tixly to the website. The website then uses this data to show it in the design they want. The sharing works by opening an iframe to the Tixly website with the integration url on the correct skin. This iframe should be hidden on the venue webpage and does not show anything. It is just used to have javascript from the event/postmessage framework to communicate between the opener page on the venue site and the iframe from Tixly. The post messaging is limited by the settings on the skin, to only allow some websites to post messages and receive data from (see Skin settings). Multiple websites can be configured, this allows development and staging servers of the venue site to use the same skin as the production website. The url of the URL to Iframe, itix (short for integration tix) file is; {skin url}/{language}/itix Example: https://tix.theateraandeparade.nl/nl/itix This url is best to be requested in an iframe . The postMessage 'GetSession' should be issued to the iframe. An EventListener is used to act on the return message with the session information. Looking at implementations of other tixly customers can help to understand this. The Brussels based venue La Monnaie / De Munt has an easy to understand setup. Data in the session information Below is an example of the json structure of the postmessage response. This shows an order with two tickets and the user. { "order": { "items": [{ "type": "Ticket", "name": "An evening with Q on stage", "details": "13-3-2022 20:00:00", "price": 12.0000 }, { "type": "Ticket", "name": "An evening with Q on stage", "details": "13-3-2022 20:00:00", "price": 12.0000 } ], "expires": 896.0954898, "url": "https://tix.theaterexample.nl/nl/buyingflow/purchase/" }, "user": { "id": 544803, "name": "James Bond", "email": "[email protected]", "hash": "2ac9f3a26521d0194530daf3e68c88589d4490617059793dd2eba1b14b786b84" "tags": [{ "id": 7, "name": "Premium", "abbr": "PP" }] }, "profile": "https://tix.theaterexample.nl/nl/profile/" } Details of the properties in the object that is being sent are as follows: order Object that is null if no order is currently in the user session order > items A list of all items in the order order > items > type Type of item. Can be Ticket, Subscription, GiftCard, Membership, Donation, or Product. Note: Subscription is a ticket that is part of a subscription package. order > items > name Name of the item, varies for each type: Ticket > Name of event Subscription > Name of subscription package GiftCard > Name of gift card group Product > Name of product order > items > details Details for each type: Ticket > Event’s start date Subscription > Event’s name and start date GiftCard > Amount of the gift card formatted as an invariant string “20.00” Product > No details given on products order > items > price Price of the item as an invariant decimal (0.00) order > expires Decimal seconds and milliseconds until the order expires from the moment the session info was requested. order > url A URL that takes you to the purchase page for the order. user Object is null if the user is not logged in on this session user > id Id of the web user. Note: this is not the customer id. In the CRM API, there is an endpoint to get the customer Id from the web user Id. CRM API: POST /WebUser/{webUserId}/customer user > name Full name of the logged-in user (can be empty) user > email Email of the logged-in web user (in rare cases, this can differ from the customer's email) user > hash With this hash, the website can validate if the web user id is valid. A secret must be added in the skin settings by a Tixly admin. The hash is computed as a SHA256 over the web user Id + skin secret. Example: web user id: 544803 secret: uXL9aHWX3pumEEZsjU!U The hash will be SHA256(544803uXL9aHWX3pumEEZsjU!U) resulting in: 2ac9f3a26521d0194530daf3e68c88589d4490617059793dd2eba1b14b786b84 user > tags A list of “Customer Tags” that the user is connected to, which can be matched with “tags” on events to see which benefits the logged-in user can access. user > tags > id Id of the tag user > tags > name Name of the tag user > tags > abbr Abbreviation of the tag, not guaranteed to be unique and can be chosen by venue admins profile A URL that takes you to the user's profile page, or to the login page if not logged in. Note: delivery fees are not in the session information. Using personalised information to give pre-sale access and different ticket types to some customers With the session information on the customer, in combination with the benefits in the Tixly Event API, the website is able to show personalised information to the customers. For example if a VIP customer is logged in they can see their VIP prices, normal customers don't see these. Or you can show the [buy tickets] button earlier to your members, with this they can buy before the general public is able to do so (pre sale). The method used here is the Tixly event API containing all the normal sales dates and prices, but also the possible benefits the customers with certain customer tags can utilise. And example of an object list of benefits; { "Benefits": [{ "CustomerTag": { "CustomerTagId": 8, "Name": "Student", "Abbreviation": "ST" }, "Prices": [{ "TicketType": "Student", "Translations": [], "Prices": [{ "PriceZone": "1", "Price": 8.5 }] }] }, { "CustomerTag": { "CustomerTagId": 16, "Name": "Friend", "Abbreviation": "FR" }, "OnlineSaleStart": "2021-06-10T13:00:00", "OnlineSaleStartUTCUnix": 1620039600, "Prices": [{ "TicketType": "Friends", "Translations": [], "Prices": [{"PriceZone": "Rang 1","Price": 15}, { "PriceZone": "Rang 2", "Price": 10}], "ActiveFrom": "2021-06-12T08:00:00+02:00", "ActiveFromUTCUnix": 1623477600, "ActiveTo": "2021-7-12T22:00:00+02:00", "ActiveToUTCUnix": 1626069600, "TicketCount": "0-2" }], }, ] } Here you can see that Customers with the tag Student get to buy tickets for TicketType Student for a price of 8.5. For customers who are Friend there is an alternative, earlier, OnlineSaleStart and also an extra TicketType Friends, that is only available during a limited time period and for a max of 2 tickets. All the benefit data should be stored in the database of the website, so they are available to use in the web front-end. The webpage by default shows an event with the prices visible in the template, the other Benefits prices are in hidden elements. Then when the website gets a user object in the session information from Tixly. The user > tags > id can be used to display the benefit prices, the ones with the corresponding CustomerTagId.  The same goes for the buy tickets button. The default information is used to display the initial state of the button. But when the user has a CustomerTag Id that matches a benefit with an earlier date, the button state to show can be re-evaluated using that date. Example of what normal, or not logged-in users see and what friends see when after the OnlineSaleStart of the friend has passed but the normal OnlineSaleStart is still in the future. Default info / state: "OnlineSaleStart": "2024-06-26T13:00:00" Friends benefit has a different date: "OnlineSaleStart": "2024-06-10T13:00:00 Notes Benefits can add ticket types to the list of available ticket types. Benefits can not change the price of already available ticket types, nor can they remove ticket types. A customer can have multiple customer tags. Each tag can have a benefit. All beneficiary ticket types are available to such a customer, and as such should be shown to him.  When there are multiple beneficiary OnlineSaleStart dates, the first occurring OnlineSaleStart should be used. A customer tag or benefit does not influence the OnlineSaleEnd, SoldOut or SaleStatus, they remain the same for all customers. Each tag can have a benefit. All beneficiary ticket types are available to such a customer, and as such should be shown to him.  When there are multiple beneficiary OnlineSaleStart dates, the first occurring OnlineSaleStart should be used. A customer tag or benefit does not influence the OnlineSaleEnd, SoldOut or SaleStatus, they remain the same for all customers. Skins The Tixly part that the customers see it the online flow and the account pages. This can be styled and configuered in many ways. That configuration is what we call a skin and controls these things, and even more: Design elements, colors, logos. Webtrackers. URLs on the logo, continue shopping buttons. Default settings for many of the emails. URL of the skin, where is can be on a your domain, for example "https://billet.musikhuset.dk" or on a tix domain like this "https://tix.no/nb/notteroy" When using organisations, a skin can be limited to sell only from the configuered organisation.  Define what sites are allowed to read session information.

The Tixly Event API is mainly used to fetch event information about events that is created in Tixly and that shall be published on a website through and external CMS system. It requires a country specific URL and a API key created in system.  Documentation can be found in Swagger by following the link below. Tixly Event API When making a website integration it is also valuable to read the website integration documentation.

The Tixly CRM API is used to fetch customers from the Tixly System, it includes customer information, transactions along with information about different customer attributes such as customer tags and permissions. It can further more write information to the Tixly system making it possible to for example create and edit customers along with tagging, adding permissions etc. from an external system. It is most commonly used with CRM and marketing systems but also to fetch sales information into BI and analytics tools. It requires a country specific URL and a API key created in system.  Documentation can be found in Swagger by following the link below. Tixly CRM API

The Tixly POS API shall only be used when making an integration for selling tickets such as a third party marketplace or a box office system. It can also be used to develop a stand alone web shop. It requires a country specific URL and a API key created in system. Documentation can be found in Postman by following the link below. Postman

Tixly provides an administration API to enable external planning or venue management software to create events and productions in Tixly and retrieve sales data for these events. The admin API was initially built to the specifications of Yesplan, and additional endpoints were added later. This is why the authorisation differs from the CRM API (basic vs Bearer token), and some names are not purely Tixly, such as "Production" instead of "Event Group."  Access to the admin API is configured in the Venue Management module of Tixly and includes a number of configuration options: Organisation Selects an organisation that will be the owner of the created events/groups. Filter by Organisation If set to yes, restricts access to retrieve information only for events of this organisation. Manual Connection If set to yes, a back-office user can add/edit/remove the external ID on events from the Tixly interface. Disabled Values Allows you to make some event properties read-only in the Tixly interface. This means they can only be changed from the management software, ensuring data consistency on both ends. Examples include Event Name, start and end dates. Outline of working with the API Event groups and events are initially created in the venue management software. When they need to be made available in Tixly, the management software can push them using this API. If there are changes or updates to event information in the venue management system, these events can be pushed again to be updated in Tixly. Upon the creation of event groups and events in Tixly, the ID of the generated entities is returned and can be stored in the venue management system. In Tixly, events are then prepared for sale, including setting prices, quotas, and specifying ticket layouts. When the events are sold, there are several routes available to fetch sales data. The api uses basic HTTP authentication: all requests should include a header Authorisation with the scheme “Basic”. All data is exchanged in json format. The date-time values are exchanged as JSON strings based on the ISO 8601 standard. https://adminapi.{country url}/v2/swagger/ui/index Yesplan still runs on version 1 - https://adminapi.{country url}/v1/swagger/ui/index Get mappings The first step it to request the available mappings to get a list of HallConfigurations, Promoters, Seasons and EventCategories that can be used when creating events. A user of the planning system might be shown this as a list of options to choose from when configuring the events. Use  GET /admin/mappings Create a production Push the production details from the planning system to Tixly. POST /admin/productions { "production-id": "P-S-1", "name": "The first production from this system", "sub-title": "SKG2023", "description": "The best show in Iceland... ", "available-online": true, "big-image": "https://cdn.myexamplevenue.com/media//16922-10.jpg", "small-image": "https://cdn.myexamplevenue.com/media//16922-10-b.jpg" } The production-id is the planning systems ID that you then later can use in calls as {externalID}. To get the production details: GET /admin/productions/{externalID} or to update the production details with PUT /admin/productions/{externalID}. Tixly downloads the images from the URLs you add to Tixly's own system and uses them as-is in the buying flow. Create  events Now you can create the events for this production. Use your own event-id  and reference your production, as you see in the first two properties. The seasons, hallconfigurations and eventcategory expect a single value each from the mapping list. POST /admin/event { "event-id": "2d35c887-fa87-4ff5-9edb-8eac42348f87", "production-id": "P-S-1", "name": "Margôt Ros", "starttime": "2024-09-22T17:00:00", "endtime": "2024-09-22T18:30:00", "onlinesalestart": "2024-01-01T09:30:00", "seasons": "1", "hallconfigurations": "47", "eventcategory": "25", "note-1": "Example note", "note-2": "More notes" } It is also possible to send images with this /admin/events, those will replace the images at the primary event group of this event. Your own event-id can be used as {externalId} to get, update or delete an event. Only events that have no tickets on them can be deleted! Retrieving sales information You can retrieve event sales statistics per event with: GET /admin/events/{externalID}. And for all events in a month use: GET /admin/events. The above methods return only events that have an external ID set and use the following output format. Example output: { "tix-event-id": "55177", "event-id": "EX-0002", "production-id": null, "name": "Amélie de musical", "admin-name": "", "location": "", "starttime": "2023-08-19T19:35:00+02:00", "endtime": "2023-08-19T22:30:00+02:00", "in-sale": true, "closed": true, "salestatus": 0, "salestatustext": "None", "ticketscapacity": 2208, "ticketssold": 34, "ticketsfree": 0, "ticketsreserved": 9, "ticketsallocated": 0, "ticketsblocked": 7, "ticketsavailable": 2158, "ticketstotal": 43, "ticketstemporarilyreserved": 0, "ticketsheldforsubscribers": 0, "ticketsrevenue": 3025, "ticketsrevenue-excluding-vat": 2775.23, "productiononline": "1", "eventonline": "1" } The next two routes return all events, including those without an external ID. Optionally, the output can be restricted by a setting in Tixly to only return those connected to the organisation set up in the credentials. What you use depends on your situation. If you need to get details on events that took place, eg. all yesterdays events. Or need to have a status on all events in a certain week, use GET /admin/GetEventsByEventDates. If you are interested in all events, and want to get new data on those that had sales activity in e.g. the last day, you can use GET /admin/GetEventsBySalesDates. The output of these two routes are arrays grouped by EventId, Ticket Type, Price zone, and Section, giving you rather detailed sales information. eg. sales in 3 price zones, each 5 ticket types wil return 15 objects like this example; { "ExternalId": "EX-0002", "EventId": 55177, "AdminName": "", "Name": "Amélie de musical", "StartDate": "08/19/2023 19:35:00", "Venue": "Example Venue", "Hall": "Big Hall", "TicketTypeId": 749, "TicketType": "Normaal", "PriceZoneId": 1, "PriceZone": "1", "SectionId": 721, "Section": "Balcony B", "SoldTickets": 0, "SoldRevenue": 0, "ReservedTickets": 1, "ReservedRevenue": 135, "Capacity": 2201 }, The above capacity is about the whole event, the sold and reserved numbers are for this combination of EventId, Ticket Type, Pricezone and Section. Only such combinations that have sales or reservations on it are in the output. Retrieve sales data over a period of time. This retrieves all tickets with seat details and customer information that were sold over a specified period.  You can use this for example get sales every hour to keep your external system up to date with the latest sales. Route to use is:  GET /admin/GetTicketsBySalesDates. The output is an array with tickets like this Example output; { "CustomerId": 1620265, "CustomerName": "Kim Howick", "FirstName": "Kim", "LastName": "Howick", "CustomerEmail": "[email protected]", "Mobile": "615525685", "AddressOne": "Blaine 1", "AddressTwo": "", "City": "Sneek", "ZipCode": "8604", "Country": "Nederland", "TicketId": 30322525, "TicketTypeId": 749, "TicketType": "Normaal", "PriceZoneId": 1, "PriceZone": "A", "Price": 30, "Created": "04/04/2023 15:58:55", "TransactionType": 1, "ExternalId": "E-55-772b", "EventId": 71845, "Section": "Zaal", "RowName": "12", "SeatName": "6" },

Tixly API's can be used for different integrations within the Tixly System. Below you will find links to the API's with the possibility to test them out. Contact Tixly Support for further details and assistance in how to create and use API keys. Event API Swagger CRM API Swagger Admin API Swagger POS API Postman