Build a POS integration

Start with one tested stamp request and webhook receipt before building a complete POS adapter. This walkthrough models the customer and cashier journey as well as the API calls behind it. It uses the marketplace endpoints because one request can resolve the customer, select the programme, find or create the enrolment, and post loyalty safely.

1. Connect

Confirm the business and choose the exact card and location.

2. Transact

Scan or match the customer, then accrue loyalty with durable IDs.

3. Recover

Reverse refunds, retry timeouts, and reconcile missed events.

Choose the installation model

One business
Marketplace app
Development

Create a dedicated API key in that business’s dashboard. This is the simplest model for an in-house connector, one Odoo database, or one POS merchant.Grant MARKETPLACE, plus LOCATIONS_READ when the integration maps stores. Add separate read scopes only for reconciliation jobs that need them.

Start with a pk_test_... key. Test writes create isolated ledger rows but do not alter live balances, wallet passes, or analytics. Test mode cannot create live customers or enrolments, so prepare an existing enrolment first.

The till journey

Step 1: confirm the installation

curl "$PERKSTAR_API_URL/marketplace/ping" \
  --header "Authorization: Bearer $PERKSTAR_API_KEY"

Persist the returned organisation ID, currency, timezone, key mode, and card choices. If default_card_id is null, the business has more than one active card. Ask the operator to map each till programme or location to a specific card_id; never select the first result silently.

A credential belongs to one Perkstar organisation. If the response names a different business from the one your installation expects, stop setup rather than writing to it.

Step 2: map stores and programmes

Use GET /locations with LOCATIONS_READ to resolve Perkstar location IDs. Store a mapping instead of comparing display names.

POS concept	Perkstar value	Rule
Merchant/account	Organisation ID from `marketplace/ping`	Immutable installation owner
Loyalty programme	`card_id`	Explicit when several cards are active
Store/site	`location_id`	Map once, refresh when configuration changes
Order/payment	`external_transaction_id`	Stable and permanently unique for the business
Request attempt	`Idempotency-Key`	Reuse for every retry of the same operation

Step 3: identify the customer

Perkstar resolves identifiers in a fixed priority. Send only identifiers that belong to the same person.

Perkstar Customer ID
Wallet scan
POS customer ID
Email or phone

{
  "identifier": {
    "customer_id": "cus_123"
  }
}

Map this opaque ID from an earlier Perkstar API or Zapier step. It is scoped to the connected business. An unknown ID returns 404 and never creates a replacement customer from the ID alone.

{
  "identifier": {
    "card_serial": "exact-value-returned-by-the-scanner"
  }
}

Pass the scanned content unchanged. Current opaque POS identifiers and older numeric/serial formats are supported. Do not parse, group, truncate, convert case, or assume a fixed length.

{
  "identifier": {
    "external_ref": "odoo:company_4:partner_981"
  }
}

Namespace stable IDs with the provider and account so two merchants cannot accidentally generate the same local reference.

{
  "identifier": {
    "email": "alice@example.com"
  }
}

Use contact details only when the POS has collected them legitimately. An email match is case-insensitive; phone matching prefers normalised E.164 and retains the stored raw value as a compatibility fallback.

Resolution order is customer_id, card_serial, first-party provider identity, external_ref, email, then phone. The first match wins.

Step 4: add loyalty

curl --request POST "$PERKSTAR_API_URL/marketplace/accrue" \
  --header "Authorization: Bearer $PERKSTAR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: odoo:company_4:order_94721:loyalty" \
  --data '{
    "identifier": { "card_serial": "value-from-scanner" },
    "card_id": "card_123",
    "transaction": {
      "type": "STAMP",
      "delta": 1,
      "external_transaction_id": "odoo:company_4:order_94721",
      "metadata": { "locationId": "location_123" }
    }
  }'

Stamp card
Points from spend
Manual adjustment

Send type: "STAMP" and the number of stamps in delta. Most integrations send 1 after an eligible completed sale or visit.

Send the qualifying amount in amount_pence. Perkstar applies the card’s current points rule. Send an explicit delta only when the upstream system is contractually authoritative for the points amount.

Use ADJUST only for an intentional correction with a useful note. A refund should use reversal so the audit trail remains linked.

Two safety keys protect the operation:

Idempotency-Key replays the same HTTP result during the request-cache window; and
external_transaction_id permanently prevents the same POS sale from earning twice.

Use both and choose a namespace owned by your integration, such as odoo:<company>:order:<id>. Provider-managed prefixes such as sq_payment_ are reserved and return 400 reserved_external_transaction_id. A timeout does not prove the write failed.

Step 5: update the till

Use the returned customer, enrolment, balance, and transaction to show a short, stable result without making another request.

201 Created

Loyalty was applied for the first time. Store the returned transaction ID beside the POS order/payment reference.

200 Existing transaction

The permanent external reference already existed. Treat this as a safe replay, not a second award.

404 Not found in test mode

Test credentials cannot create a live customer or enrolment. Select an existing testable customer and card, then retry.

409 or 422 conflict

The supplied identity or external transaction conflicts with an existing record or environment. Stop and surface a staff-review state; do not invent another identifier.

429 or 5xx

Honour Retry-After for 429. Retry transient failures with backoff and the same idempotency and external transaction IDs.

Step 6: reverse a refund or void

curl --request POST "$PERKSTAR_API_URL/marketplace/reverse" \
  --header "Authorization: Bearer $PERKSTAR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: odoo:company_4:refund_301" \
  --data '{
    "external_transaction_id": "odoo:company_4:order_94721",
    "reason": "POS order refunded"
  }'

Reversal writes a compensating transaction linked to the original. Replaying a refund returns the existing reversal. Do not create an unrelated negative award: it loses the original-sale link and weakens reconciliation.

Step 7: work through outages

An offline queue should retain the original merchant, card, location, customer identifier, transaction reference, idempotency key, amount, and occurrence time. Encrypt local data, bound retention, and make failed entries visible to staff.

Step 8: reconcile

Webhooks provide fast updates; scheduled reads prove eventual consistency.

Subscribe to transaction.created, customer.enrolled, reward.redeemed, and tier.changed as relevant.
Verify and persist each event before acknowledging it.
At least daily, compare recent POS references with Perkstar transactions.
Repair missing writes using the same stable IDs.
Alert on a queue that is old, repeatedly failing, or growing unexpectedly.

See the webhook catalogue for exact payloads.

Get started

Core concepts

Integration recipes

Platform

Developer tools

Ship safely

1. Connect

2. Transact

3. Recover

Choose the installation model

The till journey

Step 1: confirm the installation

Step 2: map stores and programmes

Step 3: identify the customer

Step 4: add loyalty

Step 5: update the till

Step 6: reverse a refund or void

Step 7: work through outages

Step 8: reconcile

Go-live proof

1. Connect

2. Transact

3. Recover

​Choose the installation model

​The till journey

​Step 1: confirm the installation

​Step 2: map stores and programmes

​Step 3: identify the customer

​Step 4: add loyalty

​Step 5: update the till

​Step 6: reverse a refund or void

​Step 7: work through outages

​Step 8: reconcile

​Go-live proof

Choose the installation model

The till journey

Step 1: confirm the installation

Step 2: map stores and programmes

Step 3: identify the customer

Step 4: add loyalty

Step 5: update the till

Step 6: reverse a refund or void

Step 7: work through outages

Step 8: reconcile

Go-live proof