Build a POS integration

The marketplace endpoints are the shortest path for a POS integration. One request can resolve a customer, choose a card, find or create the enrolment, and post the loyalty transaction.

1. Create a dedicated key

Create one API key per POS connection. Grant:

MARKETPLACE for ping, accrue, enrol, and reverse;
LOCATIONS_READ when transactions must be attributed to a store; and
read scopes only when the adapter genuinely needs separate reconciliation.

Use a test key during development and a new live key for production.

2. Confirm the business and cards

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

When default_card_id is null, the business has more than one active card. Ask the operator to map each POS location or loyalty programme to a specific card_id; never guess the first card.

3. Identify the customer

Send at least one identifier. Perkstar checks them in this order:

card_serial
provider identity for first-party integrations
external_ref
email
phone

For a wallet scan, pass the barcode content unchanged as card_serial. Current opaque POS identifiers and older numeric or serial formats are both resolved by the API. Do not parse, reformat, truncate, or assume a fixed length. For customer records coming from the POS, prefer a namespaced stable ID:

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

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" }
    }
  }'

For points based on spend, send type: "POINTS" with amount_pence. Perkstar uses the card’s points rule. Send an explicit delta only when the upstream system is authoritative for the points amount.

5. Handle refunds

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"
  }'

Do not create a negative award as a substitute for reversal. The reversal links the audit trail to the original transaction and preserves retry safety.

Production rules

A sale callback must acknowledge only after Perkstar has accepted or durably queued the operation.
Retry timeouts and 5xx responses with the same IDs.
Respect Retry-After on 429.
Queue offline work locally and retain the original transaction time and ID.
Show terminal failures to staff; do not drop them silently.
Keep location mapping explicit when the business has several stores.

A test marketplace call cannot create a live customer or enrolment. Prepare an existing test customer/card enrolment before testing accrual.

Get started

Core concepts

Integration recipes

Ship safely

1. Create a dedicated key

2. Confirm the business and cards

3. Identify the customer

4. Add loyalty

5. Handle refunds

Production rules

​1. Create a dedicated key

​2. Confirm the business and cards

​3. Identify the customer

​4. Add loyalty

​5. Handle refunds

​Production rules

1. Create a dedicated key

2. Confirm the business and cards

3. Identify the customer

4. Add loyalty

5. Handle refunds

Production rules