Polyflight tickets

Required scopes: both polyflight:read and polyflight_terms:read. Ticket responses expose the terms version and share BPS frozen at admission.

GET /api/operator/polyflight/tickets
GET /api/operator/polyflight/tickets/{ticketId}
GET /api/operator/polyflight/tickets/export
Authorization: Bearer {operator_api_key_or_staff_session}

ticketId is a UUID. Every query is constrained to the authenticated operator; a ticket owned by another operator returns 404 POLYFLIGHT_TICKET_NOT_FOUND. Responses use Cache-Control: private, no-store.

List and export filters

The date interval is half-open. search does not search ticket IDs, purchase IDs, or payment status; use the detail route for a known ticket UUID.

curl -sS -G \
  -H "Authorization: Bearer ${OPERATOR_API_KEY}" \
  --data-urlencode "status=won,lost" \
  --data-urlencode "search=operator-user-123" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=25" \
  "https://your-beacon-origin.example.com/api/operator/polyflight/tickets"

Representative list response

{
  "items": [
    {
      "ticketId": "018f70e4-e9c3-7d86-a84c-7ead54e42953",
      "proofTicketId": "018f70e4-f2c1-73c8-9c26-a2fd7f077a4b",
      "purchaseRequestId": "018f70e4-df31-777d-b488-c5876162727e",
      "operatorId": 42,
      "operatorUserId": 701,
      "externalUserId": "operator-user-123",
      "flightId": "018f6f8a-0c47-7af3-8ac2-6c5d9f166d85",
      "flightCode": "PF-20260817-1200-A",
      "status": "won",
      "choiceKind": "abcd",
      "choiceIndex": 2,
      "predictedSequence": "1234",
      "stakeMinor": "10000",
      "feeMinor": "500",
      "netStakeMinor": "9500",
      "potentialPayoutMinor": "38000",
      "termsVersionId": "018f4f92-acde-79e3-9a11-26e38cb73582",
      "ticketFeeShareBps": 10000,
      "positionShareBps": 8000,
      "paymentEffect": "win",
      "paymentStatus": "owed",
      "paymentAmountMinor": "38000",
      "createdAt": "2026-08-17T11:57:12.000Z",
      "settledAt": "2026-08-17T12:00:03.000Z",
      "refundedAt": null
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 25
}

When no tickets match, the list returns items: [] and total: 0. A page beyond the last match has empty items but retains the matching total. The detail route returns one ticket in the same shape without the page envelope.

Read result and delivery separately

status is the game result:

• purchased: admitted, but no terminal result yet;
• won or lost: authoritative result recorded;
• refunded: the ticket was voided and its original stake became refundable.

paymentEffect is win, loss, or refund when delivery is required. paymentStatus is independently owed, in_flight, paid, or manual_review; both fields are null when there is no obligation. Therefore status: "won" with paymentStatus: "owed" is a final win with an unpaid payout, not a pending game result. Newly settled losses expose paymentEffect: "loss" and paymentAmountMinor: "0": their lifecycle tracks a zero-amount wallet acknowledgement, not money owed or paid. The loss remains final in every delivery state and does not block flight financial settlement. Inspect linked wallet evidence in Balance operations.

The existing ticket.resolved callback includes a non-null loss-delivery obligationId for newly settled losses. No loss payout pending/processed callback is emitted; read the ticket lifecycle and loss_credit operation for delivery status. Historical losses keep their existing lifecycle values without backfilled delivery, and older planned/dispatched wallet request evidence is preserved.

proofTicketId links a private operator ticket to its anonymous v5 public-proof ticket. It is null for legacy v4 tickets. Frozen terms are historical ticket terms, not the operator's current terms.

Export

Export applies the same filters to all matching rows. It returns formula-safe CSV by default; add format=json for the canonical JSON envelope.

curl -sS -G \
  -H "Authorization: Bearer ${OPERATOR_API_KEY}" \
  --data-urlencode "status=won" \
  "https://your-beacon-origin.example.com/api/operator/polyflight/tickets/export" \
  --output polyflight-winners.csv

In the dashboard, open Polyflight → Tickets to browse tickets and search by flight code or external user ID. Use the request above or API Playground for exact purchased, won, or lost status filtering; those API statuses are not all available in the current dashboard selector. Choose Export all filtered only for filters the page exposes. See Terms, statements, and settlement for how frozen ticket terms enter a monthly statement.

Playground: /api-playground/polyflight?request=polyflight-tickets.