Voucher API (Gutscheine)

The Voucher API is the programmatic interface to APRO’s central voucher ledger — the same system that powers in-store gift cards, online voucher shops, and loyalty credit. Balances are authoritative server-side; every operation returns the updated voucher so the caller never has to track state locally.

Host: cloudgateway.apro.at (path prefix /voucherservice/)
Auth: API key in x-api-key
Content type: application/json
Upstream reference: api-docs.apro.at → voucherservice ↗

Amounts

All monetary fields are integer minor units (cents) — 5000 means € 50.00. balance is the currently-available amount; amount is the original face value; maxAmount (optional) caps the ceiling for top-ups.

Voucher shape

The voucher object appears in every response. Fields:

Field	Type	Description
`id`	GUID	Internal APRO voucher ID. Use this in URL paths.
`voucherCode`	string	Human-readable code printed on the card/receipt.
`gift.amount`	integer	Original face value (minor units).
`gift.balance`	integer	Available balance (minor units).
`gift.maxAmount`	integer \| null	Ceiling for top-ups; `null` = uncapped.
`codeId`	string \| null	Optional secondary identifier.
`startDate`	ISO 8601 \| null	Not valid before.
`expirationDate`	ISO 8601 \| null	Not valid after.
`enabled`	bool	`false` = manually disabled/blocked.
`comment`	string \| null	Free-form staff note.
`categoryId`	integer	Voucher category (issuing channel).
`categoryName`	string	Category display name.
`categoryNrOfTimesRedeemablePerUnit`	integer \| null	Category-level redemption-count cap.
`categoryExternalPaymentProviderId`	string \| null	Upstream payment-provider reference.
`createdAt`	ISO 8601	When the voucher was issued.
`discriminator`	string	`"GiftVoucherDto"` for gift cards.

1. List vouchers

GET https://cloudgateway.apro.at/voucherservice/api/v1/vouchers

Returns every voucher visible to the API key. Use the validity endpoint instead when you just need to look up one code — it’s indexed for that path.

2. Check validity

GET https://cloudgateway.apro.at/voucherservice/api/v1/vouchers/validity
    ?voucherCode=560620085

Query parameters

Name	Type	Required	Description
`voucherCode`	string	✅	The code printed on the voucher.

Example response

{
  "voucher": {
    "gift": { "amount": 5000, "balance": 3880, "maxAmount": null },
    "id": "f5f4d577-3764-4c25-12f8-08db73dad741",
    "voucherCode": "560620085",
    "codeId": null,
    "startDate": null,
    "expirationDate": null,
    "enabled": true,
    "comment": null,
    "categoryId": 4,
    "categoryName": "OnlineGutschein",
    "categoryNrOfTimesRedeemablePerUnit": null,
    "categoryExternalPaymentProviderId": null,
    "createdAt": "2023-06-23T11:13:15.6386753",
    "discriminator": "GiftVoucherDto"
  },
  "errors": [],
  "isValid": true
}

Download: voucher-validity-response.json

isValid: false + a populated errors array indicates why the voucher cannot be redeemed right now (expired, disabled, wrong date window, redemption cap reached). Common error codes:

Error	Meaning
`NotFound`	`voucherCode` does not exist.
`Expired`	Past `expirationDate`.
`NotYetStarted`	Before `startDate`.
`Disabled`	`enabled = false`.
`NoBalance`	`balance == 0`.
`CategoryCapReached`	`categoryNrOfTimesRedeemablePerUnit` exhausted.

3. Issue a voucher

POST https://cloudgateway.apro.at/voucherservice/api/v1/vouchers/gifts

Creates a new gift voucher. On success the HTTP status is 201 Created and the response Location header points at the new resource.

Request body

Field	Type	Required	Description
`categoryId`	integer	✅	Which voucher category to issue under.
`voucherCode`	string	✅	Code to print on the voucher. Must be unique.
`comment`	string	—	Staff note.
`gift.amount`	integer	✅	Face value in minor units.
`gift.maxAmount`	integer	—	Top-up ceiling.
`clientType`	string	✅	Identifier of the calling system. Provided by APRO for your integration — see clientType.
`clientContext`	string (JSON)	—	Serialised JSON for side-channel context (outlet etc.).
`startDate`	ISO 8601	—	Not valid before.
`expirationDate`	ISO 8601	—	Not valid after.

Example request

{
  "categoryId": 1,
  "voucherCode": "2131231",
  "comment": "Gift card — reprint for a lost original",
  "gift": { "amount": 50, "maxAmount": 10000 },
  "clientType": "<provided-by-apro>",
  "clientContext": "{\"outletId\":\"231231\"}",
  "startDate": "2026-01-01T00:00:00",
  "expirationDate": "2028-12-31T23:59:59"
}

Download: voucher-issue-request.json

Example response

{
  "data": {
    "gift": { "amount": 50, "balance": 50, "maxAmount": 10000 },
    "id": "e961c17d-d037-4d27-734d-08ddda944e39",
    "voucherCode": "2131231",
    "categoryId": 1,
    "categoryName": "Standard",
    "enabled": true,
    "comment": "Gift card — reprint for a lost original",
    "startDate": "2026-01-01T00:00:00",
    "expirationDate": "2028-12-31T23:59:59",
    "createdAt": "2026-04-20T21:33:00.000+02:00",
    "discriminator": "GiftVoucherDto"
  }
}

Download: voucher-issue-response.json

4. Redeem a voucher

POST https://cloudgateway.apro.at/voucherservice/api/v1/vouchers/{voucherId}/redemption

Burns amount minor units off the balance. Path parameter is the voucher’s internal id (not the voucherCode) — you get it from /validity.

Request body

Field	Type	Required	Description
`redemption.amount`	integer	✅	Amount to debit in minor units.
`clientReference`	string	—	Opaque trace string (e.g. `"{ \"waiterId\": 10 }"`). Stored and returned on the transaction.
`clientContext`	string (JSON)	—	Side-channel context.
`comment`	string	—	Staff note.
`clientType`	string	✅	Identifier of the calling system. Provided by APRO — see clientType.

Example request

{
  "redemption": { "amount": 50 },
  "clientReference": "{ \"waiterId\": 10 }",
  "clientContext": "{\"outletId\":\"231231\"}",
  "comment": "Redeemed at Bar 2 against receipt 5906",
  "clientType": "<provided-by-apro>"
}

Download: voucher-redeem-request.json

Example response

{
  "data": {
    "redemption": { "amount": 50, "items": [] },
    "success": true,
    "errors": [],
    "transactionId": 21142,
    "voucher": {
      "gift": { "amount": 5000, "balance": 3830, "maxAmount": null },
      "id": "f5f4d577-3764-4c25-12f8-08db73dad741",
      "voucherCode": "560620085",
      "categoryId": 4,
      "categoryName": "OnlineGutschein",
      "enabled": true,
      "discriminator": "GiftVoucherDto"
    }
  }
}

Download: voucher-redeem-response.json

The transactionId (integer) is the authoritative ID for this redemption — persist it for reconciliation and refunds.

5. Top up a voucher

POST https://cloudgateway.apro.at/voucherservice/api/v1/vouchers/{voucherId}/booking

Adds amount minor units back onto the voucher, e.g. when a customer re-charges a multi-use card or a refund flows back.

Request body

Field	Type	Required	Description
`amount`	integer	✅	Amount to credit in minor units. Must respect `gift.maxAmount` if set.
`clientReference`	string	—	Opaque trace string.
`clientType`	string	✅	Identifier of the calling system. Provided by APRO — see clientType.
`clientContext`	string (JSON)	—	Side-channel context.
`comment`	string	—	Staff note.

Example request

{
  "amount": 1000,
  "clientReference": "{ \"waiterId\": 10 }",
  "clientType": "<provided-by-apro>",
  "clientContext": "{\"outletId\":\"231231\"}",
  "comment": "Top-up after customer added credit"
}

Download: voucher-booking-request.json

Example response

{
  "data": {
    "newAmount": 4830,
    "success": true,
    "errors": [],
    "transactionId": 21143,
    "voucher": {
      "gift": { "amount": 5000, "balance": 4830, "maxAmount": null },
      "id": "f5f4d577-3764-4c25-12f8-08db73dad741",
      "voucherCode": "560620085",
      "categoryName": "OnlineGutschein",
      "enabled": true,
      "discriminator": "GiftVoucherDto"
    }
  }
}

Download: voucher-booking-response.json

clientType

clientType identifies the calling system so the voucher ledger knows which integration created a transaction. APRO assigns a clientType value to every integration at onboarding time — the exact string is not self-selectable and is shared with you together with the API key. Always use the value provided by APRO; never hard-code a guess.

Error handling

HTTP 4xx on validation failures (bad voucherId, malformed body, missing auth). See Authentication → Error responses.
HTTP 200 with success: false on business rule failures (insufficient balance, expired, etc.). Inspect the errors array.
Never replay a redemption on the client side. If a response times out, query /validity to confirm the balance before retrying — the operation may already be applied server-side.