Points Deduction.

Deduct points from a member's loyalty card via the Partner API.

Jun 9, 2026

Partners can deduct a custom number of points from a member's loyalty card. Use this endpoint to redeem points for off-platform rewards like gift cards or external services, without needing a staff member at the register.

How It Works

The platform stores point balances as a running sum of transactions. No single "balance" field exists. A deduction inserts a new transaction with a negative point value, which reduces the member's effective balance.

The deduction consumes points in first-in, first-out (FIFO) order, starting with the oldest unexpired credits.

Endpoint

POST /api/{locale}/v1/partner/cards/{cardUID}/{memberUID}/transactions/deductions

Authentication

Requires a Partner API token (Bearer token). The authenticated partner must own the card.

Authorization

Check	Description
Partner token	Required. Authenticates the partner making the request
Card ownership	The card must belong to the authenticated partner
Staff (optional)	If `staffId` is provided, the staff member must have access to the same card

ℹ️ Note: The staffId field is optional. It records which staff member initiated the deduction. If you omit it, the platform records the transaction as "Partner".

Request Body

Field	Type	Required	Description
`points`	integer	Yes	Number of points to deduct. Must be a positive integer (≥ 1).
`note`	string	Yes	Reason for the deduction. Every deduction needs an audit note. Max 1024 characters.
`reference`	string	No	External reference for linking to an external system (e.g., `giftcard:order:12345`). Max 255 characters.
`staffId`	UUID	No	Staff member ID for audit attribution. The staff member must have access to the card.

Example Request

curl -X POST "https://your-domain.com/api/en-us/v1/partner/cards/123-456-789-012/987-654-321-098/transactions/deductions" \
  -H "Authorization: Bearer your-partner-token" \
  -H "Content-Type: application/json" \
  -d '{
    "points": 500,
    "note": "Gift card redemption - $50 Amazon card",
    "reference": "giftcard:order:12345"
  }'

Example Response

{
  "message": "Points deducted successfully",
  "points_deducted": 500,
  "new_balance": 1200,
  "transaction": {
    "id": "019b8d49-abcd-7abc-8def-17f2107a8ec0",
    "event": "partner_deducted_points",
    "points": -500,
    "note": "Gift card redemption - $50 Amazon card",
    "external_reference": "giftcard:order:12345",
    "created_at": "2026-06-09T12:00:00.000000Z"
  }
}

Error Responses

Insufficient Points (422)

The member does not have enough points:

{
  "message": "Insufficient points. Required: 500, available: 200"
}

Validation Error (422)

A required field is missing or invalid:

{
  "message": "The given data was invalid.",
  "errors": {
    "note": ["The note field is required."]
  }
}

Card Not Found (404)

The card does not exist, or the authenticated partner does not own it:

{
  "error": "Card not found"
}

Behavior

No negative balances. A deduction fails if the member's current balance is lower than the requested amount.
Note is required. Every deduction must include a reason for audit purposes.
Tiers stay unchanged. The tier system counts lifetime positive transactions, so deductions do not affect a member's tier.
No notifications. Deductions do not trigger email or push notifications to the member.