Transaction API
Transactions are the core mechanism for awarding loyalty points to members. Every purchase, redemption, or manual point adjustment flows through the Transaction API — making it the most frequently called part of the Trifft platform.
How it works
When a sale occurs at a POS, e-commerce checkout, or any other touchpoint, your system sends a Create Transaction request to Trifft. Trifft evaluates the transaction against your active loyalty rules (point multipliers, bonus campaigns, tier thresholds, etc.) and awards points to the member's wallet automatically.
The general flow is:
- Member is identified at checkout (by card, phone, email, or custom parameter)
- Your system sends
POST /v1/transactionwith the sale details - Trifft calculates and awards points based on the configured rules
- The member's wallet is updated in real time
Member identification
Every transaction must identify the member. Trifft supports five identification strategies via the member_id_type field:
member_id_type | member_id value |
|---|---|
TrifftID | Member's internal Trifft UUID |
CardID | Physical or virtual card number |
PhoneNumber | Member's phone number |
Email | Member's email address |
CustomParam | Any custom parameter in param_slug:value format |
Venue identification
Transactions must also be linked to a venue (physical location or e-commerce). Use the venue_id_type field:
venue_id_type | venue_id value |
|---|---|
VenueID | Trifft's internal venue UUID |
CustomParam | Custom parameter in param_slug:value format |
Ecommerce | Set venue_id to null for online transactions |
Transaction types
The type field controls how the transaction is processed:
| Type | Behavior |
|---|---|
standard | Normal purchase — points are calculated by Trifft's loyalty rules |
wallet | Direct wallet operation — used for manual point adjustments not tied to a purchase |
silent | Transaction is recorded but no notification is sent to the member |
Amounts and currency
All monetary values use cents to avoid floating-point issues. For example, $12.23 is sent as 1223.
The same applies to redeemed_points — points are expressed in the same unit as the transaction amount.
If you need to override Trifft's automatic point calculation for a specific transaction, pass the points field explicitly. When provided, Trifft skips its internal calculation and awards exactly that many points.
Line items
Passing items is optional but recommended for integrations that want per-product point rules, reporting, or the Points Calculator (see below). Each item includes:
| Field | Required | Description |
|---|---|---|
name | Yes | Product name |
type | Yes | Your product type classification (any string) |
qty | Yes | Quantity (float, e.g. 2.5 for weighted goods) |
price | Yes | Unit price in cents |
sku | No | Universal product identifier |
Points Calculator
The Points Calculator endpoint lets you preview how many points a member would earn for a given product or full checkout basket — before the actual transaction is submitted.
Use it to display a real-time points preview at the POS or on the product/cart page in your e-commerce frontend.
Typical use cases:
- "You'll earn 120 points for this purchase" displayed at checkout
- Per-product points badge on product detail pages
- Cart summary showing total points for the full basket
The calculator respects all active loyalty rules, multipliers, and the member's current tier — the result reflects exactly what POST /v1/transaction would award.
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /v1/transaction | Record a new transaction and award points |
POST | /v1/transaction/{custom_transaction_id} | Update custom parameters on an existing transaction |
POST | /v1/transaction/{custom_transaction_id}/refund | Refund a transaction and reverse the awarded points |
DELETE | /v1/transaction/{custom_transaction_id} | Delete a transaction and reverse the awarded points |
POST | /v1/points-calculator | Preview the points a member would earn for a product or basket |
Idempotency
All transaction requests are idempotent by the id field (your custom transaction ID). Submitting the same id twice will not create duplicate transactions or award points twice. Use your POS order number or receipt ID as the id to safely retry on network failures.
Refunds vs. Deletions
Both /refund and DELETE reverse the points awarded by a transaction, but they serve different purposes:
- Refund — use when a customer returns a product or requests a chargeback. The transaction remains in the history and is marked as refunded and coupons and/or points are reverted.
- Delete — use to correct data errors (e.g. a transaction sent to the wrong member). The transaction is removed from history entirely.