Event Group Tickets, Product Group Buys — Frontend Change Log

Author: Josh S. Sakweli, Backend Lead Team Last Updated: 2026-10-31 Version: v1.0 Backend version / branch: fet/location_service (+ notification server d17b028) Deployed to: staging, already live since the 2026-10-25 deploy (6434a415) Compared with: staging as deployed on 2026-10-06 (448f06a0), before group tickets existed

Base URL: https://api.nexgate.co/api/v1 (staging: https://dev.api.nexgate.co/api/v1)

Short Description: Event tickets can now be bought together at a group price ("3 tickets at 15,000 instead of 20,000"). Ticket responses and the event checkout gained fields for it. Product group buys changed too: moving and leaving a group now take a whole payment, there is a new Leave group action, and filled groups now really create their orders (before, they never did).

Audience: mobile team · web team

Related docs — the full flows, with every new endpoint, live in their own docs (not repeated here):

• event_group_tickets_api_doc.md — event tickets "buy together"
• product_group_purchase_api_doc.md — product group buys
• docs/changelog/frontend_changelog_2026-10-25.md §7.1 — group checkout with pickup / delivery

How to read this

One change is breaking: moving a product group payment (§2.2). Everything else keeps working.

0. At a glance

1. Event tickets

What changed in this service: an organiser can switch on group buying for a paid ticket type. One buyer starts a group, friends join with a code, and when the group is full everyone gets their tickets at once. If it does not fill in time, everyone is refunded automatically.

Example: VIP is 20,000. The organiser sets group price 15,000, size 3.

• Asha starts a group "Yoyo Crew" with 2 tickets → pays 30,000 → no booking yet, she sees "2 of 3".
• Baraka joins with the code with 1 ticket → pays 15,000 → group is full → Asha gets 2 tickets, Baraka 1, with QR codes.
• ❌ If nobody joins before the deadline → Asha gets her 30,000 back.

Rules the app must show:

• Size counts tickets, not people.
• No ticket and no QR code until the group is full.
• Paid tickets only (not free, donation or door sales).
• A group closes at the earliest of: its time limit, the end of ticket sales, or 2 hours before the event. expiresAt is the deadline.
• Each friend buys with their own account: a group checkout cannot buy for otherAttendees.

1.1 NEW Organiser: switch group buying on

Endpoint: PATCH {base_url}/e-events/tickets/{ticketId}/group-buying

{ "enabled": true, "groupPrice": 15000, "groupSize": 3, "timeLimitHours": 24 }

Changing price or size later does not touch groups already running. Errors are 400, show the message as it is (for example "Group price must be lower than the ticket price (20000.00)").

1.2 CHANGED Ticket responses — groupBuying

Endpoint: GET {base_url}/e-events/tickets/{eventId}/{ticketId} · the event's ticket list · the PATCH in §1.1

"groupBuying": { "enabled": true, "groupPrice": 15000.0, "groupSize": 3, "timeLimitHours": 24,
                 "availableToBuy": 14, "heldInOpenGroups": 3, "paidInOpenGroups": 2, "openGroups": 1, "sold": 0 }

App to do

• Organiser ticket screen: "Buy together" switch with price / size / time, and the counts above.
• Ticket page: show "Buy together at 15,000" when groupBuying.enabled.

1.3 CHANGED Event checkout — group

Endpoint: POST {base_url}/e-events/checkout

Request

{ "eventId": "1635…", "ticketTypeId": "8a31…", "ticketsForMe": 1, "group": { "groupId": "3a6d…" } }

Response

Errors (400, show as is)

• Group name is required when starting a group
• An open group named 'yoyo crew' already exists for this ticket (names are unique per ticket, case ignored)
• Only 1 tickets left in this group · This group is no longer open · This group is for a different ticket
• Group buying is not available for this ticket · It is too close to the event to start a group
• Group tickets are bought for yourself; each friend joins the group with their own account
• You can hold at most 6 of this ticket; 2 are already waiting in groups — the per-person limit counts waiting tickets

1.4 CHANGED Pay — may fill the group

Endpoint: POST {base_url}/e-events/checkout/{sessionId}/payment — same request

New error to handle: This group just filled up or closed. You have not been charged. — two people paid for the last place at the same moment and the other got it. Nothing was taken; send the user back to the group list.

1.5 CHANGED Cancel a booking

Endpoint: PATCH {base_url}/e-events/booking-orders/{bookingId}/cancel — unchanged

Also works for a booking that came from a group: it refunds exactly those tickets and puts them back on sale.

1.6 NEW Ticket groups — read, move, leave

Full shapes and errors: event_group_tickets_api_doc.md Parts 2 and 4. The parts the screens need:

• Move { "targetGroupId": "…", "quantity": 1 } — any number of my tickets, same event and same ticket type, no money moves. If it fills the target, everyone there gets tickets at once.
• Leave { "quantity": 1 } — any number of my tickets, refunded in full at once; the places open up again.

App to do

• Ticket page: open groups list, "Join with a code", "Start a group".
• My groups: "Waiting for group: 2 of 3" with expiresAt — never a ticket or QR while OPEN.
• Group screen: participants (highlight isMe), Move and Leave.

2. Product group buys

What changed in this service: moving and leaving now take one whole payment — its items, delivery and tax stay together. Each payment a user makes in a group becomes its own order.

Example: Asha pays twice in a group: payment A (1 item, 900) and payment B (1 item, 900).

• ✅ Move payment A to another group → A's item and money go there, B stays.
• ✅ Leave with payment B → 900 (plus its delivery) back at once.
• ❌ Before: "move 1 item" did not say which payment, so the wrong money could be refunded, and a full move left Asha with no order.

2.1 CHANGED Group reads — purchaseHistory

Endpoint: GET {base_url}/e-commerce/group-purchases/{groupId} · /code/{groupCode} · /my-participations

"purchaseHistory": [
  { "checkoutSessionId": "dd9b…", "quantity": 1, "amountPaid": 900.00, "purchasedAt": "2026-10-07T12:40:11" },
  { "checkoutSessionId": "28bc…", "quantity": 1, "amountPaid": 900.00, "purchasedAt": "2026-10-07T12:41:03" }
]

Missing purchaseHistory means "not mine", never an error.

2.2 BREAKING Move a payment to another group

Endpoint: POST {base_url}/e-commerce/group-purchases/transfer

Request

{ "sourceGroupId": "34e5…",
  "targetGroupId": "5604…",
  "quantity": 1 }

{ "sourceGroupId": "34e5…",
  "targetGroupId": "5604…",
  "checkoutSessionId": "dd9b…" }

Why it is breaking: an old app that sends quantity: 1 for a payment of 2 items now moves both, and a user who paid twice is refused until the app sends checkoutSessionId. Only between groups of the same product and shop at the same group price. To move only part of a payment: leave with it (§2.3) and buy again in the other group.

Errors (400)

• You paid 2 times in this group; choose which payment with checkoutSessionId
• That payment is not in this group · The target group does not have 3 free seats
• Payments can only move out of a group that is still open · Source and target groups must be different

2.3 NEW Leave a group — full refund

Endpoint: POST {base_url}/e-commerce/group-purchases/{groupId}/withdraw

{ "checkoutSessionId": "28bc…" }

Body may be empty when the user paid once. Only while the group is OPEN. The whole payment (items, delivery, tax) goes back to the wallet at once. The response is the user's entry: status: REFUNDED when nothing is left, still ACTIVE when another payment remains. A user who left can join again.

Errors (400): You can only leave a group that is still open, You have no active payment in this group.

2.4 FIX Filling, expiring, racing

App to do

• My groups: list the payments from purchaseHistory ("1 item · 900"); skip the choice when there is one.
• Move: send the chosen checkoutSessionId, stop sending quantity.
• New Leave group button while OPEN.
• The last-place error: send the user back to the group list.

3. Notifications

All four open the group: targetType: "EVENT_TICKET_GROUP", targetId = group id → GET /e-events/ticket-groups/{targetId}. An app that does not know the target yet opens the bell list.

A refund also sends the existing ESCROW_REFUNDED, once per person (not once per ticket).

4. App checklist by screen