API Reference

Discounts

Create, update, and manage percentage or fixed-amount discounts. Discounts can target entire orders, specific categories, or individual items and support optional validity windows, usage limits, and minimum order thresholds.

Admin Only

All discount endpoints require administrator privileges. Staff members with lower roles will receive a 403 Forbidden response.

List Discounts

Retrieve all discounts configured for the current restaurant.

GET/api/discountsAdmin Only

Returns an array of all discounts, including inactive ones.

bash

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

json

{
  __PH0__: [
    {
      __PH1__: "d1a2b3c4-5678-90ab-cdef-111111111111",
      __PH3__: "Lunch Special",
      __PH5__: "10 % off all lunch orders",
      __PH7__: "percentage",
      __PH9__: 10,
      __PH10__: 15.00,
      __PH11__: 5.00,
      __PH12__: "order",
      __PH14__: null,
      __PH15__: "2026-01-01T00:00:00Z",
      __PH17__: "2026-12-31T23:59:59Z",
      __PH19__: 500,
      __PH20__: 123,
      __PH21__: true,
      __PH22__: "2026-01-01T12:00:00Z",
      __PH24__: "2026-01-15T09:30:00Z"
    }
  ]
}

Create Discount

Add a new discount rule to your restaurant.

POST/api/discountsAdmin Only

Creates a new discount and returns the full object.

Request Body

Name	Type	Required	Description
`name`	`string`	Required	Display name shown on receipts and in the POS UI.
`description`	`string`	Optional	Internal note or customer-facing description.
`discount_type`	`"percentage" \| "fixed"`	Required	Whether the value is a percentage off or a fixed EUR amount.
`value`	`number`	Required	Discount value. Percentage (0-100) or fixed amount in EUR.
`min_order_amount`	`number`	Optional	Minimum order total (EUR) before this discount may be applied.
`max_discount_amount`	`number`	Optional	Cap on the EUR amount deducted. Useful for percentage discounts.
`applicable_to`	`"order" \| "category" \| "item"`	Optional	Scope of the discount. Defaults to "order" if omitted.
`category_id`	`string (UUID)`	Optional	Required when applicable_to is "category". The target category.
`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.
`usage_limit`	`integer`	Optional	Maximum number of times this discount may be redeemed. Null means unlimited.

bash

curl -X POST https://api.possfer.com/api/discounts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lunch Special",
    "description": "10 % off all lunch orders",
    "discount_type": "percentage",
    "value": 10,
    "min_order_amount": 15.00,
    "max_discount_amount": 5.00,
    "applicable_to": "order",
    "valid_from": "2026-01-01T00:00:00Z",
    "valid_until": "2026-12-31T23:59:59Z",
    "usage_limit": 500
  }'

Update Discount

Partially update an existing discount. Only the fields you include in the request body will be changed.

PUT/api/discounts/:idAdmin Only

Applies a partial update and returns the updated discount.

Path Parameters

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

Partial updates

Send only the fields you want to change. Omitted fields remain untouched. Use is_active to enable or disable a discount without deleting it.

bash

curl -X PUT https://api.possfer.com/api/discounts/d1a2b3c4-5678-90ab-cdef-111111111111 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false,
    "valid_until": "2026-06-30T23:59:59Z"
  }'

Delete Discount

Permanently remove a discount. This action cannot be undone.

DELETE/api/discounts/:idAdmin Only

Deletes the discount and returns 204 No Content on success.

Path Parameters

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

Prefer deactivation

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

bash

curl -X DELETE https://api.possfer.com/api/discounts/d1a2b3c4-5678-90ab-cdef-111111111111 \
  -H "Authorization: Bearer <token>"