Vouchers and uploads

​

Vouchers

​

Upload a file

FILE=codes-november.csv
curl -sS -X POST "$VOUCHER_API_BASE_URL/provider/v1/voucher-sets/2030/uploads" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "fileName": "'"$FILE"'",
    "format": "csv",
    "sizeBytes": '"$(wc -c < "$FILE" | tr -d ' ')"',
    "sha256": "'"$(shasum -a 256 "$FILE" | cut -d' ' -f1)"'",
    "defaults": {"redemptionType": "single", "validUntil": "2026-12-31T22:59:59Z"}
  }' > upload.json

# The upload target is a signed storage URL, not $VOUCHER_API_BASE_URL; send no API key to it.
UPLOAD_URL=$(jq -r '.data.uploadTarget.url' upload.json)
curl -sS -X PUT "$UPLOAD_URL" -H "Content-Type: text/csv" --data-binary @"$FILE"

UPLOAD_ID=$(jq -r '.data.id' upload.json)
curl -sS -X POST "$VOUCHER_API_BASE_URL/provider/v1/voucher-sets/2030/uploads/$UPLOAD_ID:start" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

​

File format

• CSV: UTF-8 (a BOM is allowed), comma or semicolon separator (detected from the header), RFC 4180 quoting, LF or CRLF line ends.
• XLSX: the first worksheet only; strings, numbers and date cells (read as UTC).
• At most 100 MiB and 1,000,000 data rows.
• A header row is required. Column names are case-insensitive: value (required), redemptionType, maxRedemptions, validFrom, validUntil, metadata (a JSON object as text).
• An empty cell takes the upload’s defaults. In maxRedemptions, the word unlimited means unlimited, even when the defaults set a maximum.

value,redemptionType,maxRedemptions,validUntil,metadata
ACME5-7KQ2-M9Q1,single,,2026-12-31T22:59:59Z,"{""batch"":""nov-2026""}"
ACME5-FAMILY-01,multiple,unlimited,,
ACME5-TEAM-02,multiple,25,2027-03-31T21:59:59Z,

​

Validation and import

1. Validation. The file’s SHA-256 is checked (checksum-mismatch fails the upload), then every row is validated before any voucher is written.
2. Import. With no invalid rows, the import starts automatically. With invalid rows, the upload stops in validated: inspect the errors, then confirm with :import and {"skipInvalidRows": true} to import only the valid rows, or :cancel. A validated upload left for 7 days is cancelled (validation-expired).

curl -sS "$VOUCHER_API_BASE_URL/provider/v1/voucher-sets/2030/uploads/$UPLOAD_ID/errors?perPage=100" \
  -H "Authorization: Bearer $VOUCHER_API_KEY"

​

Batch API

curl -sS -X POST "$VOUCHER_API_BASE_URL/provider/v1/voucher-sets/2030/vouchers:batch" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "defaults": {"redemptionType": "single", "validUntil": "2026-12-31T22:59:59Z"},
    "vouchers": [
      {"value": "ACME5-7KQ2-M9Q1"},
      {"value": "ACME5-FAMILY-01", "redemptionType": "multiple", "maxRedemptions": null, "metadata": {"batch": "family"}}
    ]
  }'

• 201 with {createdCount, items}: compact items (id, valueMask, redemptionType, maxRedemptions, status) in request order.
• Any invalid item → 400 data-failed-validation with one entry per problem (vouchers[17].value); nothing is created.
• A value already in the set → 409 voucher-value-exists, naming each item; a value twice in the request → duplicate-value. Nothing is created.
• More than 1,000 items → 422 batch-too-large.
• Send an Idempotency-Key: a retry then replays the result and never duplicates vouchers.

​

Revoking vouchers

curl -sS -X POST "$VOUCHER_API_BASE_URL/provider/v1/voucher-sets/2030/vouchers:revoke" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"voucherIds": [5031, 5032], "reason": "Leaked on a forum."}'

• Only available vouchers can be revoked; others → 409 voucher-not-revocable. Up to 1,000 ids, all or nothing.
• One voucher: POST /provider/v1/vouchers/{voucherId}:revoke with {"reason": …}.
• Revoked vouchers are never redeemable and never deleted; past redemptions stay.

​

Viewing voucher values

curl -sS -X POST "$VOUCHER_API_BASE_URL/provider/v1/vouchers/5030:reveal" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

• One voucher per call; there is no bulk reveal.
• Every reveal is recorded in your audit log as voucher.revealed (never with the value) and monitored by AllRide.
• An idempotent replay returns "value": null with Idempotent-Replay-Redacted: true.
• To find a voucher by its value, use search on the vouchers list: an exact match on the full value, available only to principals with reveal-provider-vouchers; results stay masked.

​

Related

• Voucher sets
• Dynamic links
• Stock and alerts