Analytics

Analytics is server-side. These reads use the secret Org-API-Key on your backend only - never ship it in an app or client code. A request with a member token is rejected with 403. See Authentication and Server-side API.

Three read-only endpoints roll up your program’s activity: a program-wide summary, per-offers performance, and a timeseries bucketed over a window. All require the Org-API-Key.

Endpoint	SDK method	Returns
`GET /v1/analytics/summary`	`analyticsSummary()`	Program-wide totals and redemption status breakdown.
`GET /v1/analytics/offers`	`analyticsOffers()`	One row per offer.
`GET /v1/analytics/timeseries`	`analyticsTimeseries({ from, to, interval })`	Buckets over a window.

Summary

analyticsSummary() calls GET /v1/analytics/summary and returns program-wide totals plus a redemption status-count breakdown.

curl

curl https://api.expys.com/v1/analytics/summary \
  -H "Authorization: Bearer YOUR_ORG_API_KEY"

number

required

Total members in the program.

number

required

Total points ever minted across the program.

number

required

Total points ever spent across the program.

number

required

Share of redemptions that reached completion.

RedemptionStatusCounts

required

A breakdown of redemptions by status (see below).

Redemption status counts

redemptions counts every redemption by its lifecycle status, plus a total:

Key	Meaning
`submitted`	Redemptions submitted.
`open`	Redemptions in the open state.
`awaiting_vendor`	Waiting on the vendor.
`awaiting_customer`	Waiting on the customer.
`purchased`	Purchased (sometimes called confirmed).
`completed`	Completed experiences.
`canceled`	Canceled redemptions.
`total`	Sum across all statuses.

All values are numbers.

Offers

analyticsOffers() calls GET /v1/analytics/offers and returns one OfferAnalytics row per offer.

curl

curl https://api.expys.com/v1/analytics/offers \
  -H "Authorization: Bearer YOUR_ORG_API_KEY"

OfferAnalytics[]

required

Per-offer performance rows.

Each OfferAnalytics row:

Field	Type	Description
`offerId`	string	The offer this row describes.
`signups`	number	Members who signed up for the offer.
`completions`	number	Redemptions of the offer that completed.
`cancellations`	number	Redemptions of the offer that were canceled.
`pointsSpent`	number	Points spent on this offer.

Timeseries

analyticsTimeseries({ from, to, interval }) calls GET /v1/analytics/timeseries and returns buckets over a window. All three query parameters are required.

string

required

Start timestamp of the window (inclusive). The first bucket begins here.

string

required

End timestamp of the window. The last bucket ends here.

string

required

The bucket granularity - how the window between from and to is divided into buckets (for example by day or by hour).

curl

curl "https://api.expys.com/v1/analytics/timeseries?from=2026-06-01T00:00:00Z&to=2026-06-23T00:00:00Z&interval=day" \
  -H "Authorization: Bearer YOUR_ORG_API_KEY"

TimeseriesBucket[]

required

One entry per interval bucket across the window.

Each TimeseriesBucket:

Field	Type	Description
`startTime`	number	Start of the bucket.
`endTime`	number	End of the bucket.
`signups`	number	Signups in the bucket.
`pointsMinted`	number	Points minted in the bucket.
`pointsSpent`	number	Points spent in the bucket.

from and to are timestamps bounding the window; interval is the bucket granularity that divides it. Omitting any of the three is an error - all are required.

In code

The server client is constructed with the Org-API-Key. analyticsSummary, analyticsOffers, and analyticsTimeseries are all called on it.

import { initialize } from "@expys/sdk";

const orgApiKey = process.env.EXPYS_ORG_API_KEY;
if (!orgApiKey) {
  throw new Error(
    "Set EXPYS_ORG_API_KEY (your secret Org-API-Key, e.g. expys_live_...). " +
      "Run this on a backend only, never in a client app.",
  );
}

// Construct the client with the machine credential as the token. Server-mode
// methods are guarded against member tokens client-side.
const expys = initialize({
  baseUrl: process.env.EXPYS_BASE_URL,
  environment: "sandbox",
  token: orgApiKey,
});

const externalUserID = process.env.EXPYS_EXTERNAL_USER_ID ?? "user_42";

async function main(): Promise<void> {
  // Mint a short-lived member token for your app to use (return this to the app,
  // never the Org-API-Key). Idempotent POST: a retry replays rather than re-mints.
  const grant = await expys.exchangeToken({ externalUserID });
  console.log(`minted member token expiring at ${grant.expiresAt}`);

  // Upsert the member's profile. PUT is idempotent by HTTP semantics (no key).
  const member = await expys.setMember(externalUserID, {
    displayName: "Ada Lovelace",
    tier: "gold",
  });
  console.log(`member ${member.externalUserID} is now tier=${member.tier}`);

  // Credit points to the member's wallet. Idempotent POST sends an Idempotency-Key.
  const credited = await expys.creditPoints({
    amount: 100,
    externalUserID,
    reason: "welcome bonus",
  });
  console.log(`new balance: ${credited.balance} ${credited.currency.symbol}`);

  // Register a webhook. The signingSecret is shown ONLY on creation - store it now.
  const webhook = await expys.createWebhook({
    events: ["redemption.created"],
    url: "https://example.com/expys/webhooks",
  });
  console.log(`webhook ${webhook.id} secret: ${webhook.signingSecret}`);

  // Org-wide analytics rollups.
  const summary = await expys.analyticsSummary();
  console.log(
    `members: ${summary.memberCount}, minted: ${summary.pointsMinted}`,
  );
}

import ExpysSDK
import Foundation

@main
struct ServerModeExample {
  static func main() async throws {
    let environment = ProcessInfo.processInfo.environment
    guard let orgApiKey = environment["EXPYS_ORG_API_KEY"] else {
      fatalError(
        "Set EXPYS_ORG_API_KEY (your secret Org-API-Key, e.g. expys_live_...). "
          + "Run this on a backend only, never in a client app.")
    }
    let baseURL =
      environment["EXPYS_BASE_URL"].flatMap(URL.init(string:))
      ?? ExpysConfiguration.defaultBaseURL
    let externalUserID = environment["EXPYS_EXTERNAL_USER_ID"] ?? "user_42"

    // Configure the client with the machine credential as the token. Server-mode
    // methods are guarded against member tokens client-side.
    let client = ExpysClient(
      configuration: ExpysConfiguration(token: orgApiKey, environment: .sandbox, baseURL: baseURL)
    )

    // Mint a short-lived member token for your app to use (return this to the app,
    // never the Org-API-Key). Idempotent POST: a retry replays rather than re-mints.
    let grant = try await client.exchangeToken(TokenExchangeRequest(externalUserID: externalUserID))
    print("minted member token expiring at \(grant.expiresAt)")

    // Upsert the member's profile. PUT is idempotent by HTTP semantics (no key).
    let member = try await client.setMember(
      externalUserID: externalUserID,
      SetMemberRequest(displayName: "Ada Lovelace", tier: "gold"))
    print("member \(member.externalUserID) is now tier=\(member.tier)")

    // Credit points to the member's wallet. Idempotent POST sends an Idempotency-Key.
    let credited = try await client.creditPoints(
      CreditWalletRequest(amount: 100, externalUserID: externalUserID, reason: "welcome bonus"))
    print("new balance: \(credited.balance) \(credited.currency.symbol)")

    // Register a webhook. The signingSecret is shown ONLY on creation - store it now.
    let webhook = try await client.createWebhook(
      CreateWebhookRequest(
        events: ["redemption.created"], url: "https://example.com/expys/webhooks"))
    print("webhook \(webhook.id) secret: \(webhook.signingSecret)")

    // Org-wide analytics rollups.
    let summary = try await client.analyticsSummary()
    print("members: \(summary.memberCount), minted: \(summary.pointsMinted)")
  }
}

package com.expys.sdk.examples.servermode

import com.expys.sdk.ExpysClient
import com.expys.sdk.ExpysConfiguration
import com.expys.sdk.ExpysEnvironment
import com.expys.sdk.models.CreateWebhookRequest
import com.expys.sdk.models.CreditWalletRequest
import com.expys.sdk.models.SetMemberRequest
import com.expys.sdk.models.TokenExchangeRequest
import kotlinx.coroutines.runBlocking
import java.net.URI

fun main() = runBlocking {
  val orgApiKey = System.getenv("EXPYS_ORG_API_KEY")
    ?: error(
      "Set EXPYS_ORG_API_KEY (your secret Org-API-Key, e.g. expys_live_...). " +
        "Run this on a backend only, never in a client app.",
    )
  val externalUserID = System.getenv("EXPYS_EXTERNAL_USER_ID") ?: "user_42"

  // Configure the client with the machine credential as the token. Server-mode
  // methods are guarded against member tokens client-side.
  val client = ExpysClient.create(
    ExpysConfiguration(
      token = orgApiKey,
      environment = ExpysEnvironment.SANDBOX,
      baseUrl = System.getenv("EXPYS_BASE_URL") ?: ExpysConfiguration.DEFAULT_BASE_URL,
    ),
  )

  // Mint a short-lived member token for your app to use (return this to the app,
  // never the Org-API-Key). Idempotent POST: a retry replays rather than re-mints.
  val grant = client.exchangeToken(TokenExchangeRequest(externalUserID = externalUserID))
  println("minted member token expiring at ${grant.expiresAt}")

  // Upsert the member's profile. PUT is idempotent by HTTP semantics (no key).
  val member = client.setMember(externalUserID, SetMemberRequest(displayName = "Ada Lovelace", tier = "gold"))
  println("member ${member.externalUserID} is now tier=${member.tier}")

  // Credit points to the member's wallet. Idempotent POST sends an Idempotency-Key.
  val credited = client.creditPoints(
    CreditWalletRequest(amount = 100, externalUserID = externalUserID, reason = "welcome bonus"),
  )
  println("new balance: ${credited.balance} ${credited.currency.symbol}")

  // Register a webhook. The signingSecret is shown ONLY on creation - store it now.
  val webhook = client.createWebhook(
    CreateWebhookRequest(events = listOf("redemption.created"), url = URI("https://example.com/expys/webhooks")),
  )
  println("webhook ${webhook.id} secret: ${webhook.signingSecret}")

  // Org-wide analytics rollups.
  val summary = client.analyticsSummary()
  println("members: ${summary.memberCount}, minted: ${summary.pointsMinted}")
}

Next steps

Members and tiers

The per-member counterpart: profiles, wallet, and redemption counts.

Points and wallet

How pointsMinted and pointsSpent are generated.

Getting started

Member API (member token)

Server-side (Org-API-Key)

Reliability and reference

Summary

Redemption status counts

Offers

Timeseries

In code

Next steps

Members and tiers

Points and wallet

​Summary

​Redemption status counts

​Offers

​Timeseries

​In code

​Next steps

Members and tiers

Points and wallet

Summary

Redemption status counts

Offers

Timeseries

In code

Next steps