Skip to content

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

ActionCredential
Guest eligibility / issue / pay / cancelTicket-url bearer (/v1/ticket-url/{token}/…)
Signed-in eligibility / issue / pay / cancelBuyer JWT /v1/me/tickets/{ticketId}/…
Tenant secret aloneNot 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.

MethodPath
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

MethodPath
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)

MethodPath
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:

MethodPath
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/tickets and 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.
PageRole
Live passRotating door code + step-up
TransferSend a pass / claim
Headless APICheckout architecture
Full API listMachine contract
WebhooksPoll until outbound ships

Next