Insomniac Uptop API — Docs & Testing Hub

Overview

This page documents the v1 endpoints you’ll call from your client. You’ll be provisioned an API key out-of-band by Uptop — drop it into API settings (top-right) and you can exercise every endpoint from this page via the Try it panels.

Administrative actions (creating rewards, configuring sponsors, opening auctions, manual point adjustments, browsing all redemptions) live on the Uptop dashboard, not in your client integration. The Dashboard tab in this app simulates that surface so you can see what your administrators will be doing on the other side.

Selected environment · Dev

https://insomniac-api-dev.uptop.xyz

Try it on this page hits this host. Switch environments in the top bar.

Production

https://insomniac-api.uptop.xyz

Use this host when you ship your integration.

Authentication

Every request must include your provisioned API key in the Api-Key header. Keys are issued by Uptop — treat them like any other production secret and keep them on the server side. The server also accepts Authorization: Bearer <key> as a convenience.

every request

Api-Key: <your-uptop-api-key>
Content-Type: application/json

typescript / fetch

const response = await fetch(
  "https://insomniac-api-dev.uptop.xyz/v1/auctions",
  {
    method: "GET",
    headers: {
      "Api-Key": process.env.UPTOP_API_KEY!,
    },
  },
);

Errors

Every non-2xx response is wrapped in a stable envelope so you can branch on error.code without parsing strings.

Envelope

Field	Type	Description
error.code	V1ErrorCode	Stable machine-readable code.
error.message	string	—
error.status	number	—

Example

error response

{
  "error": {
    "code": "INSUFFICIENT_POINTS",
    "message": "User does not have enough points for this redemption.",
    "status": 400
  }
}

Error codes

Code	HTTP	When
UNAUTHORIZED	401	Missing, malformed, or revoked `Api-Key` header.
NOT_FOUND	404	Unknown `userId`, `auctionId`, `redemptionId`, or `sponsorId`.
VALIDATION_ERROR	400	DTO validation failed, `rewardId`/`auctionId` mismatch on redemption, or missing `variantSku` for a merch redemption.
AUCTION_CLOSED	400	Auction is paused, cancelled, or past its end date.
INSUFFICIENT_POINTS	400	User balance is below the auction's `currentPrice`.
INSUFFICIENT_FUNDS	402	Wallet cash, not points: the withdrawable balance is short. Withdrawals only.
WITHDRAWAL_LIMIT_EXCEEDED	400	The withdrawal would go over the daily outbound limit.
FORBIDDEN	403	The operation is refused for this user or program — e.g. a withdrawal declined by a risk check, or withdrawals not enabled.
INTERNAL_ERROR	500	Anything unexpected — check server logs.

Typical client flow

A common end-to-end loop for a client app:

On sign-in, call POST /users:upsert with your externalUserId + email and cache the returned id.
Render the storefront by fetching GET /auctions?status=open and the corresponding GET /rewards/{rewardId}. Display currentPrice as the live points cost.
Show the user’s balance with GET /users/{userId}/points/balance and (optionally) their history via GET /users/{userId}/points/events.
Claim a reward by calling POST /users/{userId}/redemptions. Catch AUCTION_CLOSED and INSUFFICIENT_POINTS explicitly — they’re the two recoverable error states.
Show past redemptions via GET /users/{userId}/redemptions.

Users

2 endpoints

Upsert a user keyed by `email` (idempotent — repeat on every sign-in to keep the record in sync), then retrieve the full profile including live wallet balance by `id`.

Upsert user

Look up an Uptop user by `email` and create it if it doesn't exist. A wallet is provisioned automatically on creation. Cache the returned `id` — it's the only key the rest of the API takes.

POST/v1/users:upsert

Request body

Field	Type	Required	Description
email	string (email)	required	Primary identifier. Upsert is idempotent on this. Also required for virtual card issuance.
phoneNumber	string (E.164)	—	User's phone number in E.164 format, e.g. `+12025551234`. Required for virtual card issuance. Kept in sync — re-upsert with a new value to update it.
externalUserId	string	—	Your partner-side identifier for this user. Optional. When supplied it's linked to the matched/created record so subsequent partner lookups by it work too.
firstName	string	—	User's first name. Required for virtual card issuance — used as the cardholder billing name on the virtual card. Kept in sync on every upsert.
lastName	string	—	User's last name. Required for virtual card issuance — used as the cardholder billing name on the virtual card. Kept in sync on every upsert.

example body

{
  "email": "fan@example.com",
  "phoneNumber": "+12025551234",
  "externalUserId": "partner-user-001",
  "firstName": "Taylor",
  "lastName": "Fan"
}

Response — 200

ReturnsUser

Click the type for the full field-by-field shape.

example response (200)

{
  "id": "65f3a91d6f3a4b0012ab34cd",
  "email": "fan@example.com",
  "phoneNumber": "+12025551234",
  "externalUserId": "partner-user-001",
  "firstName": "Taylor",
  "lastName": "Fan",
  "createdAt": "2026-05-22T15:00:00.000Z"
}

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key`.
VALIDATION_ERROR400— `email` missing or malformed, or `phoneNumber` supplied but not valid E.164.

Notes

**All four fields are required to issue a virtual card: `email`, `phoneNumber`, `firstName`, and `lastName`.** These are used as the cardholder identity on the card record. A user missing any of them cannot be issued a virtual card — pass all four on first upsert.
**No formal KYC is performed.** These fields are used for card issuance purposes only. Uptop does not run identity verification or background checks on this information. Wallets are capped at $1,000, which falls below the threshold that would require KYC.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

Get user

Fetch the user's profile from Uptop plus their live wallet balance. Use this to display the current balance before prompting a load or redemption.

GET/v1/users/{userId}

Path parameters

Field	Type	Required	Description
userId	string	required	Uptop user id returned from `POST /users:upsert`.

Response — 200

ReturnsUserDetail

Click the type for the full field-by-field shape.

example response (200)

{
  "id": "65f3a91d6f3a4b0012ab34cd",
  "email": "fan@example.com",
  "phoneNumber": "+12025551234",
  "externalUserId": "partner-user-001",
  "createdAt": "2026-05-22T15:00:00.000Z",
  "balance": {
    "amount": 2500,
    "currency": "usd"
  }
}

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key`.
NOT_FOUND404— Unknown `userId`.
INTERNAL_ERROR502— Wallet service unavailable.

Notes

`balance.amount` is in the **smallest currency unit** — cents for USD. Divide by 100 to display dollars.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

Wallet

8 endpoints

Virtual wallet attached to every user. Use the virtual-card endpoint to retrieve display-safe card details for showing the card in-app. Transactions are cursor-paginated — store the `nextCursor` from each response and pass it as `cursor` on the next request to page forward through history. Funds leave the wallet through `wallet/withdrawals`, an ACH credit to a bank account the user has linked. That credit cannot be recalled once submitted, which is why the endpoint requires an `idempotencyKey`. Read `wallet/withdrawable-balance` first: it reports how much of the balance a withdrawal will actually accept, which is lower whenever funds are still clearing or a card hold is open.

Get virtual card

Returns display-safe virtual card details — network, last four digits, expiry, cardholder name, and state. Does not expose the full card number or CVV.

GET/v1/users/{userId}/wallet/virtual-card

Path parameters

Field	Type	Required	Description
userId	string	required	Uptop user id returned from `POST /users:upsert`.

Response — 200

ReturnsVirtualCard

Click the type for the full field-by-field shape.

example response (200)

{
  "id": "47d688b2-c0d6-46a2-81e5-2baa979a5aa2",
  "type": "VIRTUAL",
  "cardNetwork": "mastercard",
  "lastFour": "8414",
  "expMonth": "08",
  "expYear": "2029",
  "cardHolderName": "Tony Lee",
  "state": "OPEN"
}

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key`.
NOT_FOUND404— userId does not exist, no virtual card has been provisioned for this user, or the merchant has no active virtual card program.
UNPROCESSABLE_ENTITY422— The user is missing one or more fields required for virtual-card operations: `email`, `phoneNumber`, `firstName`, or `lastName`. Upsert the user with all four fields first.
INTERNAL_ERROR502— Wallet service unavailable.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

List wallet transactions

Returns a cursor-paginated list of wallet transactions for a user, newest first. Omit `cursor` for the first page; pass the returned `nextCursor` on each subsequent call.

GET/v1/users/{userId}/wallet/transactions

Path parameters

Field	Type	Required	Description
userId	string	required	Uptop user id returned from `POST /users:upsert`.

Query parameters

Field	Type	Required	Description
limit	integer	—	Max transactions per page. Default `20`, max `50`.
cursor	string	—	Pagination cursor from a previous response's `nextCursor`. Omit for the first page.

Response — 200

Field	Type	Description
transactions	WalletTransaction[]	Ordered newest-first.
hasMore	boolean	`true` when additional pages exist.
nextCursor	string	Pass as `cursor` to fetch the next page. Absent when `hasMore` is `false`.

example response (200)

{
  "transactions": [
    {
      "id": "txn-abc123",
      "type": "use_balance",
      "amount": -1500,
      "currency": "usd",
      "createdAt": "2026-06-01T18:30:00Z",
      "description": "Spend"
    },
    {
      "id": "txn-def456",
      "type": "add_balance",
      "amount": 10000,
      "currency": "usd",
      "createdAt": "2026-05-28T12:00:00Z",
      "description": "Card load"
    }
  ],
  "hasMore": true,
  "nextCursor": "cursor_abc123"
}

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key`.
NOT_FOUND404— userId does not exist.
INTERNAL_ERROR502— Wallet service unavailable.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

List payment methods

Returns the funding sources attached to the user's wallet — the cards (and bank accounts) used to load balance. Each entry is display-safe: brand and last four only, never the full number. The `preferred` method is the default used by add-balance when no `paymentMethodId` is supplied. Returns an empty array when no payment method is on file.

GET/v1/users/{userId}/wallet/payment-methods

Path parameters

Field	Type	Required	Description
userId	string	required	Uptop user id returned from `POST /users:upsert`.

Response — 200

Field	Type	Description
paymentMethods	PaymentMethod[]	Attached funding sources. Empty when none are on file.

example response (200)

{
  "paymentMethods": [
    {
      "id": "pm-9f2c1a7b",
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "expMonth": 12,
      "expYear": 2027,
      "preferred": true
    }
  ]
}

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key`.
NOT_FOUND404— userId does not exist.
INTERNAL_ERROR502— Wallet service unavailable.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

Create bank link token

Mints a short-lived Plaid Link token so the user can connect a bank account as a funding source ("Pay by Bank"). Hand the returned `linkToken` to Plaid Link, then post the resulting public token to `POST /users/{userId}/wallet/bank-accounts` to finish. Set `platform` for the native mobile SDKs — a token minted for iOS will not open on Android — and omit it for web. Mint a fresh token per Link session; tokens expire after 4 hours. Accepts either the partner `Api-Key` or a user-scoped client token from `POST /users/{userId}/auth/client-token`; prefer the client token from a mobile app so the partner key never ships in an app binary.

POST/v1/users/{userId}/wallet/link-token

Path parameters

Field	Type	Required	Description
userId	string	required	Uptop user id returned from `POST /users:upsert`.

Request body

Field	Type	Required	Description
platform	"ios" \| "android"	—	Native Plaid SDK platform. Omit for web. A token is only valid on the platform it was minted for.
hosted	boolean	—	Returns `hostedLinkUrl` for Plaid's hosted page instead of an in-process token. Cannot be combined with `platform`.

example body

{
  "platform": "ios"
}

Response — 201

Field	Type	Description
linkToken	string	Pass to the Plaid SDK to open Link.
expiration	string	ISO-8601 timestamp after which the token is rejected.
hostedLinkUrl	string	Only present when `hosted` was `true`. Open in a browser.

example response (201)

{
  "linkToken": "link-sandbox-8f2a1c6d-4b3e-4a91-9f27-1d8c5e0b7a34",
  "expiration": "2026-07-31T16:00:00Z"
}

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key` or client token.
VALIDATION_ERROR400— `platform` is not `ios` or `android`, or `platform` and `hosted` were both set.
NOT_FOUND404— userId does not exist.
INTERNAL_ERROR502— Plaid or the wallet service is unavailable.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

Link bank account

Completes Pay-by-Bank setup by exchanging the Plaid public token from Link's success callback for a bank payment method on the user's wallet. The bank then appears in `GET /users/{userId}/wallet/payment-methods` and can fund `wallet:add-balance`. Call it promptly — the public token is single-use and expires about 30 minutes after Link completes, and a failed exchange means the user has to link again. Accepts either the partner `Api-Key` or a user-scoped client token.

POST/v1/users/{userId}/wallet/bank-accounts

Path parameters

Field	Type	Required	Description
userId	string	required	Uptop user id returned from `POST /users:upsert`.

Request body

Field	Type	Required	Description
publicToken	string	required	Plaid `public_token` from Link's success callback.
accountId	string	—	The account the user selected (Plaid `metadata.accounts[0].id`). Omit to use the only account on the item.

example body

{
  "publicToken": "public-sandbox-2f7c9d81-6a4b-4e35-8c12-7b0e9a3d5f46",
  "accountId": "acct-7d2f"
}

Response — 201

Field	Type	Description
paymentMethodId	string	Wallet payment-method id for the linked bank. Pass to add-balance to fund from it.
account	object	The linked account: `accountId`, `name`, and `mask` (last four, may be null).
institutionName	string	Display name of the bank, e.g. `"Chase"`.

example response (201)

{
  "paymentMethodId": "pm-3c8b1e94",
  "account": {
    "accountId": "acct-7d2f",
    "name": "Plaid Checking",
    "mask": "0000"
  },
  "institutionName": "First Platypus Bank"
}

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key` or client token.
VALIDATION_ERROR400— `publicToken` missing, already used, or expired.
NOT_FOUND404— userId does not exist.
INTERNAL_ERROR502— Plaid or the wallet service is unavailable.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

Get withdrawable balance

Returns how much of the wallet balance a withdrawal will accept right now, alongside the wallet balance itself. The two differ because promotional and other non-cash funds cannot be cashed out, recently added funds are held until they clear, an open card authorization blocks withdrawals entirely, and the per-withdrawal minimum and maximum bound the result. `withdrawableBalance` is therefore always an amount a withdrawal accepts, or `0`. Call this before rendering a withdrawal screen and bind any "maximum" control to `withdrawableBalance` rather than to `balance`. Both figures come from a single read, so they cannot disagree; this endpoint replaces `GET /users/{userId}/wallet` on that screen rather than supplementing it. Accepts either the partner `Api-Key` or a user-scoped client token.

GET/v1/users/{userId}/wallet/withdrawable-balance

Path parameters

Field	Type	Required	Description
userId	string	required	Uptop user id returned from `POST /users:upsert`.

Response — 200

ReturnsWithdrawableBalance

Click the type for the full field-by-field shape.

example response (200)

{
  "balance": 15336,
  "withdrawableBalance": 13336,
  "currency": "usd",
  "reason": "held_recent_load"
}

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key` or client token.
FORBIDDEN403— Withdrawals are not configured for the program, in which case the withdrawal endpoint returns the same code and the screen should not be offered. Also returned when a client token is scoped to a different user than the one in the path.
NOT_FOUND404— `userId` does not exist, or the user has no wallet.
INTERNAL_ERROR502— The wallet service was unavailable or did not respond in time.

Notes

**`reason` is present only when `withdrawableBalance` is below `balance`.** Five values are defined today. `open_card_hold`: a pending card authorization is blocking withdrawals, and `withdrawableBalance` is `0`. `held_recent_load`: recently added funds have not finished clearing. `non_cash_funds`: part of the balance is promotional or otherwise not cashable. `maximum_withdrawal`: the balance exceeds the per-withdrawal maximum, and `withdrawableBalance` is that maximum. `below_minimum_withdrawal`: what remains is under the per-withdrawal minimum, so `withdrawableBalance` is `0`. Only one reason is reported when several apply, whichever determines the returned figure. Treat an unrecognized value as a generic explanation rather than an error, since further values may be added.
**Do not publish clearing dates or per-reason amounts.** The response deliberately carries neither. The holding period is a fraud control, so stating when funds unlock, or how much each constraint holds, publishes the control. Wording such as "some funds are still processing" tells the user what they need to know without exposing it.
**The per-withdrawal minimum and maximum are already applied.** `withdrawableBalance` never exceeds the largest amount one withdrawal accepts, and is reported as `0` rather than as an amount below the minimum. A control bound to it therefore cannot produce an amount refused for being out of bounds, and no integration needs to hardcode either limit.
**The figure is a snapshot, not a reservation.** A card authorization or a settling load can change it moments later, so `POST /users/{userId}/wallet/withdrawals` remains the authority. Read it again after an `INSUFFICIENT_FUNDS` refusal rather than reusing the value on screen.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

Create a withdrawal

Submits an ACH credit from the user's wallet to a bank account they have linked. The wallet is debited immediately and the response status is always `pending`; the credit settles over the following business days and its outcome appears as later entries in `GET /users/{userId}/wallet/transactions` rather than on this response. `paymentMethodId` is required and must identify a bank account, so complete Plaid Link before calling this endpoint. Accepts either the partner `Api-Key`, which may act on any user, or a user-scoped client token from `POST /users/{userId}/auth/client-token`. Every request requires an `idempotencyKey`; see the notes for its lifecycle.

POST/v1/users/{userId}/wallet/withdrawals

Path parameters

Field	Type	Required	Description
userId	string	required	Uptop user id returned from `POST /users:upsert`.

Request body

Field	Type	Required	Description
amountCents	integer	required	Amount to withdraw, in cents. The minimum is `100` ($1.00). Amounts above the per-withdrawal cap are refused with `VALIDATION_ERROR`.
paymentMethodId	string	required	Destination bank account: an `id` from `GET /users/{userId}/wallet/payment-methods` with `type: "bank_account"`, or the `paymentMethodId` returned when the account was linked. Cards are rejected. The field has no default, so the destination is always explicit.
idempotencyKey	string (UUID)	required	Identifies one withdrawal intent and must stay constant across every retry of that intent, so that a replay returns the original transaction rather than submitting a second ACH credit. Generate a new key whenever the amount or destination changes; reusing a key with a different amount returns 409.

example body

{
  "amountCents": 5000,
  "paymentMethodId": "pm-3c8b1e94",
  "idempotencyKey": "6f8b0d4a-2e51-4b7c-9a13-8c5d2f0e7b64"
}

Response — 201

ReturnsWithdrawal

Click the type for the full field-by-field shape.

example response (201)

{
  "transactionId": "txn-7b21c4de",
  "status": "pending",
  "amountCents": 5000,
  "paymentMethodId": "pm-3c8b1e94",
  "balance": 10336,
  "currency": "usd",
  "createdAt": "2026-08-24T15:04:00.000Z"
}

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key` or client token.
VALIDATION_ERROR400— `amountCents` is below `100` or over the per-withdrawal cap, `idempotencyKey` is missing or not a UUID, or `paymentMethodId` is a card rather than a bank account.
VALIDATION_ERROR409— The `idempotencyKey` was already used for a withdrawal of a different amount, which identifies a stale key rather than a replay. Create a new intent with a new key; do not retry this request.
INSUFFICIENT_FUNDS402— The withdrawable balance is below `amountCents`, because the wallet holds less than that amount, a recent load has not cleared, or a card hold is open. Retriable once the funds clear.
WITHDRAWAL_LIMIT_EXCEEDED400— The request exceeds the daily outbound limit. Retriable with a smaller amount or on a later day.
FORBIDDEN403— Declined by a risk check, or withdrawals are not yet configured for the program. Not retriable; contact your account contact.
NOT_FOUND404— `userId` does not exist, or `paymentMethodId` is not a payment method on this user's wallet.
INTERNAL_ERROR502— The wallet service was unavailable or did not respond in time. The withdrawal may or may not have been created; retry with the same `idempotencyKey`.

Notes

**Reuse the `idempotencyKey` on every retry.** A request that times out and is retried under a new key submits a second ACH credit. Generate one UUID per withdrawal intent, meaning the amount and destination the user confirmed, persist it before the first request, and send that same key, amount, and destination on every retry. Discard the key after a 2xx, and generate a new one when the user changes the amount or destination.
**A timeout or a 502 is an unknown outcome, not a failure.** The withdrawal may already exist. Retry with the same key, since a replay returns the original transaction rather than submitting a second ACH credit. Do not resolve the ambiguity by creating a new withdrawal, and note that the transaction list cannot identify one: transaction records carry no idempotency key, so two withdrawals of the same amount to the same destination are indistinguishable.
**Check the withdrawable balance before submitting.** The wallet balance is an upper bound: recently added funds are held until they clear, an open card hold blocks withdrawals entirely, and the per-withdrawal limits bound what one request may take. `GET /users/{userId}/wallet/withdrawable-balance` reports the amount this endpoint will accept, and any maximum offered to the user should come from there. That figure is a snapshot rather than a reservation, so still handle `INSUFFICIENT_FUNDS` and read it again before retrying.
**Withdrawing recently added funds can deduct points.** Programs may award points when funds are added to the wallet; when recently added funds leave as cash rather than being spent, the points awarded for the withdrawn amount are deducted again. Withdrawing part of a recent load deducts the bonus on that part only, and one load is never deducted twice across withdrawals. The deduction posts as a negative-`delta` entry of type `other` in `GET /users/{userId}/points/events`, and the points balance can go negative when those points were already redeemed. In-venue spending never triggers this. The lookback window, like the funds-availability holds, is a fraud control and is not disclosed.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

Create & push-provision virtual card

Issues the user's virtual card (if they don't have one yet) and pushes it into Apple Pay or Google Pay in a single call. The virtual card is a singleton per user, so this endpoint is idempotent — it reuses the existing card when one is present and only creates a card the first time. The device generates cryptographic material (nonce, nonce signature, certificate) which this endpoint forwards to the card network. An opaque provisioning payload is returned for the device to complete the "Add to Wallet" flow.

POST/v1/users/{userId}/wallet/virtual-card/provision

Path parameters

Field	Type	Required	Description
userId	string	required	Uptop user id returned from `POST /users:upsert`.

Request body

Field	Type	Required	Description
digitalWallet	"APPLE_PAY" \| "GOOGLE_PAY"	required	Target digital wallet.
nonce	string	—	Apple Pay only. Base64-encoded cryptographic nonce generated by the device.
nonceSignature	string	—	Apple Pay only. Base64-encoded signature over the nonce generated by the device.
certificate	string	—	Apple Pay only. Apple's public leaf certificate, Base64-encoded PEM (headers omitted).

example body

{
  "digitalWallet": "APPLE_PAY",
  "nonce": "base64nonce==",
  "nonceSignature": "base64sig==",
  "certificate": "base64cert=="
}

Response — 200

Field	Type	Description
(provisioning payload)	object	Opaque cryptographic data. Pass this directly to the device's wallet SDK to complete provisioning.

example response (200)

{}

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key`.
NOT_FOUND404— userId does not exist, or the merchant has no active virtual card program (no card can be issued).
VALIDATION_ERROR400— digitalWallet is missing, or nonce/nonceSignature/certificate are absent for APPLE_PAY.
UNPROCESSABLE_ENTITY422— The user is missing one or more fields required for virtual-card operations: `email`, `phoneNumber`, `firstName`, or `lastName`. Upsert the user with all four fields first.
INTERNAL_ERROR502— Card provisioning service unavailable.

Notes

This is the only endpoint that issues a virtual card — it creates one on the first call and reuses it on every call after, then push-provisions it. Because the card is a singleton, the endpoint is idempotent and safe to retry.
**Cardholder-identity prerequisites — all four must be on file:** `email`, `phoneNumber`, `firstName`, `lastName`. They become the cardholder identity on the card record and are required by every virtual-card endpoint (issue, push-provision, and fetch). Upsert the user with all four before provisioning, or you'll get a 422.
**No formal KYC is performed.** These fields are used for card issuance only — Uptop does not run identity verification on them. The $1,000 wallet cap keeps the program below the threshold that would require KYC.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

Field	Type	Required	Description
sponsorId	string	required	Sponsor id from the list endpoint.

Rewards

2 endpoints

Rewards are the things fans can redeem (tickets, experiences, merch, collectibles). They carry no `pointsCost` — price comes from the auction. Created/edited from the Uptop dashboard; clients only need to list/read.

List rewards

All rewards.

GET/v1/rewards

Response — 200

ReturnsReward[]

Click the type for the full field-by-field shape.

example response (200)

[
  {
    "id": "65f3a91d6f3a4b0012ab50bb",
    "name": "VIP locker room tour",
    "description": "Walk-through after the game.",
    "iconUrl": "https://example.com/icon.png",
    "buttonColor": "#1D428A",
    "type": "experience",
    "formFields": [
      {
        "name": "first_name",
        "type": "text",
        "required": true
      },
      {
        "name": "last_name",
        "type": "text",
        "required": true
      },
      {
        "name": "phone_number",
        "type": "text",
        "required": true
      }
    ],
    "tags": [
      "members-only"
    ],
    "createdAt": "2026-05-22T15:00:00.000Z"
  }
]

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key`.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

Get reward

Full record for a single reward, including its `formFields` (what the user has to fill in to redeem) and merch variants if applicable.

GET/v1/rewards/{rewardId}

Path parameters

Field	Type	Required	Description
rewardId	string	required	Reward id from the list endpoint.

Response — 200

ReturnsReward

Click the type for the full field-by-field shape.

example response (200)

{
  "id": "65f3a91d6f3a4b0012ab50bb",
  "name": "Home jersey",
  "description": "Replica home jersey",
  "iconUrl": "https://example.com/j.png",
  "buttonColor": "#FFFFFF",
  "type": "merch",
  "formFields": [
    {
      "name": "first_name",
      "type": "text",
      "required": true
    },
    {
      "name": "last_name",
      "type": "text",
      "required": true
    },
    {
      "name": "address_line_1",
      "type": "text",
      "required": true
    },
    {
      "name": "city",
      "type": "text",
      "required": true
    },
    {
      "name": "state",
      "type": "text",
      "required": true
    },
    {
      "name": "zip",
      "type": "text",
      "required": true
    }
  ],
  "merch": {
    "variants": [
      {
        "sku": "home-jersey-M",
        "color": "blue",
        "size": "M",
        "inventory": 5
      }
    ]
  },
  "tags": [
    "fan-favorite",
    "summer-drop"
  ],
  "createdAt": "2026-05-22T15:00:00.000Z"
}

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key`.
VALIDATION_ERROR400— Unknown `rewardId`.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

Auctions

2 endpoints

Auctions price rewards in points. `currentPrice` is calculated on read for `open`/`paused` auctions and is `null` for `ended`/`cancelled`. Create/edit/pause/resume/cancel are dashboard-driven; you'll only ever read them.

List auctions

All auctions; optionally filter by status. Pass `expand=reward` to inline each auction's full `Reward` and render a storefront in one request.

GET/v1/auctions

Query parameters

Field	Type	Required	Description
status	"open" \| "paused" \| "cancelled" \| "ended"	—	Filter by lifecycle state.
expand	"reward"	—	When set, every row carries the full `Reward` object under `reward` — same shape as `GET /rewards/{rewardId}` — instead of just `rewardId`. Saves the per-auction reward fetch (1 + N calls become 1).

Response — 200

ReturnsAuction[]

Click the type for the full field-by-field shape.

example response (200)

[
  {
    "id": "65f3a91d6f3a4b0012ab60cc",
    "rewardId": "65f3a91d6f3a4b0012ab50bb",
    "startPrice": 1000,
    "reservePrice": 100,
    "currentPrice": 750,
    "startDate": "2026-05-22T14:00:00.000Z",
    "endDate": "2026-05-22T16:00:00.000Z",
    "quantity": 5,
    "quantityPurchased": 1,
    "status": "open",
    "createdAt": "2026-05-22T13:50:00.000Z"
  }
]

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key`.

Notes

The example above shows the default (unexpanded) response. With `?expand=reward`, each row additionally includes a `reward` object — see the `Auction` type for the field and the `Reward` type for its shape.
If an auction's underlying reward no longer exists, the `reward` field is omitted for that row rather than returning an error.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

Get auction

Single auction. `currentPrice` is computed at read time. Supports `expand=reward` like the list endpoint.

GET/v1/auctions/{auctionId}

Path parameters

Field	Type	Required	Description
auctionId	string	required	Auction id.

Query parameters

Field	Type	Required	Description
expand	"reward"	—	When set, the full `Reward` object is inlined under `reward`.

Response — 200

ReturnsAuction

Click the type for the full field-by-field shape.

example response (200)

{
  "id": "65f3a91d6f3a4b0012ab60cc",
  "rewardId": "65f3a91d6f3a4b0012ab50bb",
  "startPrice": 1000,
  "reservePrice": 100,
  "currentPrice": 750,
  "startDate": "2026-05-22T14:00:00.000Z",
  "endDate": "2026-05-22T16:00:00.000Z",
  "quantity": 5,
  "quantityPurchased": 1,
  "status": "open",
  "createdAt": "2026-05-22T13:50:00.000Z"
}

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key`.
NOT_FOUND404— Unknown `auctionId`.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

Points

2 endpoints

Per-user points balance and ledger. Manual adjustments are admin-only and handled from the dashboard.

Get user points balance

Available, pending, and lifetime-earned points. Card-spend earns start in `pendingBalance` (estimated from the authorized amount) and move to `currentBalance` (spendable) once the card transaction settles — credited at the amount that actually settled, so the final value can differ from the pending estimate (a fully reversed charge earns none).

GET/v1/users/{userId}/points/balance

Path parameters

Field	Type	Required	Description
userId	string	required	Uptop user id returned from `POST /users:upsert`.

Response — 200

ReturnsPointsBalance

Click the type for the full field-by-field shape.

example response (200)

{
  "userId": "65f3a91d6f3a4b0012ab34cd",
  "currentBalance": 4250,
  "pendingBalance": 750,
  "lifetimeEarned": 5000
}

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key`.
NOT_FOUND404— Unknown `userId`.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

List user points events

Ledger of point movements for the user, newest first. Card spend surfaces as `'spend'`; other internal types (referrals, badges, …) collapse to `'other'`.

GET/v1/users/{userId}/points/events

Path parameters

Field	Type	Required	Description
userId	string	required	Uptop user id returned from `POST /users:upsert`.

Query parameters

Field	Type	Required	Description
type	"adjustment" \| "receipt" \| "daily_claim" \| "reward_claim" \| "spend"	—	Optional filter. Only the public event types are exposed by name.

Response — 200

ReturnsPointsEvent[]

Click the type for the full field-by-field shape.

example response (200)

[
  {
    "id": "65f3a91d6f3a4b0012ab70dd",
    "userId": "65f3a91d6f3a4b0012ab34cd",
    "type": "adjustment",
    "delta": 5000,
    "reason": "manual_seed",
    "createdAt": "2026-05-22T15:01:00.000Z"
  },
  {
    "id": "65f3a91d6f3a4b0012ab70ee",
    "userId": "65f3a91d6f3a4b0012ab34cd",
    "type": "reward_claim",
    "delta": -750,
    "createdAt": "2026-05-22T15:10:00.000Z"
  }
]

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key`.
NOT_FOUND404— Unknown `userId`.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

Redemptions

3 endpoints

A redemption claims an open auction at its `currentPrice`, deducting available points FIFO from the user's ledger. Pending (unsettled card-spend) points can't be redeemed. This is the most important client-side write — it's how a fan actually 'buys' a reward.

Create redemption

Claim an auction on behalf of the user. Pass both `rewardId` and `auctionId` — the server rejects mismatches. Merch redemptions additionally require `variantSku`.

POST/v1/users/{userId}/redemptions

Path parameters

Field	Type	Required	Description
userId	string	required	Uptop user id returned from `POST /users:upsert`.

Request body

Field	Type	Required	Description
rewardId	string	required	—
auctionId	string	required	—
completedFormFields	Record<string, string>	required	Values for the reward's `formFields`. For experience, send `phone_number`; for merch/collectible, send name + address fields.
variantSku	string	—	Required for merch rewards. Must match a variant on the reward.

example body

{
  "rewardId": "65f3a91d6f3a4b0012ab50bb",
  "auctionId": "65f3a91d6f3a4b0012ab60cc",
  "completedFormFields": {
    "first_name": "Test",
    "last_name": "Fan",
    "phone_number": "555-555-1212"
  }
}

Response — 201

ReturnsRedemption

Click the type for the full field-by-field shape.

example response (201)

{
  "id": "65f3a91d6f3a4b0012ab80ff",
  "rewardId": "65f3a91d6f3a4b0012ab50bb",
  "userId": "65f3a91d6f3a4b0012ab34cd",
  "pointsSpent": 750,
  "completedFormFields": {
    "first_name": "Test",
    "last_name": "Fan",
    "phone_number": "555-555-1212"
  },
  "createdAt": "2026-05-22T15:10:00.000Z"
}

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key`.
NOT_FOUND404— Unknown `userId` or `auctionId`.
VALIDATION_ERROR400— `rewardId` doesn't match the auction's reward, or `variantSku` missing on a merch redemption.
AUCTION_CLOSED400— Auction is paused, cancelled, or past its end date.
INSUFFICIENT_POINTS400— User balance is below `currentPrice`.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

List user redemptions

Every redemption belonging to the user, newest first.

GET/v1/users/{userId}/redemptions

Path parameters

Field	Type	Required	Description
userId	string	required	Uptop user id returned from `POST /users:upsert`.

Response — 200

ReturnsRedemption[]

Click the type for the full field-by-field shape.

example response (200)

[
  {
    "id": "65f3a91d6f3a4b0012ab80ff",
    "rewardId": "65f3a91d6f3a4b0012ab50bb",
    "userId": "65f3a91d6f3a4b0012ab34cd",
    "pointsSpent": 750,
    "completedFormFields": {
      "first_name": "Test",
      "last_name": "Fan",
      "phone_number": "555-555-1212"
    },
    "createdAt": "2026-05-22T15:10:00.000Z"
  }
]

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key`.
NOT_FOUND404— Unknown `userId`.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

Get redemption

A single redemption by id.

GET/v1/redemptions/{redemptionId}

Path parameters

Field	Type	Required	Description
redemptionId	string	required	Redemption id.

Response — 200

ReturnsRedemption

Click the type for the full field-by-field shape.

example response (200)

{
  "id": "65f3a91d6f3a4b0012ab80ff",
  "rewardId": "65f3a91d6f3a4b0012ab50bb",
  "userId": "65f3a91d6f3a4b0012ab34cd",
  "pointsSpent": 750,
  "completedFormFields": {
    "first_name": "Test",
    "last_name": "Fan",
    "phone_number": "555-555-1212"
  },
  "createdAt": "2026-05-22T15:10:00.000Z"
}

Errors

UNAUTHORIZED401— Missing or invalid `Api-Key`.
NOT_FOUND404— Unknown `redemptionId`.

Try it (curl)

curl

Set an API key in the top-right API settings menu —$UPTOP_API_KEY in the curl will be substituted for it on send.

Edit anything above, then send through the local proxy.

Type definitions

Every response above references one of these types. Each definition lists the full field-by-field shape — click any type name elsewhere on the page to jump back here.

User

#type-User

An Uptop user. The `id` is what every other endpoint takes as `{userId}`. Returned by `POST /users:upsert`.

Field	Type	Required	Description
id	string	required	Uptop user id.
email	string (email)	required	Primary identifier. Upsert is idempotent on this.
phoneNumber	string (E.164)	—	Present only if supplied on a previous upsert. Required for card issuance — pass it on first upsert or the user cannot receive a virtual card.
externalUserId	string	—	Partner-side identifier. Present only if supplied on a previous upsert.
firstName	string	—	Present only if supplied on a previous upsert. Required for virtual card issuance.
lastName	string	—	Present only if supplied on a previous upsert. Required for virtual card issuance.
createdAt	string (ISO 8601)	required	—

example

{
  "id": "65f3a91d6f3a4b0012ab34cd",
  "email": "fan@example.com",
  "phoneNumber": "+12025551234",
  "externalUserId": "partner-user-001",
  "firstName": "Taylor",
  "lastName": "Fan",
  "createdAt": "2026-05-22T15:00:00.000Z"
}

WalletTransaction

#type-WalletTransaction

A single wallet credit or debit. `use_balance` transactions are debits and carry a negative `amount`.

Field	Type	Required	Description
id	string	required	Transaction ID.
type	string	required	Transaction type. Common values: `add_balance`, `use_balance`, `merchant_refund`.
amount	integer	required	Cents. Negative for `use_balance` (debit); positive for credits.
currency	string	required	Lowercase ISO 4217, e.g. `"usd"`.
createdAt	string (ISO 8601)	required	UTC timestamp.
description	string	—	Human-readable label. Omitted if not set.

example

{
  "id": "txn-abc123",
  "type": "use_balance",
  "amount": -1500,
  "currency": "usd",
  "createdAt": "2026-06-01T18:30:00Z",
  "description": "Spend"
}

UserDetail

#type-UserDetail

Extends `User` with a live wallet balance. Returned by `GET /users/{userId}`.

Field	Type	Required	Description
id	string	required	—
email	string (email)	required	—
phoneNumber	string (E.164)	—	Present only if supplied on a previous upsert. Required for card issuance.
externalUserId	string	—	Present only if supplied on a previous upsert.
firstName	string	—	Present only if supplied on a previous upsert. Required for virtual card issuance.
lastName	string	—	Present only if supplied on a previous upsert. Required for virtual card issuance.
createdAt	string (ISO 8601)	required	—
balance.amount	number	required	Wallet balance in the smallest currency unit (cents for USD). Divide by 100 to display dollars.
balance.currency	string	required	Lowercase ISO 4217 currency code, e.g. `"usd"`.

example

{
  "id": "65f3a91d6f3a4b0012ab34cd",
  "email": "fan@example.com",
  "phoneNumber": "+12025551234",
  "externalUserId": "partner-user-001",
  "firstName": "Taylor",
  "lastName": "Fan",
  "createdAt": "2026-05-22T15:00:00.000Z",
  "balance": {
    "amount": 2500,
    "currency": "usd"
  }
}

VirtualCard

#type-VirtualCard

Display-safe virtual card details. Does not include the full card number or CVV.

Field	Type	Required	Description
id	string	required	Virtual card UUID.
type	string	required	Always `"VIRTUAL"`.
cardNetwork	string	required	Card network, e.g. `"mastercard"`.
lastFour	string	required	Last four digits of the card number.
expMonth	string	required	Zero-padded expiry month, e.g. `"08"`.
expYear	string	required	Four-digit expiry year, e.g. `"2029"`.
cardHolderName	string	required	Cardholder name on the virtual card.
state	string	required	Card state, e.g. `"OPEN"`.

example

{
  "id": "47d688b2-c0d6-46a2-81e5-2baa979a5aa2",
  "type": "VIRTUAL",
  "cardNetwork": "mastercard",
  "lastFour": "8414",
  "expMonth": "08",
  "expYear": "2029",
  "cardHolderName": "Tony Lee",
  "state": "OPEN"
}

PaymentMethod

#type-PaymentMethod

A display-safe funding source attached to a wallet (a card or bank account used to load balance). Never includes the full account number. Returned by `GET /users/{userId}/wallet/payment-methods`.

Field	Type	Required	Description
id	string	required	Payment method ID. Pass as `paymentMethodId` to add-balance to charge a specific source.
type	string	—	Funding source type, e.g. `"card"` or `"bank_account"`. Omitted when unknown.
brand	string	—	For cards, the network (e.g. `"visa"`); for bank accounts, the bank name. Omitted when unknown.
last4	string	—	Last four digits of the card or account number. Omitted when unknown.
expMonth	integer	—	Card expiry month (`1`–`12`). Cards only; omitted for bank accounts.
expYear	integer	—	Four-digit card expiry year. Cards only; omitted for bank accounts.
preferred	boolean	required	`true` for the default source used by add-balance when no `paymentMethodId` is given.

example

{
  "id": "pm-9f2c1a7b",
  "type": "card",
  "brand": "visa",
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2027,
  "preferred": true
}

WithdrawableBalance

#type-WithdrawableBalance

The wallet balance alongside the portion of it a withdrawal will accept right now, returned by `GET /users/{userId}/wallet/withdrawable-balance`. Both figures are read at the same instant.

Field	Type	Required	Description
balance	integer	required	Wallet balance in cents. An upper bound on `withdrawableBalance`.
withdrawableBalance	integer	required	Cents a withdrawal will accept right now, bounded by the per-withdrawal minimum and maximum. `0` means none can be withdrawn.
currency	string	required	Lowercase ISO 4217. Always `"usd"` today.
reason	string	—	Why `withdrawableBalance` is below `balance`. Absent when the two are equal. `open_card_hold`, `held_recent_load`, `non_cash_funds`, `maximum_withdrawal`, or `below_minimum_withdrawal` today; further values may be added, so treat an unrecognized value as a generic explanation.

example

{
  "balance": 15336,
  "withdrawableBalance": 13336,
  "currency": "usd",
  "reason": "held_recent_load"
}

Withdrawal

#type-Withdrawal

An ACH credit from the wallet to a linked bank account, returned by `POST /users/{userId}/wallet/withdrawals`. The status is always `pending` on creation; the credit settles asynchronously and its outcome appears in `GET /users/{userId}/wallet/transactions`.

Field	Type	Required	Description
transactionId	string	required	Wallet transaction id for the debit. Use it to match this withdrawal against the transaction list.
status	"pending"	required	Always `pending` on creation. Settlement is reported later in `GET /users/{userId}/wallet/transactions`.
amountCents	integer	required	Cents debited from the wallet.
paymentMethodId	string	required	The bank account the funds were sent to.
balance	integer	required	Wallet balance in cents after the debit.
currency	string	required	Lowercase ISO 4217. Always `"usd"` today.
createdAt	string	required	ISO-8601 timestamp of the debit.

example

{
  "transactionId": "txn-7b21c4de",
  "status": "pending",
  "amountCents": 5000,
  "paymentMethodId": "pm-3c8b1e94",
  "balance": 10336,
  "currency": "usd",
  "createdAt": "2026-08-24T15:04:00.000Z"
}

Sponsor

#type-Sponsor

A brand whose spend triggers points. Configuration is dashboard-driven.

Field	Type	Required	Description
id	string	required	—
name	string	required	—
description	string	required	—
logoUrl	string (url)	required	—
primaryColor	string (hex)	required	—
secondaryColor	string (hex)	required	—
matchingType	"plaid" \| "receipt" \| "combination"	required	How spend is matched. `combination` accepts both linked-card and receipt evidence.
pointsMultiplier	number	required	Server-side reward multiplier on matched spend.
frontendMultiplier	number	required	Display-only multiplier rendered in the app.
priority	number	required	Higher values surface earlier in the sponsor strip.
unavailable	boolean	required	When true, hide the sponsor without deleting it. Unavailable sponsors never match spend — no `pointsMultiplier` boost, no `sponsorId` attribution on earns.
createdAt	string (ISO 8601)	required	—

example

{
  "id": "65f3a91d6f3a4b0012ab40aa",
  "name": "Acme Coffee",
  "description": "Local coffee partner",
  "logoUrl": "https://example.com/acme.png",
  "primaryColor": "#1D428A",
  "secondaryColor": "#FFFFFF",
  "matchingType": "receipt",
  "pointsMultiplier": 2,
  "frontendMultiplier": 2,
  "priority": 10,
  "unavailable": false,
  "createdAt": "2026-05-22T15:00:00.000Z"
}

Reward

#type-Reward

A redeemable item (ticket, experience, merch, collectible). Rewards carry no `pointsCost` — price comes from the auction. `merch` is only present when `type === 'merch'`.

Field	Type	Required	Description
id	string	required	—
name	string	required	—
description	string	required	—
iconUrl	string (url)	required	—
buttonColor	string (hex)	required	—
type	"ticket" \| "experience" \| "merch" \| "collectible"	required	—
formFields	FormField[]	required	Fields the user must fill in to redeem this reward.
merch	{ variants: MerchVariant[] }	—	Present only when `type === 'merch'`. Pass the chosen `variantSku` on redemption.
tags	string[]	required	Free-form editorial labels (e.g. `summer-drop`, `edc-exclusive`) for grouping/featuring beyond `type`. Always an array — `[]` when none are set.
createdAt	string (ISO 8601)	required	—

example

{
  "id": "65f3a91d6f3a4b0012ab50bb",
  "name": "Home jersey",
  "description": "Replica home jersey",
  "iconUrl": "https://example.com/j.png",
  "buttonColor": "#FFFFFF",
  "type": "merch",
  "formFields": [
    {
      "name": "first_name",
      "type": "text",
      "required": true
    },
    {
      "name": "last_name",
      "type": "text",
      "required": true
    }
  ],
  "merch": {
    "variants": [
      {
        "sku": "home-jersey-M",
        "color": "blue",
        "size": "M",
        "inventory": 5
      }
    ]
  },
  "tags": [
    "fan-favorite",
    "summer-drop"
  ],
  "createdAt": "2026-05-22T15:00:00.000Z"
}

FormField

#type-FormField

A single input the user has to provide to claim a reward.

Field	Type	Required	Description
name	string	required	Field key (e.g. `first_name`, `phone_number`).
type	"text" \| "select" \| "email"	required	—
required	boolean	required	—

example

{
  "name": "phone_number",
  "type": "text",
  "required": true
}

MerchVariant

#type-MerchVariant

A purchasable SKU on a merch `Reward`.

Field	Type	Required	Description
sku	string	required	Variant SKU. Pass this as `variantSku` on a merch redemption.
color	string	required	—
size	string	required	—
inventory	number	required	Remaining stock.

example

{
  "sku": "home-jersey-M",
  "color": "blue",
  "size": "M",
  "inventory": 5
}

Auction

#type-Auction

A Dutch-style auction pricing a `Reward` in points. `currentPrice` is `null` when the auction is `ended` or `cancelled`.

Field	Type	Required	Description
id	string	required	—
rewardId	string	required	Reward being auctioned.
reward	Reward	—	Full reward object. Present only when the request used `?expand=reward`; omitted if the underlying reward no longer exists.
startPrice	number	required	Points cost at `startDate`.
reservePrice	number	required	Floor the auction decays toward.
currentPrice	number \| null	required	Computed at read time for `open`/`paused` auctions. `null` for `ended`/`cancelled`.
startDate	string (ISO 8601)	required	—
endDate	string (ISO 8601)	required	—
quantity	number	required	Total claimable units.
quantityPurchased	number	required	—
status	"open" \| "paused" \| "cancelled" \| "ended"	required	—
createdAt	string (ISO 8601)	required	—

example

{
  "id": "65f3a91d6f3a4b0012ab60cc",
  "rewardId": "65f3a91d6f3a4b0012ab50bb",
  "startPrice": 1000,
  "reservePrice": 100,
  "currentPrice": 750,
  "startDate": "2026-05-22T14:00:00.000Z",
  "endDate": "2026-05-22T16:00:00.000Z",
  "quantity": 5,
  "quantityPurchased": 1,
  "status": "open",
  "createdAt": "2026-05-22T13:50:00.000Z"
}

PointsBalance

#type-PointsBalance

Current and lifetime points totals for a user.

Field	Type	Required	Description
userId	string	required	—
currentBalance	number	required	Spendable (available) points right now.
pendingBalance	number	required	Points from card taps awaiting settlement — not yet redeemable. Estimated from the authorized amount; the amount credited to `currentBalance` reflects what actually settles, so it can differ (a fully reversed charge earns none).
lifetimeEarned	number	required	Total points credited over the account's life. Decreases only when an earn is reversed — a refunded wallet purchase, or a clawback of points awarded for funds that were later withdrawn.

example

{
  "userId": "65f3a91d6f3a4b0012ab34cd",
  "currentBalance": 4250,
  "pendingBalance": 750,
  "lifetimeEarned": 5000
}

PointsEvent

#type-PointsEvent

An immutable ledger entry. The four public `type` values are exposed by name; all internal event types (referrals, badges, wallet spend, …) collapse to `'other'`.

Field	Type	Required	Description
id	string	required	—
userId	string	required	—
type	"adjustment" \| "receipt" \| "daily_claim" \| "reward_claim" \| "spend" \| "other"	required	`spend` is a card-spend earn.
delta	number	required	Positive credits the balance; negative debits it.
reason	string	—	Free-form. Typically only set on `adjustment` events.
sponsorId	string	—	The sponsor whose spend triggered the earn, for theming Tokens. Set on sponsor-attributed card earns; absent otherwise.
city	string	—	Merchant city where a card-spend (`spend`) earn occurred. Set when the card event carries location; absent otherwise.
state	string	—	Merchant state/region for a card-spend (`spend`) earn. Set when the card event carries location; absent otherwise.
createdAt	string (ISO 8601)	required	—

example

{
  "id": "65f3a91d6f3a4b0012ab70dd",
  "userId": "65f3a91d6f3a4b0012ab34cd",
  "type": "adjustment",
  "delta": 5000,
  "reason": "manual_seed",
  "createdAt": "2026-05-22T15:01:00.000Z"
}

Redemption

#type-Redemption

A claimed auction. `pointsSpent` is the auction's `currentPrice` at the moment of claim — not the reward's nominal price.

Field	Type	Required	Description
id	string	required	—
rewardId	string	required	—
userId	string	required	—
pointsSpent	number	required	Auction `currentPrice` at claim time.
completedFormFields	Record<string, string>	required	Values the user submitted for the reward's `formFields`.
createdAt	string (ISO 8601)	required	—

example

{
  "id": "65f3a91d6f3a4b0012ab80ff",
  "rewardId": "65f3a91d6f3a4b0012ab50bb",
  "userId": "65f3a91d6f3a4b0012ab34cd",
  "pointsSpent": 750,
  "completedFormFields": {
    "first_name": "Test",
    "last_name": "Fan",
    "phone_number": "555-555-1212"
  },
  "createdAt": "2026-05-22T15:10:00.000Z"
}

Overview

Authentication

Errors

Envelope

Example

Error codes

Typical client flow

Users

Request body

Response — 200

Errors

Notes

Try it (curl)

Path parameters

Response — 200

Errors

Notes

Try it (curl)

Wallet

Path parameters

Response — 200

Errors

Try it (curl)

Path parameters

Query parameters

Response — 200

Errors

Try it (curl)

Path parameters

Response — 200

Errors

Try it (curl)

Path parameters

Request body

Response — 201

Errors

Try it (curl)

Path parameters

Request body

Response — 201

Errors

Try it (curl)

Path parameters

Response — 200

Errors

Notes

Try it (curl)

Path parameters

Request body

Response — 201

Errors

Notes

Try it (curl)

Path parameters

Request body

Response — 200

Errors

Notes

Try it (curl)

Sponsors

Response — 200

Errors

Try it (curl)

Path parameters

Response — 200

Errors

Try it (curl)

Rewards

Response — 200

Errors

Try it (curl)

Path parameters

Response — 200

Errors

Try it (curl)

Auctions

Query parameters

Response — 200

Errors

Notes