Earn Rules

Earn rules define how customers earn points from their purchases. When a transaction is submitted, Puntjes evaluates the vendor's active earn rules that cover the purchase and awards points accordingly.

---

Rule types

Base rate

The most common rule type. Points are calculated based on the transaction amount:

points = (transaction_amount / 100) × rate

For example, with a rate of 10 and a transaction amount of 2500 (EUR 25.00):

points = (2500 / 100) × 10 = 250 points

Which rate pays

A base rate either names the branches it applies at, or names none, and a rule that names none applies at all of them. Which rate pays a purchase is settled before any points are calculated: the rates naming the purchase's branch apply, and the rest are skipped. Only when no rate names that branch do the vendor-wide ones pay.

A purchase submitted without a branch earns from the vendor-wide rates alone. A branch-scoped rate never pays on an unattributed purchase.

At most one active rate may be vendor-wide, and no two active rates may name the same branch, so this always settles on a single rate.

Multiplier bonuses live on campaigns

Bonus multipliers are not an earn rule type. They belong to campaigns, which are evaluated by their own engine and reported separately in the transaction response.

---

Rule properties

Field	Type	Description
id	integer	Unique rule ID
name	string	Descriptive name (e.g., "Standard earn rate")
type	string	base_rate
rate	integer	Points per EUR
min_transaction_amount	integer	Minimum transaction amount (in cents) to trigger this rule. Optional.
status	string	active or inactive

---

How rules are applied

When a transaction is submitted:

1. All active earn rules for the vendor are fetched
2. Base rates are narrowed to the transaction's branch: those naming it, or the vendor-wide ones when none does
3. Each surviving rule checks if the transaction meets its conditions (e.g., minimum amount)
4. The appropriate strategy calculates the points for each matching rule
5. Points from all matching rules are summed
6. The total is credited to the customer's wallet as an earn ledger entry

The transaction response includes a breakdown of everything that was considered: earn rules and campaigns alike, with each one's individual point contribution:

{
    "data": {
        "id": 42,
        "total_amount": 2500,
        "points_earned": 500,
        "rules_applied": [
            {
                "rule_id": 3,
                "rule_name": "Standard rate",
                "rule_type": "base_rate",
                "points_earned": 250,
                "family": null,
                "moment": null,
                "campaign_version": null,
                "suppressed_by": null,
                "reason": null,
                "line_breakdown": null
            },
            {
                "rule_id": 7,
                "rule_name": "Weekend Double Points",
                "rule_type": "campaign",
                "points_earned": 250,
                "family": "transaction",
                "moment": null,
                "campaign_version": 1,
                "suppressed_by": null,
                "reason": null,
                "line_breakdown": null
            }
        ]
    }
}

Every rule that was evaluated is listed whether or not it paid, so an entry with points_earned: 0 is normal. The rule applied and the transaction met no minimum. A base rate skipped in step 2 is absent instead, because reporting a rate that was never evaluated as having earned nothing would describe a calculation that did not happen. See the rules_applied breakdown for the full field reference.

---

Minimum transaction amount

Rules can specify a min_transaction_amount in cents. Transactions below this threshold will not trigger the rule. This allows vendors to:

• Only award base points on purchases above a certain value
• Withhold campaign multiplier bonuses on those same purchases, because a multiplier is applied to the base points that were actually credited, and below the threshold that figure is zero

---

Rule changes

Changes to earn rule rates are tracked with a history of old and new values plus the timestamp of the change. This provides an audit trail for rate adjustments.