Point of sale

Award points or stamps at the till and show the balance on the receipt.

Earn points from a sale

Pass the raw sale — Passtastic applies the card's configured accrual rate. Use from: "spend" for a currency amount, or from: "items" when your POS tracks earn-eligible items by key (e.g. one stamp per coffee, regardless of price). Omit from and pass a flat amount to add a specific number of points or stamps directly.

# Item-based (e.g. "one stamp per coffee")
curl -X POST https://api.passtastic.io/api/v1/customers/crm_10293/earn \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "stamps",
    "from": "items",
    "items": [{ "key": "coffee", "quantity": 1 }]
  }'

Or the spend-based form, for a card that earns points per currency unit spent:

curl -X POST https://api.passtastic.io/api/v1/customers/crm_10293/earn \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sale-98213-earn" \
  -d '{
    "type": "points",
    "from": "spend",
    "spend": { "amount": 24.50, "currency": "EUR" },
    "note": "Order #4821"
  }'

Send an Idempotency-Key — a POS register can retry the same sale on a network blip, and the key stops it from being awarded twice.

Customers who join at the till with only an ID number

If your POS creates the customer at checkout with just their ID number (no email or phone), send "allowClaimByExternalId": true on POST /v1/customers. When the customer then scans the card's QR code and fills in the sign-up form with that same number, the card appears on their screen with the stamps or points they already earned, and any email or phone they type is saved. The card's sign-up form needs an identifier question that holds your externalCustomerId.

This works only until the card is first added to a wallet. After that, someone typing the same number gets the usual check instead (the card is emailed to the address on file, or shown when they type the phone on file), so nobody can take a card that is already on someone's phone. It never applies to paid or merchant-issued cards. Turn it on for customers you created earlier with PATCH /v1/customers/{ref}.

curl -X POST https://api.passtastic.io/api/v1/customers \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardId": "64f1c2a9b8e4a2d1c0a1b2c3",
    "externalCustomerId": "V-27919523",
    "customFields": { "custom_id_number": "V-27919523" },
    "allowClaimByExternalId": true
  }'

Read a customer's balance

curl https://api.passtastic.io/api/v1/customers/crm_10293 \
  -H "X-Api-Key: YOUR_API_KEY"

{
  "externalCustomerId": "crm_10293",
  "passUserId": "66a1e2f3c9d4b5a6f7081920",
  "personId": "per_7Hq2xLm9Pz4Kd8Wv1Rt5",
  "cardId": "64f1c2a9b8e4a2d1c0a1b2c3",
  "name": "Alex Rivera",
  "firstName": "Alex",
  "lastName": "Rivera",
  "cardType": "point_card",
  "balance": { "points": 245 },
  "installed": true,
  "installUrl": "https://passtastic.io/get-pass/64f1c2a9b8e4a2d1c0a1b2c3"
}

name, firstName and lastName are strings, or null when the customer has none.

balance shape depends on the card: { stamps } for stamp cards, { points } for point cards, { points, level } for level cards. Print it on the receipt so the customer sees the result of the sale they just made.

Units. Every balance is a whole number — 245 points, 6 stamps — with one exception: store credit (a card that tracks the merchant's own currency or a custom unit, e.g. "credits") can carry up to 2 decimals, e.g. { "points": 25.5 }. initialPoints on enroll and balanceCorrection/setPoints on adjust follow the same rule.