Getting started - Puntjes Docs

Integrate the Puntjes loyalty and rewards API into your point-of-sale system or application.

Authentication

Set up OAuth2 client credentials and start making authenticated API requests.

Core concepts

Understand customers, wallets, earn rules, rewards, and campaigns.

API reference

Complete reference for all endpoints including request and response formats.

Error handling

Error codes, the response they arrive in, and how you catch them.

What is Puntjes?

Puntjes is a loyalty and rewards platform where a vendor (a shop, a retailer) runs a loyalty program for their customers. Through the Puntjes API, your point-of-sale system can:

Register customers and look them up by loyalty card or email
Record transactions and automatically award points based on configurable earn rules
Run campaigns with point multipliers during promotional periods
Offer rewards that customers can redeem with their accumulated points
Track wallet balances with a full append-only ledger of all point movements

Quick start

1. Obtain API credentials

Your Puntjes vendor account comes with an OAuth2 client. You'll need your client ID and client secret to authenticate. These are managed through the admin portal at /admin/api-clients.

2. Get an access token

Request an access token using the OAuth2 client credentials flow:

curl -X POST https://puntjes.app/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

The response includes an access_token valid for 60 minutes:

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1Q..."
}

3. Make your first API call

Look up a customer by their loyalty card identifier:

curl https://puntjes.app/api/v1/customers/lookup?identifier=K7M2QX4P \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
    "data": {
        "id": 1,
        "first_name": "Jan",
        "last_name": "De Vries",
        "email": "jan@example.com",
        "status": "active",
        "wallet_balance": 1500
    }
}

4. Submit a transaction

Record a purchase and earn points automatically:

curl -X POST https://puntjes.app/api/v1/transactions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "K7M2QX4P",
    "idempotency_key": "order-2024-001",
    "total_amount": 2500,
    "description": "Lunch order"
  }'

{
    "data": {
        "id": 42,
        "customer_id": 1,
        "total_amount": 2500,
        "points_earned": 25,
        "rules_applied": [{ "rule_id": 3, "rule_name": "Base rate", "rule_type": "base_rate", "points_earned": 25 }]
    }
}

rules_applied entries carry more than four fields

Abridged for brevity. Every entry also carries family, moment, campaign_version, suppressed_by, reason and line_breakdown: all null for an earn rule, and populated for a campaign. See Transaction endpoints for the full contract.

Amounts are in cents

All monetary amounts in the API are expressed in cents (euro cents). A total_amount of 2500 represents EUR 25.00. Point balances are also stored as integers.

Key concepts

Concept	Description
Vendor	A merchant or retailer running a loyalty program through Puntjes
Customer	An end user enrolled in a vendor's loyalty program
Identifier	A lookup value attached to a customer: their loyalty card code or email address
Wallet	A customer's point balance, backed by an append-only ledger
Earn Rule	A rule that determines how many points a transaction earns
Campaign	A time-bounded promotion that multiplies earned points
Reward	An item (discount or product) a customer can redeem with points
Redemption	A record of a customer spending points on a reward

Base URL

All API endpoints are served under:

https://puntjes.app/api/v1

All requests must include an Authorization: Bearer {token} header. See Authentication for details.