Vouchers
createVoucher
Section titled “createVoucher”POST /v1/rewards/vouchers · Scope: write
createVoucher(request: CreateVoucherRequest, options?): Promise<VoucherDto>| Parameter | Type | Description |
|---|---|---|
code |
string |
Required. Unique in your organization. |
title |
string |
Required. |
discountType |
'PERCENTAGE' | 'FIXED_AMOUNT' | 'FREE_ITEM' |
Required unless terms is set. |
terms |
object |
Your own description of the promise. Published on-chain, so no personal data. |
description |
string |
|
pointsCost |
number |
Defaults to 0, a free voucher. |
discountValue |
string |
|
totalSupply |
number | null |
|
startsAt |
string | null |
ISO date-time with seconds and timezone |
expiresAt |
string | null |
ISO date-time with seconds and timezone |
metadata |
object |
|
status |
'DRAFT' | 'ACTIVE' | 'PAUSED' |
Defaults to ACTIVE, which publishes the terms on-chain first. |
VoucherDto adds id, organizationId, claimedCount, publishStatus, suiTermsId, refundPolicy, createdAt and updatedAt.
updateVoucher
Section titled “updateVoucher”Takes any fields from createVoucher. Once publishing starts, everything in the terms is fixed; metadata, supply and status are not. Guide
PATCH /v1/rewards/vouchers/:id · Scope: write
updateVoucher(voucherId: string, request: UpdateVoucherRequest, options?): Promise<VoucherDto>listVouchers
Section titled “listVouchers”GET /v1/rewards/vouchers · Scope: read
listVouchers(options?): Promise<VoucherDto[]>getVoucher
Section titled “getVoucher”GET /v1/rewards/vouchers/:id · Scope: read
getVoucher(voucherId: string, options?): Promise<VoucherDto>claimVoucher
Section titled “claimVoucher”Reserves a voucher. It stays RESERVED until the chain confirms. Guide
POST /v1/rewards/vouchers/:id/claim · Scope: write
claimVoucher(voucherId: string, request: ClaimVoucherRequest, options?): Promise<ClaimVoucherResponse>| Parameter | Type | Description |
|---|---|---|
organizationEndUserId |
string |
Required. A UUID. |
idempotencyKey |
string |
Required. 1–100 letters, numbers, :, _ or -. |
| Returned field | Type | Description |
|---|---|---|
voucherOwnershipId |
string |
Use it with getVoucherClaim. |
voucherId |
string |
|
organizationEndUserId |
string |
|
serialCode |
string |
Use it with prepareVoucherUse once AVAILABLE. |
status |
VoucherOwnershipStatus |
|
pointsDeducted |
number |
Zero until the chain confirms. |
pointsCost |
number |
|
transactionId |
string | null |
The REDEEM transaction. Use it to reverse the claim. |
digest |
string | null |
Present on a claim response while RESERVED |
transactionBytes |
string | null |
Present on a claim response while RESERVED |
refundPolicy |
VoucherRefundPolicySnapshot |
Published with the voucher’s terms |
claimedAt |
string |
|
expiresAt |
string | null |
getVoucherClaim
Section titled “getVoucherClaim”Reads the saved state of a claim. It doesn’t return signing bytes or a digest.
GET /v1/rewards/claims/:id · Scope: read
getVoucherClaim(ownershipId: string, options?): Promise<ClaimVoucherResponse>finalizeVoucherClaim
Section titled “finalizeVoucherClaim”Submits the customer’s signature for a claim, on the same route as finalizePosRedemption. Your API key isn’t what authorizes it.
POST /v1/credits/redeem/finalize · Public: the signature authorizes it
finalizeVoucherClaim(request: { digest: string; signature: string }, options?): Promise<FinalizePosRedemptionResponse>grantVoucher
Section titled “grantVoucher”Gives a customer a voucher without spending their points. It stays RESERVED until the chain records it, and voucher.granted reports that. Guide
POST /v1/rewards/vouchers/:id/grant · Scope: write
grantVoucher(voucherId: string, request: GrantVoucherRequest, options?): Promise<ClaimVoucherResponse>| Parameter | Type | Description |
|---|---|---|
organizationEndUserId |
string |
Required. A UUID. |
idempotencyKey |
string |
Required. 1–100 letters, numbers, :, _ or -. |
prepareVoucherUse
Section titled “prepareVoucherUse”Asks the customer to use a voucher. It returns bytes for their device to sign and marks nothing used. Guide
POST /v1/rewards/vouchers/use · Scope: write
prepareVoucherUse(request: PrepareVoucherUseRequest, options?): Promise<PrepareVoucherUseResponse>| Parameter | Type | Description |
|---|---|---|
serialCode |
string |
Required. 1–100 letters, numbers, _ or -. |
idempotencyKey |
string |
Required. 1–100 letters, numbers, :, _ or -. |
Returns voucherOwnershipId, voucherId, serialCode, status, digest, transactionBytes, voucherTitle, discountType and discountValue. digest and transactionBytes are null once the use has settled.
finalizeVoucherUse
Section titled “finalizeVoucherUse”Submits the customer’s signature for a use. In a browser, use auth.signAndFinalizeVoucherUse.
POST /v1/rewards/vouchers/use/finalize · Public: the signature authorizes it
finalizeVoucherUse(request: { digest: string; signature: string }, options?): Promise<RedeemVoucherResponse>Returns voucherOwnershipId, voucherId, serialCode, status, redeemedAt, voucherTitle, discountType, discountValue and blockchainDigest.
listMemberVouchers
Section titled “listMemberVouchers”GET /v1/rewards/members/:memberId/vouchers · Scope: read
listMemberVouchers(memberId: string, options?): Promise<VoucherOwnershipDto[]>getVoucherRefundPolicy
Section titled “getVoucherRefundPolicy”Reads the policy the next published voucher takes.
GET /v1/rewards/refund-policy · Scope: read
getVoucherRefundPolicy(options?): Promise<VoucherRefundPolicyDto>setVoucherRefundPolicy
Section titled “setVoucherRefundPolicy”Sets the policy for vouchers published from now on. Settings
PUT /v1/rewards/refund-policy · Scope: admin
setVoucherRefundPolicy(request: SetVoucherRefundPolicyRequest, options?): Promise<VoucherRefundPolicyDto>listVoucherRefundPolicyHistory
Section titled “listVoucherRefundPolicyHistory”Lists policy versions, newest first.
GET /v1/rewards/refund-policy/history · Scope: admin
listVoucherRefundPolicyHistory(query?: { limit?: number; beforeVersion?: number }, options?): Promise<VoucherRefundPolicyDto[]>limit is 1–100 and defaults to 50. beforeVersion is an exclusive cursor: pass the last version of the previous page.