API Reference

Vouchers

Issue, validate, and redeem voucher codes and gift cards. Vouchers support both fixed-value and percentage types, optional usage caps, and configurable validity windows.

Admin Only

All voucher endpoints require administrator privileges unless otherwise noted.

List Vouchers

Retrieve all vouchers for the current restaurant.

GET/api/vouchersAdmin Only

Returns an array of all vouchers, including redeemed and expired ones.

bash

curl https://api.possfer.com/api/vouchers \
  -H "Authorization: Bearer <token>"

json

{
  __PH0__: [
    {
      __PH1__: "v1a2b3c4-5678-90ab-cdef-222222222222",
      __PH3__: "WELCOME25",
      __PH5__: "percentage",
      __PH7__: 25,
      __PH8__: 25,
      __PH9__: 20.00,
      __PH10__: 100,
      __PH11__: 14,
      __PH12__: "2026-01-01T00:00:00Z",
      __PH14__: "2026-06-30T23:59:59Z",
      __PH16__: true,
      __PH17__: "2026-01-01T10:00:00Z",
      __PH19__: "2026-02-10T08:15:00Z"
    }
  ]
}

Get Voucher

Retrieve a single voucher by its unique identifier.

GET/api/vouchers/:idAdmin Only

Returns the full voucher object including redemption statistics.

Path Parameters

Name	Type	Required	Description
`id`	`string (UUID)`	Required	Unique identifier of the voucher.

bash

curl https://api.possfer.com/api/vouchers/v1a2b3c4-5678-90ab-cdef-222222222222 \
  -H "Authorization: Bearer <token>"

Create Voucher

Issue a new voucher code for your restaurant.

POST/api/vouchersAdmin Only

Creates a new voucher and returns the full object with its generated ID.

Request Body

Name	Type	Required	Description
`code`	`string`	Required	Unique alphanumeric voucher code customers will enter at checkout.
`voucher_type`	`"percentage" \| "fixed"`	Required	Whether the voucher grants a percentage off or a fixed EUR credit.
`original_value`	`number`	Required	Face value. Percentage (0-100) or fixed amount in EUR.
`min_order_amount`	`number`	Optional	Minimum order total (EUR) required to use this voucher.
`max_uses`	`integer`	Optional	Maximum total redemptions allowed. Null means unlimited.
`valid_from`	`string (ISO 8601)`	Optional	Start of the validity window. Defaults to now.
`valid_until`	`string (ISO 8601)`	Optional	End of the validity window. Null means no expiry.

bash

curl -X POST https://api.possfer.com/api/vouchers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME25",
    "voucher_type": "percentage",
    "original_value": 25,
    "min_order_amount": 20.00,
    "max_uses": 100,
    "valid_from": "2026-01-01T00:00:00Z",
    "valid_until": "2026-06-30T23:59:59Z"
  }'

Update Voucher

Update select fields of an existing voucher.

PUT/api/vouchers/:idAdmin Only

Applies a partial update to the voucher and returns the updated object.

Path Parameters

Name	Type	Required	Description
`id`	`string (UUID)`	Required	Unique identifier of the voucher.

Request Body

Name	Type	Required	Description
`is_active`	`boolean`	Optional	Enable or disable the voucher.
`valid_until`	`string (ISO 8601)`	Optional	Extend or shorten the validity window.
`max_uses`	`integer`	Optional	Adjust the maximum number of redemptions.

bash

curl -X PUT https://api.possfer.com/api/vouchers/v1a2b3c4-5678-90ab-cdef-222222222222 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false,
    "valid_until": "2026-03-31T23:59:59Z"
  }'

Delete Voucher

Permanently remove a voucher. This action cannot be undone.

DELETE/api/vouchers/:idAdmin Only

Deletes the voucher and returns 204 No Content on success.

Path Parameters

Name	Type	Required	Description
`id`	`string (UUID)`	Required	Unique identifier of the voucher to delete.

Prefer deactivation

For audit-trail purposes, consider setting is_active: false via the update endpoint instead of permanently deleting vouchers.

bash

curl -X DELETE https://api.possfer.com/api/vouchers/v1a2b3c4-5678-90ab-cdef-222222222222 \
  -H "Authorization: Bearer <token>"

Validate Voucher Code

Check whether a voucher code is valid and eligible for redemption without actually consuming a use.

GET/api/vouchers/validate?code=Admin Only

Returns the voucher details and validity status.

Query Parameters

Name	Type	Required	Description
`code`	`string`	Required	The voucher code to validate.

bash

curl __PH1__Authorization: Bearer <token>"

json

{
  __PH0__: true,
  __PH1__: {
    __PH2__: "v1a2b3c4-5678-90ab-cdef-222222222222",
    __PH4__: "WELCOME25",
    __PH6__: "percentage",
    __PH8__: 25,
    __PH9__: 25,
    __PH10__: true
  },
  __PH11__: null
}

Validation only

This endpoint does not consume a use. To apply the voucher to an order, use the Redeem Voucher endpoint below.

Redeem Voucher

Apply a voucher to an order. This increments the usage counter and, for fixed-value vouchers, reduces the remaining balance.

POST/api/vouchers/redeemAdmin Only

Redeems the voucher against the specified order and returns the applied discount amount.

Request Body

Name	Type	Required	Description
`code`	`string`	Required	The voucher code to redeem.
`order_id`	`string (UUID)`	Required	The order to apply the voucher to.

bash

curl -X POST https://api.possfer.com/api/vouchers/redeem \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME25",
    "order_id": "o9f8e7d6-5432-10ab-cdef-333333333333"
  }'

json

{
  __PH0__: true,
  __PH1__: 12.50,
  __PH2__: {
    __PH3__: "v1a2b3c4-5678-90ab-cdef-222222222222",
    __PH5__: "WELCOME25",
    __PH7__: 25,
    __PH8__: 15
  }
}

Idempotency

Each voucher can only be applied once per order. Attempting to redeem the same code against the same order will return a 409 Conflict error.