Davi Developers LogoDavi Developers

Documentation

Rewarding Someone Without an Account

Issue a reward to a card whose holder has not signed up yet, so it is waiting when they claim the card.

This guide issues a reward to a person who has no Davi account, at a door, a stand or a counter. You need an organization-scoped token and a published reward template with no required_entitlement (see below).

A reward is issued to a wallet, and a wallet can exist before its owner does.

curl -X POST "https://api.davi.social/api/v1/rewards/REWARD_SLUG/redeem" \
  -H "Authorization: Bearer ORG_SCOPED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": { "type": "card", "value": "CARD_UID" },
    "scope": "single-use"
  }'

identifier is the same tagged union used everywhere a recipient is named:

typevalueUse when
cardA card uidYou tapped or scanned a card
linkA Davi linkYou scanned a QR or were handed a URL
walletA wallet addressYou already resolved the recipient
usernameA usernameThey told you who they are on Davi
user_idA user UUIDYou already know the Davi user

Use card or link for someone without an account. Each resolves to a wallet, and that wallet does not need an owner. An unclaimed card is bound to a wallet with nobody behind it, and a reward issued there is held, not refused.

The reward stays in the wallet. When somebody later claims the card, the wallet and the reward come with it. You do not issue anything a second time.

2. Handle both response shapes

Which shape you get depends on how the reward template produces its content, not on the request:

  • { "status": "completed", "transaction_id": … }: the reward exists now.
  • { "status": "pending", "delivery_uuid": … }: content is being generated elsewhere. Poll GET /rewards/deliveries/{delivery_uuid} until it reports completed with a transaction_id, or failed.

Handle both. Changing how a template produces its content changes the response shape your code sees.

Retries and repeats

Redemption takes an optional idempotency_key:

{ "identifier": { … }, "scope": "single-use", "idempotency_key": "stand-a-2026-07-31-0142" }

If you omit it, one is derived from stable identifiers. Redeeming the same reward to the same recipient twice is recognized as a repeat, so a retry after a dropped connection does not double-issue.

Supply your own key when your idea of "the same redemption" is narrower, for example one reward per visit rather than one per person. Put whatever makes the visit unique into the key.

Leave the reward ungated

The reward's required_entitlement still applies. A wallet with no owner holds no entitlements, so a reward gated on a membership tier cannot be issued to it. Leave required_entitlement unset on rewards you hand out this way.

Next