Front-desk benefit fulfillment
Show arriving members' owed benefits to the desk, verify the guest's code, and record the fulfillment.
This is the pattern behind a hotel or venue operations screen: the desk sees which arriving members are owed something, the guest presents a code, and the desk records that it was handed over.
The sequence
Confirm your reach
GET /v1/partner/scope — which organization and venues this credential
covers. Use it to drive the venue picker rather than hard-coding ids.
Load the arrivals feed
GET /v1/partner/arrivals returns tasks for upcoming member arrivals.
The feed covers roughly a week back to two months ahead.
Acknowledge a task
Acknowledging marks the task as seen by the desk. It is naturally idempotent, so a retry is safe.
Verify the guest's code
The guest presents a two-word verification code. Verify is read-only — it checks the code and returns what it refers to, and changes nothing.
Record the fulfillment
Fulfill with fulfilledBy and optional notes (up to 500 characters).
This is the call that records the benefit as delivered.
Verification codes
- Two words, for example
golden river. - Case-insensitive, so do not force the guest's input to match exactly.
- Unique only among active fulfillments at a property, and reusable afterwards. Treat a code as a lookup key for a live fulfillment, never as a permanent identifier.
- Active statuses are
claimed,pending_approval,approvedandmodified.
Things that catch people out
Acknowledging an arrival is not the same as delivering the benefit. The acknowledgement records that the desk saw the task. Only the fulfillment call records delivery. Reporting "acknowledged" as "fulfilled" will overstate what guests actually received.
- Do not poll arrivals aggressively. The feed is regenerated every six hours, so polling more often returns the same data.
- Send an
Idempotency-Keyon every write. Front-desk staff retry, and networks drop. See Errors, idempotency and pagination. - Verify before you fulfill. Verify is safe to call repeatedly; fulfill is the state change.
Scopes
Arrivals and fulfillments are separate permissions, and the read and write halves are separate again. Each endpoint in the API reference shows exactly what it needs.