BLOK

Developer API

Add BLOK loyalty to your own app or POS, server to server.

Authentication

Generate a key in your dashboard under Settings, “Developer API”. Send it on every request as a bearer token. The key is shown once at creation; only its hash is stored, so if you lose it you rotate rather than recover. Keep it server-side.

Authorization: Bearer blok_live_xxxxxxxxxxxxxxxxxxxxxxxx

Base URL and errors

All endpoints live under https://scanblok.com/api/v1. Every error uses the same envelope with a matching HTTP status:

{ "error": { "code": "insufficient", "message": "Not enough points yet." } }

Endpoints

POST /api/v1/customers

Enroll a new member on your shop. All fields optional. Pass emailOptIn only when the customer actually agreed to reminder emails. Returns the scanCode you use on the other endpoints.

{ "displayName": "Sam", "email": "sam@example.com", "emailOptIn": true }

POST /api/v1/checkins

Record a visit and award points. Optional amountCents (spend mode) or bonusPoints. The existing daily caps, cooldown and campaign multipliers apply.

{ "scanCode": "aB3...", "amountCents": 1200 }

GET /api/v1/customers/:scanCode

Read a member's current balance, visit count and the last 20 ledger events.

GET /api/v1/rewards

Your active reward catalog: id, name, emoji and costPoints.

POST /api/v1/redemptions

Burn points for a reward. Deducts immediately and returns a single-use voucher token that expires in 10 minutes.

{ "scanCode": "aB3...", "rewardId": "clx..." }

POST /api/v1/redemptions/:token/finalize

Mark the voucher redeemed when the reward is handed over.

A typical flow

  1. Enroll a customer when they sign up, store the scanCode.
  2. Record a check-in on each visit or purchase.
  3. Read the balance to show it in your app.
  4. Create a redemption, then finalize it at hand-over.