Giving away tickets with a guest list

A guest list is a batch of single-use codes. Each code is good for one free ticket of one ticket type. The organizer creates the list and hands out the codes however they like: to friends and family, to an exhibitor, to a sponsor. Whoever holds a code redeems it in the shop and gets that ticket for free.

Before you start:

• Eventjet has to enable guest lists for the company. If the API responds that the company does not have guest lists, contact Eventjet support.
• The API user needs permission to manage the company's guest lists. Permission to manage discount codes is not enough.
• Authenticate as that user with Authorization: Basic base64(key:secret).

1. Pick the ticket type the codes should give away. Any ticket type of one of the company's events works, except seat-map ticket types: they have no price of their own, so there is nothing to give away.

   query GetTicketTypes($eventId: ID!, $locale: String!) {
     event(id: $eventId) {
       ticketTypes {
         id                    # Pass this as CreateGuestListInput.ticketTypeId
         name(locale: $locale)
       }
     }
   }
   query GetTicketTypes($eventId: ID!, $locale: String!) {
     event(id: $eventId) {
       ticketTypes {
         id                    # Pass this as CreateGuestListInput.ticketTypeId
         name(locale: $locale)
       }
     }
   }
   

2. Create the guest list with Mutation.createGuestList. Give it a name so the organizer can find it again, and say how many codes you need. The validity period is optional. Without one, the codes stay valid until the list is deactivated.

   mutation CreateGuestList($ticketTypeId: ID!) {
     createGuestList(
       input: {
         ticketTypeId: $ticketTypeId
         name: "Hall 3 exhibitors"
         numberOfCodes: 200
         validity: { start: "2026-10-01T00:00:00+02:00", end: "2026-10-31T23:59:59+01:00" }
       }
     ) {
       guestList {
         id             # Keep this. Query.guestList takes it.
         numberOfCodes
       }
     }
   }
   mutation CreateGuestList($ticketTypeId: ID!) {
     createGuestList(
       input: {
         ticketTypeId: $ticketTypeId
         name: "Hall 3 exhibitors"
         numberOfCodes: 200
         validity: { start: "2026-10-01T00:00:00+02:00", end: "2026-10-31T23:59:59+01:00" }
       }
     ) {
       guestList {
         id             # Keep this. Query.guestList takes it.
         numberOfCodes
       }
     }
   }
   

   Query.discountCodeGenerationLimits tells you the largest number of codes one call can generate.

   Invalid input is rejected before anything is written. Every error carries its own ErrorCode, so a form can point at the field. CreateGuestListInput lists the codes.

   The codes are generated in the background. The mutation waits for that to finish, so the list it resolves to normally has all its codes. If the mutation responds with GuestListCreationTimeout instead, the list may still have been created. Look it up with Query.guestList before you try again. Trying again creates a second list.

3. Read the list back with Query.guestList. isGenerating tells you whether the codes are complete.

   query GetGuestList($id: ID!) {
     guestList(id: $id) {
       isGenerating
       numberOfCodes
       isActive
     }
   }
   query GetGuestList($id: ID!) {
     guestList(id: $id) {
       isGenerating
       numberOfCodes
       isActive
     }
   }
   

4. Hand out the codes. They are not available through the GraphQL API yet. The organizer downloads them from the guest list page in the Eventjet backend.

5. Redeem a code. The guest enters it in the shop, which calls Mutation.applyCodeToNewCart with the shop's slug. The cart it resolves to holds one ticket of the chosen ticket type at a price of zero, and checkout continues as usual. A code that was already redeemed, or one used outside its validity period, is rejected with CartDoesNotQualifyForDiscount, like any other unusable code.

   mutation RedeemGuestListCode($shopSlug: ID!, $code: String!) {
     applyCodeToNewCart(input: { shopSlug: $shopSlug, code: $code }) {
       cart {
         id
         numberOfItems      # 1
         grandTotal { amount }  # 0
       }
     }
   }
   mutation RedeemGuestListCode($shopSlug: ID!, $code: String!) {
     applyCodeToNewCart(input: { shopSlug: $shopSlug, code: $code }) {
       cart {
         id
         numberOfItems      # 1
         grandTotal { amount }  # 0
       }
     }
   }
   

Root fields

• Query.guestList
• Mutation.createGuestList
• Mutation.applyCodeToNewCart