App
For developers

Punkto public API

Embed Punkto's loyalty program into your own product — award and redeem points, generate redeem QR codes, look up a customer's balance, referral link, name and avatar.

Request accessSign in to your business dashboard to apply — it's free.

How it works

1

Submit a request

In your Business dashboard → Settings → API, tell us what you're building and why you need access.

2

We review it

Our team checks the request — usually within a couple of days.

3

Get your key

Once approved, your API key appears in the dashboard. Copy it right away — for security, it's shown only once.

Authentication

Every request needs your API key as a Bearer token in the Authorization header. All endpoints act on behalf of your business; customers are identified by phone number, since third-party apps have no internal Punkto customer ID.

Authorization: Bearer $PUNKTO_API_KEY

Endpoints

GET/business

Your business profile

Read your own business's public details plus its points/discount configuration — hours, address, points-per-currency-unit, max discount ratio and tiers — so your integration can self-configure instead of hardcoding limits.

Request

curl https://api.punkto.app/api/public/v1/business \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Response

{
  "business": {
    "id": "cknq0abc10000...",
    "name": "Coffee Corner",
    "slug": "coffee-corner",
    "city": "Warszawa",
    "workingHours": { "mon": { "open": "08:00", "close": "18:00" } },
    "pointsPerCurrencyUnit": 0.1,
    "maxDiscountRatio": 0.2,
    "maxDiscountPerReceipt": null,
    "discountTiers": null,
    "category": { "slug": "cafes", "name": "Cafes" }
  }
}
POST/points/earn

Award points

Credit points to a customer after a purchase — the same rate as your in-app QR-scan flow (rounded down).

Request

curl -X POST https://api.punkto.app/api/public/v1/points/earn \
  -H "Authorization: Bearer $PUNKTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+48123456789", "amount": 49.90}'

Response

{
  "balance": 5,
  "transaction": {
    "id": "cknq0x1a20001...",
    "type": "earn",
    "points": 5,
    "createdAt": "2026-09-23T23:16:50.250Z"
  }
}
POST/points/redeem

Deduct points

Redeem points as a discount against a receipt total. The amount is automatically capped by your configured discount limits.

Request

curl -X POST https://api.punkto.app/api/public/v1/points/redeem \
  -H "Authorization: Bearer $PUNKTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+48123456789", "points": 20, "receiptAmount": 49.90}'

Response

{
  "balance": 130,
  "discountAmount": 20,
  "transaction": {
    "id": "cknq0x1a20002...",
    "type": "redeem",
    "points": 20,
    "createdAt": "2026-09-23T23:18:12.104Z"
  }
}
POST/points/redeem-code

Generate a redeem QR code

Issue a short-lived code (2 minutes) a customer can use to redeem points in person. Render `code` as a QR yourself, or let them type the 6-digit `shortCode`.

Request

curl -X POST https://api.punkto.app/api/public/v1/points/redeem-code \
  -H "Authorization: Bearer $PUNKTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+48123456789", "points": 20}'

Response

{
  "code": "eyJhbGciOiJIUzI1NiIs...",
  "shortCode": "482913",
  "expiresIn": 120,
  "requestedPoints": 20,
  "grantedPoints": 20,
  "capped": false
}
GET/businesses

List businesses

Public directory of active Punkto businesses — the same list shown in the customer app.

Request

curl https://api.punkto.app/api/public/v1/businesses \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Response

{
  "businesses": [
    {
      "id": "cknq0abc10000...",
      "slug": "coffee-corner",
      "name": "Coffee Corner",
      "logoUrl": "https://...",
      "city": "Warszawa",
      "category": { "slug": "cafes", "name": "Cafes" }
    }
  ]
}
GET/rewards

List your rewards

Your business's special offers/rewards catalog — the same list shown in the customer app's business detail popup.

Request

curl https://api.punkto.app/api/public/v1/rewards \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Response

{
  "rewards": [
    {
      "id": "cknq0rwd10000...",
      "name": "Free coffee",
      "costPoints": 100,
      "discountType": "amount",
      "discountValue": 10
    }
  ]
}
POST/rewards/:rewardId/redeem

Redeem a reward

Redeem a specific named reward for a customer (e.g. "Free coffee") instead of a generic points discount — deducts its cost in points from their balance.

Request

curl -X POST https://api.punkto.app/api/public/v1/rewards/cknq0rwd10000.../redeem \
  -H "Authorization: Bearer $PUNKTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+48123456789"}'

Response

{
  "balance": 50,
  "reward": { "id": "cknq0rwd10000...", "name": "Free coffee", "costPoints": 100 },
  "transaction": {
    "id": "cknq0x1a20003...",
    "type": "redeem",
    "points": -100,
    "createdAt": "2026-09-23T23:53:15.497Z"
  }
}
GET/products

List your products/services

Your business's product/service catalog — the same list shown in the customer app.

Request

curl https://api.punkto.app/api/public/v1/products \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Response

{
  "products": [
    { "id": "cknq0prd10000...", "name": "Cappuccino", "price": 14.5, "emoji": "☕" }
  ]
}
GET/customers/:phone/balance

Customer points balance

Look up how many points a customer currently has.

Request

curl https://api.punkto.app/api/public/v1/customers/+48123456789/balance \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Response

{
  "points": 150
}
GET/customers/:phone/history

Customer points history

A customer's points transactions at your business, newest first — useful for reconciliation. Capped to `limit` rows (default 50, max 200).

Request

curl "https://api.punkto.app/api/public/v1/customers/+48123456789/history?limit=20" \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Response

{
  "transactions": [
    { "id": "cknq0x1a20001...", "type": "earn", "points": 5, "createdAt": "2026-09-23T23:16:50.250Z" },
    { "id": "cknq0x1a20002...", "type": "redeem", "points": -20, "createdAt": "2026-09-23T23:18:12.104Z" }
  ]
}
GET/customers/:phone/referral

Customer referral link

Get a customer's referral code — new signups who enter it are linked as referred by them.

Request

curl https://api.punkto.app/api/public/v1/customers/+48123456789/referral \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Response

{
  "referralCode": "GT2DEY"
}
GET/customers/:phone/profile

Customer name & avatar

Read a customer's display name and avatar.

Request

curl https://api.punkto.app/api/public/v1/customers/+48123456789/profile \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Response

{
  "name": "Anna Kowalska",
  "avatarUrl": "https://..."
}
PATCH/customers/:phone/profile

Update name & avatar

Update a customer's display name and/or avatar URL.

Request

curl -X PATCH https://api.punkto.app/api/public/v1/customers/+48123456789/profile \
  -H "Authorization: Bearer $PUNKTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Anna Kowalska"}'

Response

{
  "name": "Anna Kowalska",
  "avatarUrl": "https://..."
}

Good to know

  • Customers are identified by phone number — a third-party app has no internal Punkto customer ID to work with.
  • If a phone number doesn't belong to a registered Punkto customer, the endpoint returns 404 rather than creating an account.
  • Points earned are rounded down; points redeemed automatically respect your configured discount tiers — no extra logic needed on your side.

Ready to integrate?

Requests are reviewed by our team while the public API is still being finalized — tell us about your app and we'll get back to you.

Request access

Download the partner app

Get new customers fast and affordably

App StoreGoogle Play