API Reference

Loyalty

Configure your restaurant's loyalty program, view customer point balances and transaction history, and award bonus points. Points are automatically earned on qualifying orders based on the configured earning rules.

Admin Only

All loyalty endpoints require administrator privileges. Customers interact with the loyalty program indirectly through orders and receipts.

Get Loyalty Settings

Retrieve the current loyalty program configuration for your restaurant.

GET/api/loyalty/settingsAdmin Only

Returns the full loyalty program configuration.

bash

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

json

{
  __PH0__: {
    __PH1__: true,
    __PH2__: 1,
    __PH3__: 100,
    __PH4__: 5.00,
    __PH5__: 50,
    __PH6__: 100,
    __PH7__: 5.00,
    __PH8__: 12,
    __PH9__: "2026-02-15T10:00:00Z"
  }
}

Update Loyalty Settings

Partially update the loyalty program configuration. Only included fields are changed; omitted fields remain as they are.

PUT/api/loyalty/settingsAdmin Only

Applies a partial update to loyalty settings and returns the updated configuration.

Request Body (all optional)

Name	Type	Required	Description
`is_enabled`	`boolean`	Optional	Enable or disable the loyalty program entirely.
`points_per_euro`	`number`	Optional	Points awarded per EUR spent on qualifying orders.
`points_for_redemption`	`integer`	Optional	Number of points required for one redemption unit.
`redemption_value_eur`	`number`	Optional	EUR value of one redemption unit (e.g. 5.00 EUR per 100 points).
`welcome_bonus`	`integer`	Optional	Bonus points granted when a customer first joins the program.
`birthday_bonus`	`integer`	Optional	Bonus points awarded on the customer's birthday.
`min_order_for_points`	`number`	Optional	Minimum order total (EUR) to earn points on a transaction.
`expiry_months`	`integer`	Optional	Number of months after which unused points expire. Set to 0 or null to disable expiry.

bash

curl -X PUT https://api.possfer.com/api/loyalty/settings \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "points_per_euro": 2,
    "welcome_bonus": 100,
    "expiry_months": 24
  }'

Changes take effect immediately

Updated earning rules apply to all future orders. Existing point balances and past transactions are not retroactively recalculated.

Customer Loyalty Transactions

Retrieve the point balance and transaction history for a specific customer.

GET/api/customers/:id/loyaltyAdmin Only

Returns the customer's current point balance and recent loyalty transactions.

Path Parameters

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

Query Parameters

Name	Type	Required	Description
`limit`	`integer`	Optional	Maximum number of transactions to return. Defaults to 50.

bash

curl __PH1__Authorization: Bearer <token>"

json

{
  __PH1__: "c-a1b2c3d4-5678-90ab-cdef-666666666666",
  __PH3__: 320,
  __PH4__: 870,
  __PH5__: 500,
  __PH6__: 50,
  __PH7__: [
    {
      __PH8__: "lt-11112222-3333-4444-5555-666677778888",
      __PH10__: "earn",
      __PH12__: 45,
      __PH13__: "Order __PH0__
      "order_id": "o-99887766-5544-3322-1100-aabbccddeeff",
      "created_at": "2026-03-19T19:__PH49__:00Z"
    },
    {
      "id": "lt-22223333-4444-5555-6666-777788889999",
      "type": "redeem",
      "points": -100,
      "description": "Redeemed for EUR 5.00 discount",
      "order_id": "o-aabbccdd-eeff-0011-2233-445566778899",
      "created_at": "2026-03-15T12:__PH58__:00Z"
    },
    {
      "id": "lt-33334444-5555-6666-7777-888899990000",
      "type": "bonus",
      "points": 50,
      "description": "Welcome bonus",
      "order_id": null,
      "created_at": "2026-02-01T10:__PH64__:00Z"
    }
  ]
}

Award Bonus Points

Manually award bonus points to a customer. Useful for promotions, compensation, or special events.

POST/api/customers/:id/loyalty/bonusAdmin Only

Awards bonus points to the customer and returns the updated balance.

Path Parameters

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

Request Body

Name	Type	Required	Description
`points`	`integer`	Required	Number of bonus points to award. Must be a positive integer.
`description`	`string`	Required	Reason for the bonus, recorded in the transaction log (e.g. "Birthday bonus", "Apology for delayed order").

bash

curl -X POST https://api.possfer.com/api/customers/c-a1b2c3d4-5678-90ab-cdef-666666666666/loyalty/bonus \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "points": 50,
    "description": "Compensation for delayed service"
  }'

json

{
  __PH0__: {
    __PH1__: "lt-44445555-6666-7777-8888-999900001111",
    __PH3__: "bonus",
    __PH5__: 50,
    __PH6__: "Compensation for delayed service",
    __PH8__: "2026-03-20T14:00:00Z"
  },
  __PH10__: 370
}

Audit trail

Every bonus award is recorded with the admin user who initiated it, a timestamp, and the provided description. These records are immutable and included in DSFinV-K exports.