Overview
Single-use promotional coupons and vouchers require strict atomic validation so that a pass can never be redeemed twice across different registers or shared via static screenshots. By pairing a coupon template with a ScannerConfiguration set to VOIDED_AFTER_SCAN scan mode, Passinstance validates the barcode, transitions the pass to VOIDED, blocks replay attempts, and triggers an immediate silent wallet update to grey out the pass on the customer's device.
Important: Always include an idempotency key when submitting redemptions from POS terminals (
x-idempotency-keyheader onPOST /api/v1/scans, oridempotencyKeyinrequest payloadonPOST /v1/pos/redeem). If a terminal retries due to a network timeout, Passinstance returns the original acceptance receipt rather than throwing a falseALREADY_VOIDEDerror to the cashier.
Single-Use Redemption Architecture
First Scan: Atomic Redemption (POST /api/v1/scans)
When a cashier scans an active coupon at checkout, the scanner submits the barcode payload to POST /api/v1/scans authenticated by x-scanner-key:
HTTP Request
/api/v1/scans
{
"scannedBarcodeValue": "PI-CPN-774109",
"scannerConfigurationId": "scfg_coupon_checkout",
"operatorId": "cashier_12",
"terminalId": "reg_berlin_01",
"validationData": {
"receiptNumber": "RCPT-2026-88412",
"basketTotal": 64.00
}
}
HTTP Response (200 OK — Accepted & Voided)
{
"decision": "SUCCESS",
"status": "ACCEPTED",
"reasonCode": "PASS_VOIDED_AFTER_SCAN",
"ruleTrace": [
{ "rule": "PassStatusRule", "passed": true },
{ "rule": "ExpirationRule", "passed": true },
{ "rule": "DefaultAcceptanceRule", "passed": true }
],
"passSnapshot": {
"id": "pass_cpn_774109",
"templateId": "tmpl_winter_promo_25",
"serialNumber": "PI-CPN-774109",
"externalId": "promo_order_774109",
"status": "VOIDED",
"expirationDate": "2026-12-31T23:59:59.000Z",
"attributes": {
"offerTitle": "25% Off Winter Collection",
"promoCode": "WINTER25"
}
},
"display": {
"title": "Coupon Redeemed",
"subtitle": "Apply 25% discount — Pass is now voided",
"color": "success"
}
}
Duplicate Scan Rejection (ALREADY_VOIDED)
If the customer attempts to scan the same pass again at another register — or if a second person presents a forwarded screenshot of the barcode — PassStatusRule detects that the pass is already VOIDED and immediately halts execution:
{
"decision": "ALREADY_VOIDED",
"status": "REJECTED",
"reasonCode": "PASS_VOIDED_AFTER_SCAN",
"ruleTrace": [
{
"rule": "PassStatusRule",
"passed": false,
"reasonCode": "PASS_VOIDED_AFTER_SCAN"
}
],
"passSnapshot": {
"id": "pass_cpn_774109",
"templateId": "tmpl_winter_promo_25",
"serialNumber": "PI-CPN-774109",
"externalId": "promo_order_774109",
"status": "VOIDED"
},
"display": {
"title": "Already Redeemed",
"subtitle": "This voucher was already used and is void.",
"color": "error"
}
}
Silent Wallet Push & Visual Grey-Out
Immediately after committing the VOIDED state transition:
-
1
Apple Wallet (
.pkpass): Passinstance signs an updated pass bundle with"voided": trueinpass.jsonand the template's Pass Type Certificate (bundleId= ApplepassTypeIdentifier), then dispatches a silent APNs push notification. iOS automatically desaturates (greys out) the pass face and invalidates the barcode in Apple Wallet. -
2
Google Wallet: Passinstance invokes the Google Wallet REST API to patch the pass object's
statetoCOMPLETED/EXPIRED, removing it from active lock-screen suggestions and displaying a redeemed status banner.
Administrators and backend workers can also manually void individual coupons or batches outside a scan flow via POST /api/v1/passes/voiding/:id/void (request payload) or POST /api/v1/passes/voiding/batch-void (request payload) with a typed VoidingReason.
Retail POS Terminal Redemption (POST /v1/pos/redeem)
Integrated retail point-of-sale systems execute direct single-use voucher redemptions via POS Redemption API (POST /v1/pos/redeem and POST /v1/pos/scan — excluded from the global /api/v1 prefix):
Field (request payload) | Type | Description |
|---|---|---|
idempotencyKey | string (required, max 255) | Unique idempotency key (recommended: tenantId:terminalId:clientTxRef). |
passRef | string (required, max 500) | Scanned barcode value, download token, serialNumber, or externalId / passPublicId. |
operation | PosOperation (required) | supported enum: DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID, or CUSTOM. Use VOID or DISCOUNT for single-use coupons. |
terminalId | string (optional UUID) | UUID of the registered POS terminal (must match credential terminal if bound). |
externalTerminalRef | string (optional) | External register code if not using the Passinstance terminal UUID. |
amount / currency | number / string | Optional discount or transaction amount and ISO-4217 currency code (e.g. EUR). |
clientTxRef | string (optional) | POS receipt or basket transaction reference for audit reconciliation. |
metadata | object (optional) | Opaque basket, cashier, or store context recorded in PosTransaction. |
After committing POST /v1/pos/redeem, the response includes walletPropagation (PosWalletPropagationStatus: QUEUED or SKIPPED) confirming push propagation to Apple Wallet and Google Wallet.
For campaign design best practices, see Coupons & Vouchers and Scan Modes & Validation Rules.
