Developer Documentation | Premium Brands Loyalty

Start here

Checkout flow

1. Identify the customer

Scan the card or enter the member code to retrieve the ID, name, and balance.

2. Post the purchase

Send the sale value and external reference; the server applies points or stamp rules.

3. Read benefits

Show available benefits and redeem each gift safely and only once.

4. Receive updates

Receive signed customer and transaction events through webhooks.

Quick start

Create a Test key in Integrations, then verify customer lookup before posting your first transaction.

curl "https://loyalty.premiumsbrands.com/api/v1/pos/customers/lookup?code=TC-0000123" \
  -H "Authorization: Bearer pb_test_your_key"

Authentication

Every key is scoped to one store, environment, and set of permissions. Send it only in the Authorization header.

Authorization: Bearer pb_test_...
Content-Type: application/json

API reference

GET

Customer lookup

Accepts a member code, UUID, or full card URL. Phone and email are deliberately excluded.

GET https://loyalty.premiumsbrands.com/api/v1/pos/customers/lookup?code=TC-0000123

POST

Transactions

Send the sale amount and let the server calculate points or stamps. The external reference must be unique and stable.

POST https://loyalty.premiumsbrands.com/api/v1/pos/transactions

{
  "provider": "pos-company",
  "external_reference": "BRANCH-POS03-874521",
  "customer_id": "customer-uuid",
  "branch_id": "branch-uuid",
  "amount": 20.00,
  "currency": "JOD"
}

GET / POST

Rewards & gifts

Read available gifts, then redeem one with its own external reference.

GET  https://loyalty.premiumsbrands.com/api/v1/pos/customers/{customer_id}/benefits
POST https://loyalty.premiumsbrands.com/api/v1/pos/gifts/{gift_id}/redeem

Webhooks

Add your receiver URL in Integrations. Deliveries are signed and the endpoint can be tested before launch.

customer.createdpoints.updatedtransaction.created

Errors

400Invalid request

401Missing or invalid key

403Permission or module unavailable

404Customer or branch not found

409Operation conflict

429 / 5xxRetry with backoff

Best practices

Use a Test key before moving to production.

Create one stable external_reference per operation and reuse it for retries.

Never put API keys in URLs, browser apps, source control, or logs.

Do not block a sale when loyalty is unavailable; queue the request and retry later.

Do not automatically retry 400, 401, 403, 404, or 409 responses.

Retry 429 and 5xx responses gradually with backoff.

Ready to connect your POS?

We can help your team or POS vendor test the integration, issue production keys, and review failure scenarios.

Start an integration

Connect your system to Premium Brands Loyalty