{"lexicon":1,"id":"tickets.atmosphere.claimFreeTicket","defs":{"main":{"type":"procedure","description":"Atomically claim zero-price scarce tickets for a verified buyer without checkout redirect. Requires app service-auth plus a verified buyerAssertionJwt.","input":{"encoding":"application/json","schema":{"type":"object","required":["buyerDid","buyerAssertionJwt","items"],"properties":{"environment":{"type":"string","knownValues":["test","live"],"maxLength":16},"eventId":{"type":"string","minLength":1,"maxLength":300},"eventUri":{"type":"string","format":"at-uri"},"buyerDid":{"type":"string","format":"did"},"buyerAssertionJwt":{"type":"string","description":"Required short-lived user service-auth JWT from buyerDid to ATM, scoped to tickets.atmosphere.claimFreeTicket.","maxLength":8192},"customerEmail":{"type":"string","maxLength":320,"description":"Private delivery/receipt hint for ticket emails. Stored privately by ATM; never written to protocol records."},"items":{"type":"array","items":{"type":"ref","ref":"tickets.atmosphere.defs#ticketHoldItemRequest"},"minLength":1,"maxLength":20},"accessCode":{"type":"string","minLength":3,"maxLength":64,"description":"Optional organizer access code (visibility gate). Required when any requested ticket type is hidden; ATM validates and consumes one use while issuing the claim."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200},"metadata":{"type":"unknown"}}}},"output":{"encoding":"application/json","schema":{"type":"object","required":["claimId","holdId","environment","items","tickets"],"properties":{"claimId":{"type":"string","maxLength":300},"holdId":{"type":"string","maxLength":300},"environment":{"type":"string","knownValues":["test","live"],"maxLength":16},"items":{"type":"array","items":{"type":"ref","ref":"tickets.atmosphere.defs#ticketHoldItem"},"minLength":1,"maxLength":20},"tickets":{"type":"array","items":{"type":"ref","ref":"tickets.atmosphere.defs#issuedTicketWithContext"},"minLength":1,"maxLength":1000},"reused":{"type":"boolean"}}}},"errors":[{"name":"AppNotRegistered","description":"Caller DID is not registered as an ATM app."},{"name":"TicketsModuleDisabled","description":"This app has not enabled ATM Tickets."},{"name":"UserAssertionRequired","description":"A verified buyer assertion (buyerAssertionJwt) is required to claim free tickets."},{"name":"AuthVerificationFailed","description":"The service-auth token could not be verified."},{"name":"UserDidMismatch","description":"buyerAssertionJwt issuer does not match buyerDid."},{"name":"InvalidItems","description":"At least one ticket type is required."},{"name":"InvalidQuantity","description":"Ticket quantity must be at least 1."},{"name":"IdempotencyConflict","description":"This idempotency key was already used for a different buyer."},{"name":"FreeClaimBindingMismatch","description":"This idempotency key is already bound to a claim with different ticket types or quantities."},{"name":"IdempotencyKeyInFlight","description":"A claim for this idempotency key is already being processed; retry to resume it."},{"name":"TicketTypeNotFound","description":"One or more ticket types were not found."},{"name":"MixedEvents","description":"A ticket claim can only contain ticket types from one event."},{"name":"MixedCurrency","description":"A ticket claim can only use one currency."},{"name":"TicketsUnavailable","description":"The ticket type is not currently available."},{"name":"PaidTicketRequiresCheckout","description":"Paid ticket types must use tickets.atmosphere.createTicketHold."},{"name":"QuantityTooHigh","description":"Requested quantity exceeds the per-claim maximum."},{"name":"InsufficientTicketCapacity","description":"Not enough capacity remains for the claim."},{"name":"TicketClaimMissing","description":"Claimed tickets could not be loaded after issuance."},{"name":"ClaimLimitReached","description":"This buyer already claimed the per-buyer maximum for a ticket type."},{"name":"AccessCodeRequired","description":"One or more requested ticket types are hidden and require an access code."},{"name":"InvalidAccessCode","description":"The access code is invalid, paused, expired, exhausted, or does not unlock every hidden ticket type in the request."},{"name":"TicketsBusy","description":"The inventory row is contended; retry shortly."}]}}}