WalletD developers
Rewards and loyalty

Convert points to wallet cash at the tenant rate

Burns loyalty points and credits the user's wallet cash at the tenant's active conversion rule, in one balanced posting.

POST/v1/rewards/convert

Burns loyalty points and credits the user's wallet cash at the tenant's active conversion rule, in one balanced posting. Requires rewards:convert and an Idempotency-Key. An API key may convert for any user; a user token only for itself (forbidden, 403). Refuses no_conversion_rule (422) when the tenant has no active conversion rule, insufficient_points (422), and idempotency_key_reuse (409) when the same key comes back with a different body — a replay with the same body returns the original conversion.

Authorization

bearerAuth
AuthorizationBearer <token>

A tenant API key (sk_{env}_{id}_{secret}), a wallet user token, or an IdP access token. Which principal the credential resolves to decides the scopes it carries; see the authentication guide.

In: header

Header Parameters

Idempotency-Key*string
Length1 <= length <= 200

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

curl -sS -X POST "$WALLETD_API/v1/rewards/convert" \  -H "Authorization: Bearer $WALLETD_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: convert-user-42-1" \  -d '{"user_id": "'$USER_ID'", "points": 650}'
{  "id": "0191c2dd-51c8-7d47-a95b-3082e6b4fc19",  "user_id": "0191c2d4-8f3a-7c51-9b2e-4a6f8d310e27",  "points": 650,  "cash_credited": 1300,  "minor_per_point": 2}

Create a reward rule (cashback, accrual, or conversion)

Creates a cashback, accrual or conversion rule, scoped to merchants, categories or one offering, and capped per transaction and per user per day.

List a user's reward grants, newest first

A user's reward grants, newest first, each naming the rule that made it and the transaction it credited.