Tickets integration guide – Unidy Documentation

1. Ticket Integration Overview

Tickets are core objects used to manage user entitlements within the system. They are flexible, metadata-rich entities that function similarly to subscriptions, allowing both fixed attributes and arbitrary custom data. To gain more insights on the Ticket UI, please refer to the Ticket Cockpit section.

Key Concepts

Ticket Structure:

A ticket is an object that holds a predefined set of attributes along with optional custom metadata. Here is example payload of a ticket in Unidy:

{
"id": "de6500df-6fc4-4449-a6d2-306ec6dc9c21",
"title": "24-25 Heimspiel",
"text": "Kaufe hier Dein Ticket",
"reference": "1234567890-1",
"metadata": {
	"seat": {
	"rowId": 7,
	"seatId": 27,
	"rowLabel": "4",
	"seatLabel": "26",
	"uniqueSeatId": "4948855007027",
	"priceCategory": {
		"id": 469821,
		"vat": 0.19,
		"code": "",
		"name": "PK1",
		"color": "#ffff00",
		"isoAmount": {
			"amount": "100",
			"currency": "EUR"
			},
		"isoNetAmount": {
			"amount": "100",
			"currency": "EUR"
			},
		"isoVatAmount": {
			"amount": "10",
			"currency": "EUR"
			}
		}
	},
	"status": "B",
	"barcode": "1170370910600530002161",
	"eventURL": "Event/560053/",
	"areaLabel": "06B",
	"invoiceId": "262212080709",
	"performer": [
		{
		"name": "Team A",
		"type": "home",
		"imgUrl": "events/opponents/home/2u/ax/8p/ij/z5/668b97fe762b2.png"
		},
		{
		"name": "Team B",
		"type": "guest",
		"imgUrl": "events/opponents/guest/o3/i2/tc/xn/ek/66866d9361483.png"
		}
		],
	"description": "",
	"competitionName": "Saison 24-25",
	"needsPersonalisation": false,
	"isChangeOfNamesAllowed": false
	},
"wallet_export": null,
"state": "inactive",
"payment_state": null,
"button_cta_url": null,
"info_banner": null,
"seating": null,
"venue": "Stadion",
"currency": "EUR",
"starts_at": "2024-08-10T20:30:00.000+02:00",
"ends_at": "2024-08-10T23:30:00.000+02:00",
"created_at": "2024-07-11T17:08:54.227+02:00",
"updated_at": "2024-07-11T17:08:54.227+02:00",
"price": 64,
"user_id": "bf6e396d-4c5c-5e98-a09b-cab64e45etrz",
"ticket_category_id": "ca97bb23-7a90-484a-bc8f-8de7c93d24673"
}

User Association:

Each ticket is linked to exactly one user.

A single user can have multiple tickets.

Category Association:

Every ticket is associated with one ticket category.

A ticket category can be associated with zero or more tickets.

2. Accessing Tickets in Unidy

Tickets can be accessed and managed through the following interfaces:

UI

❗

Feature flag: need to be activated in the Unidy settings

User account interface https://{brand URL}/tickets

Admin interface: https://{brand URL}/dashboard/tickets

Development

Tickets API endpoints & schemas: https://{brand URL}/api-docs

Using one of the following OAuth flows:

clientCredentials

authorizationCode

implicit

❗

Please ask your integration contact person in Unidy to set up an OAuth App for accessing the tickets.

Webhooks

3. State of the ticket

In Unidy every ticket can have 3 states:

active

passive

inactive

There is a Unidy maintenance job in place that sets the ticket from active to inactive whenever a ticket is expired:

For the tickets with ends_at value set this job runs every 15 minutes and sets every designated ticket to inactive

For the tickets with an empty ends_at value this job will run on the day after the starts_at date at 00:00 and will set the ticket to inactive state.