Points Calculator

The Points Calculator is a read-only preview endpoint that estimates how many loyalty points a member would earn for a given purchase — before any transaction is created. No points are awarded and no wallets are modified.

Use it to show real-time point previews anywhere in your customer-facing UI: product detail pages, cart summaries, or checkout screens.

Modes

The endpoint operates in one of two modes, selected automatically based on the request body.

Single-item mode

Send amount and optionally sku. Use this on product detail pages where you want to show how many points a customer would earn for buying a specific product.

{
  "member_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 4999,
  "sku": "ABC-123"
}

Checkout mode

Send a non-empty items array. Use this on the cart or checkout page to show the total points a customer would earn for their full basket. When items is present, the root-level sku field is ignored.

{
  "member_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 15000,
  "shipping_fee": 500,
  "payment_fee": 0,
  "discounts": [1000],
  "items": [
    {
      "sku": "ABC-123",
      "amount": 4999,
      "qty": 2,
      "final_amount": 8999,
      "discount_allocations": [{ "amount": 1000 }]
    },
    {
      "sku": "XYZ-456",
      "amount": 3000,
      "qty": 1
    }
  ]
}

If neither amount nor items is provided, the endpoint returns a 400 error.

Member vs. guest previews

member_id is optional. When provided, the calculation applies the member's current tier multiplier on top of the base rate. When omitted, the base rate is used — useful for showing a generic points preview to non-logged-in visitors.

What the calculation respects

• Wallet configuration — exchange rate, rounding rules, and whether the base amount is gross or net of fees
• Tier multipliers — applied when member_id is provided and the member has an active tier
• Fees — shipping_fee and payment_fee are subtracted from the base when the wallet is configured for net-of-fees calculation
• Discounts — order-level discounts are distributed proportionally across line items unless item-level discount_allocations are provided
• Ignored SKUs — SKUs excluded from point earning in your loyalty configuration are respected
• Product promotions — active points multiplier promotions are evaluated per SKU and reflected in the bonus array of the response

Response

A successful response returns the total expected points broken down into base points and any active promotion bonuses.

{
  "status": 200,
  "success": true,
  "data": {
    "points": 150,
    "base_points": 100,
    "bonus": [
      {
        "display_name": "Double points weekend",
        "name": "Double points weekend",
        "note": "Double points weekend",
        "multiplier": 1,
        "points": 50,
        "link_url": null,
        "image": null
      }
    ]
  }
}

Each bonus entry:

When wallets are disabled for the vendor or member, the endpoint still returns 200 with all values set to zero:

{
  "status": 200,
  "success": true,
  "data": {
    "points": 0,
    "base_points": 0,
    "bonus": []
  }
}

Amounts and currency

All monetary values use cents to avoid floating-point precision issues. For example, $49.99 is sent as 4999.

In checkout mode, if amount is omitted, it is computed as:

amount = sum(item.final_amount or item.amount × item.qty) + shipping_fee + payment_fee

Errors