Collection & ownership
Separate a buyer's prize history from the items their wallet can act on now.
Alex's purchase belongs to buyer_123. In Verity-collected mode, a winning prize is delivered to the wallet that paid for the winning ticket. If that NFT later moves to another wallet, Alex's prize history remains, but it does not authorize actions for the new holder.
Use the right source for each view
| View | Request | Authentication | Meaning |
|---|---|---|---|
| My tickets | GET /users/{externalUserRef}/checkouts | Partner key, on your server | Your buyer's checkouts and confirmed tickets |
| Prize history | GET /users/{externalUserRef}/prizes | Partner key, on your server | Prizes won through your storefront, including past sellbacks and redemptions |
| Current wallet collection | GET /prizes | Wallet session, wallet API | Items and shipping eligibility for the connected holder |
| Sellback offers | GET /buybacks | Wallet session, wallet API | Current offers, expiry and any sellback operation |
| Shipping orders | GET /redemptions | Wallet session, wallet API | Orders the holder can track or resume |
The wallet API uses /api/v1/redeem, even for collection and sellback. The partner API uses /api/v1/platform. See environment and identity setup.
Render actions from current eligibility
- Load partner prize history for your authenticated buyer.
- Ask the holder to verify their wallet when they want to sell back or ship an item.
- Load wallet prizes and offers. Match the prize
idto the offer'sprize_id; do not match by name or image. - Use the wallet response for current actions. A history-only entry must not become redeemable just because it has an NFT address.
| State | Suggested display |
|---|---|
| Drawn, delivery not yet confirmed | Prize delivery pending |
Wallet prize with redeemable: true | Redeem action |
Offer with available: true and a future expires_at | Sell back, showing amount_usd and deadline |
| Sellback awaiting signature or processing | Resume / view sellback; disable a competing shipping action |
| Existing redemption | Resume payment or track shipment using the order status |
redeemable: false | Explain redeem_blocked_reason; do not infer eligibility locally |
An item can be visible in both Collection and Sellback while an offer is open. These are two views of the same item, not two items. Offer expiry alone does not remove it from the collection. There is no Keep Item or Mint step.
Refresh after changes
Refresh collection, offers, orders and relevant balances after a confirmed action. On a wallet change, clear the previous wallet session, selected items and quotes before fetching the new holder's data. Do not display an old wallet's cached actions for a new wallet.
Loading failures are not empty collections. Show a retry state, respect rate limits, and recheck eligibility at prepare time. Another tab or wallet action can change ownership while the page is open.
Next: Sellback or Redemption.