User status

Why use this endpoint

Your backend may need an authoritative, up-to-date view of a user’s Relay balances. For example, you might decide whether they can redeem an offer, display savings alongside your own UI, or reconcile state after a purchase flow. The widget keeps users informed inside Relay, but this API lets your servers query Fruga directly so those decisions stay in sync.

The response highlights available: funds that are available for redemption now. Use it whenever you need a real-time signal for redemption eligibility or messaging on your platform.

Query parameters

Example

GET {FRUGA_API_URL}/partner/user/status?userRef=user_123

Request headers

Signing the request

Signing follows the same rules as Cashback Claim: HMAC-SHA256 with your PARTNER_SECRET, a dotted canonical string, and a lowercase hex SHA-256 digest of the exact request body bytes.

For this endpoint:

• HTTP method is GET.
• Path in the signing string is /partner/user/status (production and sandbox follow the same path convention as /cashback/claim - the path only, with no host and no /api prefix).
• There is no request body: hash the empty string ("") so the body digest is the SHA-256 hex of empty input (e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855).

Construct:

{timestamp}.GET./partner/user/status.{bodyHash}

Then HMAC-SHA256 that string with your PARTNER_SECRET and Base64-encode the result for X-Partner-Signature.

Signing example (Node.js)

import crypto from 'crypto';

const buildSignedGetHeaders = (pathForSigning) => {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const secret = process.env.PARTNER_SECRET;
  const body = ''; // GET - empty body
  const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
  const signingString = `${timestamp}.GET.${pathForSigning}.${bodyHash}`;

  const signature = crypto
    .createHmac('sha256', secret)
    .update(signingString)
    .digest('base64');

  return {
    'X-Partner-Key': process.env.NEXT_PUBLIC_PARTNER_ID,
    'X-Partner-Timestamp': timestamp,
    'X-Partner-Signature': signature,
  };
};

const userRef = encodeURIComponent('user_123');
const url = `${process.env.FRUGA_API_URL}/partner/user/status?userRef=${userRef}`;

const response = await fetch(url, {
  method: 'GET',
  headers: buildSignedGetHeaders('/partner/user/status'),
});

Signing example (Python)

import hashlib, hmac, base64, time, os
from urllib.parse import quote
import requests

def build_signed_get_headers(path_for_signing: str) -> dict:
    timestamp = str(int(time.time()))
    secret = os.environ["PARTNER_SECRET"].encode()
    body = b""
    body_hash = hashlib.sha256(body).hexdigest()
    signing_string = f"{timestamp}.GET.{path_for_signing}.{body_hash}"
    signature = base64.b64encode(
        hmac.new(secret, signing_string.encode(), hashlib.sha256).digest()
    ).decode()
    return {
        "X-Partner-Key": os.environ["NEXT_PUBLIC_PARTNER_ID"],
        "X-Partner-Timestamp": timestamp,
        "X-Partner-Signature": signature,
    }

user_ref = quote("user_123", safe="")
url = f"{os.environ['FRUGA_API_URL']}/partner/user/status?userRef={user_ref}"

response = requests.get(
    url,
    headers=build_signed_get_headers("/partner/user/status"),
)

Responses

Success (200 OK)

JSON body describing the user’s balances and related metadata. Monetary amounts are in GBP (consistent with Cashback Claim).

{
  "userRef": "user_123",
  "available": 46.2,
  "pending": 0.1,
  "lifetimeEarned": 120.5,
  "lifetimeRedeemed": 74.3,
  "lastRedemption": {
    "transactionId": 987654321,
    "amount": 12.0,
    "status": "PAID",
    "redemptionContext": "NEW_POLICY",
    "createdAt": "2026-04-20T14:32:01Z"
  },
  "updatedAt": "2026-04-28T09:15:00Z"
}

Fields

lastRedemption object (when present)

Errors

Error bodies follow the common JSON error shape used elsewhere on the API (error, message, path, timestamp - exact fields may vary).

Operational notes