Process a Unified Points Transaction

Process a points transaction for a customer. This single endpoint handles three scenarios:

How it works:
Use the reward and redeem boolean flags to tell Rewrd what type of transaction to perform. You can set one or both to true.

`reward`	`redeem`	What happens
`true`	`false`	Reward only — Customer earns points based on an earning rule.
`false`	`true`	Redeem only — Customer spends points toward a purchase.
`true`	`true`	Combined — Customer earns AND redeems points in a single checkout.

When reward is true:
You must provide way_to_earn_id (the ID of the earning rule from your dashboard). Rewrd will calculate the points to credit based on the rule's type:

Fixed rule — Awards a fixed number of points regardless of order_value (e.g. always award 50 points).

Percentage rule — Awards points as a percentage of order_value (e.g. 10% of ₦5,000 = 500 points).

When redeem is true:
You must provide deduct_points — the exact number of points to deduct from the customer's balance. The customer must have enough points, otherwise the request will fail with an insufficient_points error.

Real-world example — Combined checkout:
A customer buys a coffee for ₦5,000. They want to use 200 of their points AND earn new points for the purchase:

{
  "customer_uid": `26833813`,
  "order_id": "ORD-003",
  "order_value": 5000,
  "redeem": true,
  "deduct_points": 200,
  "reward": true,
  "way_to_earn_id": 1
}

This will deduct 200 points AND credit new points based on earning rule #1, all in a single atomic operation.

This endpoint requires an Idempotency-Key header to prevent duplicate transactions. Use a unique key per checkout (e.g. your order ID).

curl --location --request POST 'https://rewrd-api-staging.fly.dev/v1/points/transaction' \ --header 'Idempotency-Key: tx-cust123-20260225-001' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "customer_uid": "26833813", "order_id": "ORD-003", "order_value": 10000, "redeem": true, "reward": true, "deduct_points": 200, "way_to_earn_id": 1 }'

{ "status": true, "message": "Transaction processed successfully", "data": [ { "id": 1284, "customer_uid": "26833813", "points": 50, "title": "Points Credit", "narration": "Credited 50 points for purchase #12345", "transaction_type": "member_points_adjustment_credit", "ledger_type": "credit", "status": "successful", "reference_id": "credit_a1b2c3d4-e5f6-7890", "balance_before": 1500, "balance_after": 1550, "created_at": "2026-02-20T14:30:00.000Z" } ] }

Process a Unified Points Transaction

Request

Responses