POS Integration

Connect your point-of-sale system to Xtarly Rewards to automatically award points or stamps when customers make a purchase.

The POS integration lets your point-of-sale system register transactions directly via a REST API. Every time a customer pays, your POS calls the Xtarly endpoint and the customer instantly receives their points or stamps — no manual scanning required.

Getting your API key

Open your organization dashboard and go to Settings → General.
Scroll down to the POS Integration section.
Click Generate API key. The key is shown once — copy it immediately and store it securely (e.g. in your POS system's environment configuration).
If the key is ever compromised, click Rotate to invalidate the old key and generate a new one.

The API key is shown only once after generation. If you lose it, you will need to rotate and update all integrations using the old key.

Base URL

All POS endpoints are served from your Xtarly domain:

https://www.xtarly.com/api/integrations/pos

Authentication

Include your API key in every request via the X-API-Key header:

X-API-Key: xtarly_pos_<your_key>

Requests without a valid key return 401 Unauthorized.

Endpoints

Register a transaction

POST /api/integrations/pos/transaction

Call this endpoint when a customer completes a purchase. Xtarly calculates the points or stamps earned based on your active reward program and credits them to the customer.

Request body

Field	Type	Required	Description
`amount`	number	✓	Purchase total in the smallest currency unit (e.g. cents for MXN/USD).
`customerId`	string	✓ (or `customerEmail`)	Xtarly customer ID.
`customerEmail`	string	✓ (or `customerId`)	Customer's registered email.
`metadata`	object	—	Optional free-form object attached to the transaction (e.g. `{ "ticket": "1234" }`).

Provide either customerId or customerEmail — at least one is required.

Example request

curl -X POST https://www.xtarly.com/api/integrations/pos/transaction \
  -H "Content-Type: application/json" \
  -H "X-API-Key: xtarly_pos_<your_key>" \
  -d '{
    "amount": 35000,
    "customerEmail": "cliente@ejemplo.com",
    "metadata": { "ticket": "T-00412" }
  }'

Successful response 200 OK

{
  "success": true,
  "data": {
    "transactionId": "txn_abc123",
    "earnedPoints": 35,
    "earnedStamps": 0,
    "customerPoints": 210,
    "customerStamps": 0
  }
}

Field	Description
`transactionId`	Unique ID of the recorded transaction.
`earnedPoints`	Points credited in this transaction.
`earnedStamps`	Stamps credited in this transaction (stamp programs).
`customerPoints`	Customer's total points after this transaction.
`customerStamps`	Customer's total stamps after this transaction.

Look up a customer

GET /api/integrations/pos/customer/:id

Returns the current balance and tier of a customer. Useful to display loyalty status at the point of sale before or after a transaction.

Example request

curl https://www.xtarly.com/api/integrations/pos/customer/cus_abc123 \
  -H "X-API-Key: xtarly_pos_<your_key>"

Successful response 200 OK

{
  "success": true,
  "data": {
    "id": "cus_abc123",
    "name": "María García",
    "email": "cliente@ejemplo.com",
    "points": 210,
    "stamps": 0,
    "tier": null
  }
}

Points calculation

The points or stamps credited per transaction depend on your active program type:

Program type	Calculation
Points	`floor(amount / currencyUnit × pointsPerCurrency)`
Tiers	Same as Points, then multiplied by the customer's tier multiplier.
Stamps	1 stamp per transaction, regardless of amount.

You configure currencyUnit and pointsPerCurrency in Settings → Program.

Error codes

Code	HTTP	Description
`UNAUTHORIZED`	401	Missing or invalid API key.
`VALIDATION_ERROR`	400	`amount` or customer identifier not provided.
`NOT_FOUND`	404	No customer found with the given ID or email in your organization.
`BAD_REQUEST`	400	Your organization has no active reward program.

POS Integration

On this page