Ticketing

Getting Started

Overview

There are 5 steps to selling a ticket. This step by step guide below with examples will take you through the process:

First, query the available tickets catalog to find a product that fits the needs. This is done using the /ticket/catalog/ endpoint.

GET
1curl https://api.npretail.app/01234567-89ab-cdef-0123-456789abcdef/production/CRONUS%20International%20Ltd./ticket/catalog/EN \
2     -H "Authorization: Bearer <apiKey>"

Use the itemNumber to specify your chosen ticket in later steps.

Response
1{
2  "storeCode": "EN",
3  "items": [
4    {
5      "itemNumber": "31001",
6      "recommendedPrice": {
7        "unitPrice": 100,
8        "unitPriceIncludesVat": true,
9        "vatPct": 25,
10        "currencyCode": "SEK"
11      },
12      "ticketType": {
13        "code": "WEB",
14        "description": "Web sales",
15        "category": "Online"
16      },
17      "description": {
18        "title": "Castle Museum Entrance",
19        "subtitle": "Adult Castle Ticket",
20        "name": "Explore History",
21        "description": "<b>Access</b> to all castle exhibits",
22        "fullDescription": "<p>Step back in time and immerse yourself in the rich history of our castle museum.  Discover fascinating artifacts, explore grand halls, and learn about the lives of the people who once lived within these walls.</p> <p>Experience the grandeur of the castle's architecture and marvel at its intricate details.  Walk through beautifully decorated rooms and admire the stunning artwork and furniture on display.</p> <p>Join a guided tour to gain deeper insights into the castle's history and hear captivating stories  about its past. Learn about the battles fought, the royal inhabitants, and the secrets that lie hidden within these ancient walls.</p>"
23      },
24      "contents": [
25        {
26          "capacityControl": "sales",
27          "code": "CASTLE",
28          "default": true,
29          "description": {
30            "title": "Castle Museum Entrance",
31            "subtitle": "Adult Castle Ticket",
32            "name": "Explore the Castle",
33            "description": "<b>Access</b> to the castle exhibit",
34            "fullDescription": "<p>Experience the grandeur of the castle's architecture and marvel at its intricate details.  Walk through beautifully decorated rooms and admire the stunning artwork and furniture on display.</p>"
35          },
36          "included": "mandatory",
37          "scheduleSelection": "noScheduleSelection",
38          "maxCapacity": 175
39        }
40      ]
41    }
42  ]
43}

Next we need to find time slots for the admission codes that are included with the selected product. For that purpose we will use the /ticket/capacity/search endpoint.

GET
1curl -G https://api.npretail.app/01234567-89ab-cdef-0123-456789abcdef/production/CRONUS%20International%20Ltd./ticket/capacity/search \
2     -H "Authorization: Bearer <apiKey>" \
3     -d itemNumber=31001 \
4     -d referenceDate=2024-10-15 \
5     -d quantity=2

From the response, user must select a suitable time slot. We need the code (“CASTLE”) and schedule.id (452) values to be able to create the reservation in the next step.

Response
1[
2  {
3    "capacityControl": "sales",
4    "code": "CASTLE",
5    "default": true,
6    "discountPct": 0,
7    "included": "mandatory",
8    "quantity": 2,
9    "referenceDate": "2024-10-15",
10    "schedules": [
11      {
12        "allocatable": true,
13        "allocationModel": "capacity",
14        "remainingCapacity": 10,
15        "explanation": "Schedule is allocatable",
16        "schedule": {
17          "externalNumber": 452,
18          "code": "MORNING",
19          "startDate": "2024-10-15",
20          "startTime": "09:00",
21          "endDate": "2024-10-15",
22          "endTime": "12:00",
23          "duration": 10800,
24          "description": "Morning schedule",
25          "arrivalFromTime": "08:30",
26          "arrivalUntilTime": "10:00"
27        },
28        "price": {
29          "pricingOption": "fixed",
30          "adjustmentAmount": 0,
31          "adjustmentPct": 0,
32          "adjustedUnitPrice": 100,
33          "adjustedTotalPrice": 200
34        },
35        "sales": {
36          "salesFromDate": "2024-10-11",
37          "salesFromTime": "00:00",
38          "salesUntilDate": "2024-10-17",
39          "salesUntilTime": "23:59"
40        }
41      },
42      {
43        "allocatable": true,
44        "allocationModel": "capacity",
45        "remainingCapacity": 12,
46        "explanation": "Schedule is allocatable",
47        "schedule": {
48          "externalNumber": 489,
49          "code": "EVENING",
50          "startDate": "2024-10-15",
51          "startTime": "17:00",
52          "endDate": "2024-10-15",
53          "endTime": "20:00",
54          "duration": 10800,
55          "description": "Evening schedule",
56          "arrivalFromTime": "16:30",
57          "arrivalUntilTime": "18:00"
58        },
59        "price": {
60          "pricingOption": "fixed",
61          "adjustmentAmount": 0,
62          "adjustmentPct": 0,
63          "adjustedUnitPrice": 100,
64          "adjustedTotalPrice": 200
65        },
66        "sales": {
67          "salesFromDate": "2024-10-11",
68          "salesFromTime": "00:00",
69          "salesUntilDate": "2024-10-17",
70          "salesUntilTime": "23:59"
71        }
72      }
73    ],
74    "unitPrice": 100,
75    "unitPriceIncludesVat": true,
76    "vatPct": 25
77  }
78]

To make a reservation we need to know the itemNumber (from step 1), admissionCode and scheduleId from step 2

POST
1curl -X POST https://api.npretail.app/01234567-89ab-cdef-0123-456789abcdef/production/CRONUS%20International%20Ltd./ticket/reservation \
2     -H "Authorization: Bearer <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "reserve": [
6    {
7      "itemNumber": "31001",
8      "quantity": 2,
9      "content": [
10        {
11          "admissionCode": "CASTLE",
12          "scheduleNumber": 452
13        }
14      ]
15    }
16  ]
17}'

If the reservation is successful, we will get a reservation token in return. As long as the reservation is valid, our tickets are guaranteed. For subsequent references to this reservation we need the reservation token.

Response
1{
2  "token": "ABC123456DEF789GHI",
3  "reservationStatus": "registered",
4  "expiresAt": "2024-10-11T12:13:00Z",
5  "reservations": [
6    {
7      "itemNumber": "31001",
8      "quantity": 2,
9      "ticket": {
10        "validFrom": "2024-10-15T00:00:00Z",
11        "validUntil": "2024-10-15T23:59:59Z",
12        "unitPrice": 80,
13        "unitPriceInclVat": 100,
14        "currencyCode": "DKK"
15      },
16      "content": [
17        {
18          "admissionDetails": {
19            "capacityControl": "sales",
20            "code": "CASTLE",
21            "default": true,
22            "description": {
23              "title": "Castle Museum Entrance",
24              "subtitle": "Adult Castle Ticket",
25              "name": "Explore the Castle",
26              "description": "<b>Access</b> to the castle exhibit",
27              "fullDescription": "<p>Experience the grandeur of the castle's architecture and marvel at its intricate details.  Walk through beautifully decorated rooms and admire the stunning artwork and furniture on display.</p>"
28            },
29            "included": "mandatory"
30          },
31          "scheduleDetails": {
32            "externalNumber": 452,
33            "code": "MORNING",
34            "startDate": "2024-10-15",
35            "startTime": "09:00",
36            "endDate": "2024-10-15",
37            "endTime": "12:00",
38            "duration": 10800,
39            "description": "Morning schedule",
40            "arrivalFromTime": "08:30",
41            "arrivalUntilTime": "10:00"
42          }
43        }
44      ]
45    }
46  ]
47}

Tickets are reserved but not valid until the reservation has been confirmed. To confirm a reservation we use the /ticket/reservation/:token/confirm endpoint.

POST
1curl -X POST https://api.npretail.app/01234567-89ab-cdef-0123-456789abcdef/production/CRONUS%20International%20Ltd./ticket/reservation/ABC123456DEF789GHI/confirm \
2     -H "Authorization: Bearer <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "ticketHolder": "John Doe",
6  "notificationAddress": "john@acme.com",
7  "paymentReference": "PAY123456"
8}'

The response object contains the ticket numbers that are created and valid for admission.

Response
1{
2  "token": "ABC123456DEF789GHI",
3  "reservationStatus": "confirmed",
4  "reservations": [
5    {
6      "itemNumber": "31001",
7      "quantity": 2,
8      "ticket": {
9        "validFrom": "2024-10-15T00:00:00Z",
10        "validUntil": "2024-10-15T23:59:59Z",
11        "unitPrice": 80,
12        "unitPriceInclVat": 100,
13        "currencyCode": "DKK",
14        "ticketNumbers": [
15          {
16            "ticketId": "12345678-1234-1234-1234-123456789012",
17            "ticketNumber": "TICKET123"
18          },
19          {
20            "ticketId": "ABCDEFAB-1234-1234-1234-123456789013",
21            "ticketNumber": "TICKET124"
22          }
23        ],
24        "pinCode": "12-34",
25        "ticketHolder": "John Doe"
26      },
27      "content": [
28        {
29          "admissionDetails": {
30            "capacityControl": "sales",
31            "code": "CASTLE",
32            "default": true,
33            "description": {
34              "title": "Castle Museum Entrance",
35              "subtitle": "Adult Castle Ticket",
36              "name": "Explore the Castle",
37              "description": "<b>Access</b> to the castle exhibit",
38              "fullDescription": "<p>Experience the grandeur of the castle's architecture and marvel at its intricate details.  Walk through beautifully decorated rooms and admire the stunning artwork and furniture on display.</p>"
39            },
40            "included": "mandatory"
41          },
42          "scheduleDetails": {
43            "externalNumber": 452,
44            "code": "MORNING",
45            "startDate": "2024-10-15",
46            "startTime": "09:00",
47            "endDate": "2024-10-15",
48            "endTime": "12:00",
49            "duration": 10800,
50            "description": "Morning schedule",
51            "arrivalFromTime": "08:30",
52            "arrivalUntilTime": "10:00"
53          }
54        }
55      ]
56    }
57  ]
58}

To get access to the ticket endpoint services, you need to know the ticketId - a unique id for each ticket. You can look-up the this id if you have printed barcode of the ticket with the Find Ticket service.

GET
1curl -G https://api.npretail.app/01234567-89ab-cdef-0123-456789abcdef/production/CRONUS%20International%20Ltd./ticket \
2     -H "Authorization: Bearer <apiKey>" \
3     -d externalNumber=TICKET123

When the ticketId is know, use the Get Ticket endpoint to retrieve all ticket information.

GET
1curl -G https://api.npretail.app/01234567-89ab-cdef-0123-456789abcdef/production/CRONUS%20International%20Ltd./ticket/12345678-1234-1234-1234-123456789012 \
2     -H "Authorization: Bearer <apiKey>" \
3     -d storeCode=EN

The response contain all relevant ticket details:

Response
1{
2  "ticketId": "12345678-1234-1234-1234-123456789012",
3  "ticketNumber": "TICKET123",
4  "reservationToken": "ABC123456DEF789GHI",
5  "itemNumber": "31001",
6  "validFrom": "2024-10-15T22:00:00Z",
7  "validUntil": "2024-10-15T21:59:59Z",
8  "issuedAt": "2024-10-11T12:13:00Z",
9  "content": [
10    {
11      "admissionDetails": {
12        "capacityControl": "sales",
13        "code": "CASTLE",
14        "default": true,
15        "description": {
16          "title": "Castle Museum Entrance",
17          "subtitle": "Adult Castle Ticket",
18          "name": "Explore the Castle",
19          "description": "<b>Access</b> to the castle exhibit",
20          "fullDescription": "<p>Experience the grandeur of the castle's architecture and marvel at its intricate details.  Walk through beautifully decorated rooms and admire the stunning artwork and furniture on display.</p>"
21        },
22        "included": "mandatory"
23      },
24      "scheduleDetails": {
25        "externalNumber": 452,
26        "code": "MORNING",
27        "startDate": "2024-10-15",
28        "startTime": "09:00",
29        "endDate": "2024-10-15",
30        "endTime": "12:00",
31        "duration": 10800,
32        "description": "Morning schedule",
33        "arrivalFromTime": "08:30",
34        "arrivalUntilTime": "10:00"
35      }
36    }
37  ],
38  "description": {
39    "title": "Castle Museum Entrance",
40    "subtitle": "Adult Castle Ticket",
41    "name": "Explore History",
42    "description": "<b>Access</b> to all castle exhibits",
43    "fullDescription": "<p>Step back in time and immerse yourself in the rich history of our castle museum.  Discover fascinating artifacts, explore grand halls, and learn about the lives of the people who once lived within these walls.</p> <p>Experience the grandeur of the castle's architecture and marvel at its intricate details.  Walk through beautifully decorated rooms and admire the stunning artwork and furniture on display.</p> <p>Join a guided tour to gain deeper insights into the castle's history and hear captivating stories  about its past. Learn about the battles fought, the royal inhabitants, and the secrets that lie hidden within these ancient walls.</p>"
44  },
45  "pinCode": "12-34",
46  "unitPrice": 80,
47  "unitPriceInclVat": 100,
48  "currencyCode": "DKK",
49  "ticketHolder": "John Doe",
50  "notificationAddress": "john@acme.com",
51  "printCount": 1,
52  "printedAt": "2024-10-15T12:00:00Z"
53}