RewardStar API

Issue and look up RewardStar gift cards via the Custom API.

RewardStar API

Issue prepaid RewardStar gift cards to members and look up previously issued cards. This surface is part of the Custom API (externalApi).

Base URL

https://us-central1-incentable-app-37d9c.cloudfunctions.net/externalApi/api/v1/external

Authentication & permissions

Use a Bearer API key (inc_…):

Authorization: Bearer YOUR_API_KEY

Action	Required permission
Issue a card	`rewardStar` → write
Look up a card	`rewardStar` → read

Enable these on the Custom API integration (or API key) in the Admin dashboard. Optionally set a Default RewardStar Card so requests can omit cardId.

Issue a card

POST /rewardstar/cards

Request body

Field	Type	Required	Description
`member.email`	string	Yes	Recipient email
`member.firstname`	string	Yes	First name
`member.lastname`	string	Yes	Last name
`member.accountKey`	string	No	Matched before email when present
`member.mobile`	string	No	Optional mobile
`denomination`	number	Yes	Face value in dollars; must be a produced denomination on the card
`expiryDays`	number	No	30–365 (default `90`)
`cardId`	string	Conditional	Card id (shown on RewardStar Card pages in Admin); required unless a default is configured
`externalRef`	string	No	Your idempotent reference (unique per `cardId`)
`idempotencyKey`	string	No	Explicit idempotency key

Also accepted: Idempotency-Key header. Resolution order: body idempotencyKey → header → externalRef → generated key.

Example

curl -X POST \
  "https://us-central1-incentable-app-37d9c.cloudfunctions.net/externalApi/api/v1/external/rewardstar/cards" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-order-12345" \
  -d '{
    "cardId": "abc123",
    "denomination": 50,
    "expiryDays": 90,
    "externalRef": "crm-order-12345",
    "member": {
      "email": "jane@example.com",
      "firstname": "Jane",
      "lastname": "Doe",
      "accountKey": "ACME-001"
    }
  }'

Success response (`201`)

{
  "data": {
    "id": "codeDocId",
    "status": "issued",
    "amount": 50,
    "expiresAt": "2026-10-19T06:00:00.000Z",
    "redeemUrl": "https://redeem.rewardstarcard.com/?t=…",
    "isTest": false,
    "externalRef": "crm-order-12345"
  },
  "memberId": "memberDocId",
  "memberCreated": true,
  "message": "RewardStar card issued successfully"
}

Idempotent replays of the same key return 200 with the original payload. Duplicate externalRef for the same cardId returns 409 with the existing card (no redeemUrl on that conflict payload). The same externalRef may be reused on a different RewardStar card.

Behaviour notes

Member upsert: accountKey → email → create Pending member (encrypted fields + auth sync).
Email: Branded HTML is compiled server-side from the card template (CTA, produced card image, placeholders). Recipients receive the redeem link by email.
Fund: Live cards draw down the program fund (face + fee + GST where applicable). Cards with test mode on skip fund movement and set isTest: true.
redeemUrl: Returned only on issue (and idempotent replay). The plaintext token is never stored; GET lookup does not include redeemUrl.

Common errors

Status	Code	Meaning
400	`NO_CARD_SPECIFIED`	No `cardId` and no default configured
400	`INVALID_ARGUMENT` / `VALIDATION_ERROR`	Bad body or denomination not on the card
402	`INSUFFICIENT_FUND`	Program fund balance too low
403	`PERMISSION_DENIED`	Key lacks `rewardStar` write
409	`DUPLICATE_EXTERNAL_REF`	`externalRef` already used for this `cardId`
409	`AMBIGUOUS_EXTERNAL_REF`	GET by `externalRef` matched multiple cards — pass `?cardId=`
409	`IDEMPOTENCY_IN_PROGRESS`	Same key still processing

Get an issued card

GET /rewardstar/cards/{id}

{id} may be the issued code document id or an externalRef. When looking up by externalRef, you can pass ?cardId= to disambiguate (references are unique per card, not across every card in the program).

curl -X GET \
  "https://us-central1-incentable-app-37d9c.cloudfunctions.net/externalApi/api/v1/external/rewardstar/cards/crm-order-12345?cardId=YOUR_CARD_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": {
    "id": "codeDocId",
    "status": "issued",
    "amount": 50,
    "cardId": "abc123",
    "memberId": "memberDocId",
    "externalRef": "crm-order-12345",
    "isTest": false,
    "expiresAt": "2026-10-19T06:00:00.000Z",
    "issuedAt": "2026-07-21T06:00:00.000Z"
  }
}

API Documentation

Custom API reference for integrating with Incentable. RewardStar gift card issuance is available for beta.