Skip to content

Partner API — EP award history

GET /v1/ep/webhook/awards

List all of your own awards in a tenant (across every user), newest first, paginated. Use it to reconcile everything you’ve credited in that tenant.

ParamInRequiredNotes
tenantIdqueryyesMust be one of your allowedTenants.
fromquerynoISO-8601 datetime. Awards with awardedAt >= from.
toquerynoISO-8601 datetime. Awards with awardedAt <= to (inclusive).
limitquerynoPage size. Default 20, max 100.
cursorquerynoOpaque nextCursor from a previous page.

Sign over the tenantId only (i.e. {X-Timestamp}.{tenantId}, no body) — so from, to, limit, and cursor are not part of the signature and can change without re-signing. A suspended partner may still read history.

{
"tenantId": "7g1RP3",
"items": [
{
"epTransactionId": "ep_tx_01HX...",
"orderId": "order-2026-0001",
"userEmail": "user@example.com",
"points": 50,
"note": "Order #2026-0001 cashback",
"awardedAt": "2026-06-17T08:21:09.000Z"
}
],
"nextCursor": null
}
FieldTypeNotes
items[].epTransactionIdstringLedger transaction id of the award.
items[].orderIdstring | nullThe orderId you sent on that award.
items[].userEmailstringThe recipient the EP was credited to.
items[].pointsintegerEP credited in that award — a positive integer (floor(amount / 1000)).
items[].notestring | nullThe note you sent, if any.
items[].awardedAtstringISO-8601 award time.
nextCursorstring | nullPass back as cursor for the next page. null = last page.

Errors use the same contract: 401 INVALID_SIGNATURE / TIMESTAMP_OUT_OF_RANGE, 403 TENANT_NOT_ALLOWED, 400 INVALID_QUERY (malformed from/to, or from > to).

async function listAwards(tenantId, { from, to, limit = 20, cursor } = {}) {
const timestamp = Date.now().toString();
const signature = crypto
.createHmac("sha256", SECRET)
.update(`${timestamp}.${tenantId}`) // sign the tenantId only, no body
.digest("hex");
const qs = new URLSearchParams({ tenantId, limit: String(limit) });
if (from) qs.set("from", from);
if (to) qs.set("to", to);
if (cursor) qs.set("cursor", cursor);
const res = await fetch(`${BASE_URL}/v1/ep/webhook/awards?${qs}`, {
headers: { "X-Api-Key": API_KEY, "X-Timestamp": timestamp, "X-Signature": signature },
});
return res.json(); // { tenantId, items, nextCursor }
}
// Page through a date window (omit from/to for the full history):
let cursor;
do {
const page = await listAwards("7g1RP3", { from: "2026-06-01T00:00:00Z", to: "2026-06-30T23:59:59Z", cursor });
for (const a of page.items) console.log(a.awardedAt, a.userEmail, a.orderId, a.points);
cursor = page.nextCursor;
} while (cursor);