Custom API
Upgrade
Reference only. Not a decision unless cited in product/DECISIONS.md.
Upgrade
Holders can pay the all-in difference to a higher type on the same event. The Live Pass URL stays the same. Empty organizer path list means upgrades are off. Complimentary passes cannot use this flow.
This is not a cheaper-ticket refund. Downgrade contracts are a separate product.
Organizer email for type changes is a Settings Notifications pulse (Daily by default). It is not the Attendees record. Guests still get the pass email from the upgrade itself.
Who this is for
Venue engineers who need the upgrade contract for headless or embed. Prefer
UpgradeFlow in @axyn/web-sdk unless you host your own UI.
Flow (guest-friendly)
Holder opens ticket (bearer or signed-in)
│
▼
GET eligibility (upgrade-options)
│
▼
POST issue (target tier) → due now
│
▼
POST pay (Stripe PaymentIntent client secret)
│
▼
Same Live Pass URL, now the higher type
Due now is all-in(target) minus remaining net on the pass. Do not show a fee-stripped headline. Do not apply a new coupon on the upgrade.
Staff can get a Ticket changes email (default Daily). That pulse is not the record. Attendees is. Guests still always get the transactional pass email.
Auth model
| Action | Credential |
|---|---|
| Guest eligibility / issue / pay / cancel | Ticket-url bearer (/v1/ticket-url/{token}/…) |
| Signed-in eligibility / issue / pay / cancel | Buyer JWT /v1/me/tickets/{ticketId}/… |
| Tenant secret alone | Not enough to upgrade a guest pass |
Default headless handoff is guest: use the ticket-url bearer path so you
do not need a buyer JWT on the ticket page. First-party hosted checkout
dogfoods these same sold /v1 shapes. Do not call platform admin or
internal routes.
Guest routes (ticket-url bearer)
Confirm bodies in Full API list.
| Method | Path |
|---|---|
GET | /v1/ticket-url/{token}/upgrade-options |
POST | /v1/ticket-url/{token}/upgrade-requests |
POST | /v1/ticket-url/{token}/upgrade-requests/cancel |
POST | /v1/ticket-url/{token}/upgrade-requests/{requestId}/pay |
Issue body: target_tier_id. Options list each allowed target with all-in
due now. Pay returns a Stripe PaymentIntent client secret when money is due.
After pay succeeds, keep using the same Live Pass URL.
Signed-in holder routes
| Method | Path |
|---|---|
GET | /v1/me/tickets/{ticketId}/upgrade-options |
POST | /v1/me/tickets/{ticketId}/upgrade-requests |
POST | /v1/me/tickets/{ticketId}/upgrade-requests/cancel |
POST | /v1/me/tickets/{ticketId}/upgrade-requests/{requestId}/pay |
Same issue field as the guest path (target_tier_id). Call these with a
buyer JWT from your server/BFF (or browser via an allowlisted BFF).
Organizer Admin (sold)
| Method | Path |
|---|---|
GET/POST/DELETE | /v1/tenants/{tenantId}/events/{eventId}/tier-upgrade-paths |
GET/PATCH | /v1/tenants/{tenantId}/workspace-defaults (allow_upgrades, upgrade_cutoff_hours) |
GET | /v1/tenants/{tenantId}/attendees (upgraded=true; list fields upgrade_from_tier_name, upgrade_to_tier_name, upgrade_delta_cents, upgraded_at, upgrade_paid_by) |
GET | /v1/tenants/{tenantId}/exports/attendees (CSV: upgrade_from_tier, upgrade_to_tier, upgrade_delta_cents, upgraded_at, upgrade_paid_by) |
POST | /v1/tenants/{tenantId}/tickets/{ticketId}/upgrade-invites (72h guest link; optional target_tier_id, send_email) |
Guest opens the invite with no login:
| Method | Path |
|---|---|
GET | /v1/upgrade-invites/{token} |
POST | /v1/upgrade-invites/{token}/upgrade-requests |
POST | /v1/upgrade-invites/{token}/upgrade-requests/cancel |
POST | /v1/upgrade-invites/{token}/upgrade-requests/{requestId}/pay |
This invite is not a second Live Pass. Sending it never remints the
door URL. Expired or unknown tokens return upgrade_invite_expired or
upgrade_invite_not_found. Already-upgraded tickets return
ticket_already_upgraded with no second charge.
Paths are per event. Workspace defaults only seed new drafts. Changing org defaults never rewrites a published event and never writes paths.
Status after pay
The holder gets a transactional email: open the same Live Pass, it now
shows the higher type. A screenshot of the old rotating door code is
denied at scan with pass_upgraded ("This pass was upgraded. Ask for
the new one."). The current Live Pass still admits. If the pass is in
Apple Wallet or Google Wallet, add it again. The door reads Live Pass,
not the old shelf. Re-downloading the .pkpass keeps the same serial
and still has no barcode.
Partner outbound webhooks are not a complete public delivery surface yet. Poll the ticket you already hold:
- Guest:
GET /v1/ticket-url/{token}(same bearer, now the higher type) - Signed-in:
GET /v1/me/ticketsand match the same ticket id
Do not invent a ticket.upgraded HMAC until Webhooks documents
one.
Organizer Sales shows Upgrade revenue as the sum of paid deltas, separate
from original ticket sales. Buyer journey events (upgrade_eligibility_viewed,
upgrade_completed, and the rest of the spine) carry ticket ids, tiers, and
cents. They never include email or the Live Pass secret.
Do / do not
Do
- Treat ticket-url bearers as secrets (HTTPS only; do not log full values).
- Quote all-in due now from
upgrade-options, not a face-only delta. - Keep the same Live Pass URL after a successful pay.
- Hide Upgrade when options are empty (organizer off, cutoff, sold out, comp).
Do not
- Teach platform admin or internal routes.
- Apply a new coupon on the upgrade.
- Treat this as a downgrade or refund.
- Rebuild inventory yourself; AXYN moves the pass in place.
Related
| Page | Role |
|---|---|
| Live pass | Rotating door code + step-up |
| Transfer | Send a pass / claim |
| Headless API | Checkout architecture |
| Full API list | Machine contract |
| Webhooks | Poll until outbound ships |