Understanding your program setup
Ask about your program’s configuration — sites, locales, points-expiry policy, earning rules, redeemable rewards, tier structure, and referral incentive.- “How is my loyalty program set up?”
- “What rules do customers earn points from, and how many points does each give?”
- “List all the rewards customers can redeem and how many points they cost.”
- “What tiers do I have, and what are the thresholds for each?”
- “Do my points expire? What’s the expiry policy?”
- “What referral incentive is configured for my program?”
- “Which sites and locales are part of my program?”
Analytics and performance
Get a time series for a single metric over a date range, bucketed by day, week, or month. Many metrics can be filtered to a single site, earning rule, or reward. The available metrics are:| Metric | What it measures | Filter by |
|---|---|---|
| New members | Customers who enrolled during the period | — |
| Activities completed | Point-earning customer activities recorded | site, rule |
| Points earned | Points earned (approved + pending) | site, rule |
| Points earned (approved) | Points earned from approved activities | site, rule |
| Points earned (pending) | Points earned from activities not yet approved | site, rule |
| Points spent | Points spent on approved reward claims | site |
| Points expired | Points that expired | site, rule |
| Points deducted | Points removed via negative approved activities | site, rule |
| Orders | Orders placed during the period | site |
| Revenue | Total order revenue, in your currency | site |
| Average order value | Revenue divided by orders, in your currency (buckets with no orders are omitted) | site |
| Loyalty-attributed revenue | Revenue attributable to the loyalty program (reward/referral orders and repeat redeemers) | site |
| Rewards claimed | Reward claims created (distinct from the points they cost) | site, reward |
| Rewards used | Claimed rewards that were redeemed | site, reward |
| Customer lifetime value | Blended customer lifetime value, averaged across customers (monthly only) | site |
Revenue, average order value, loyalty-attributed revenue, and customer
lifetime value are returned in your store’s currency. If your program has
active sites in more than one currency, scope these metrics to a single site
with a site filter — otherwise the request is refused rather than mixing
currencies. Customer lifetime value is only available at month granularity.
- “How many new members did I gain each month this year?”
- “Show me points earned per week for the last quarter.”
- “Compare points earned vs points spent over the last 90 days.”
- “How many points expired last month?”
- “What were my daily activity completions in December?”
- “Which earning rule drove the most points last month?”
- “Break down points earned by site for the last month.”
- “What was my revenue and average order value each month this year?”
- “How much revenue was attributed to the loyalty program last quarter?”
- “How many orders did I get per week over the last 90 days?”
- “How many rewards were claimed vs used last month?”
- “Which reward was claimed the most over the last 90 days?”
- “Show me customer lifetime value month by month this year.”
Customers
Look up your loyalty customers by email, ID (merchant_id, their ID in your
ecommerce platform), or created/updated time range. Each customer includes their
points balances, enrollment state, current tier, tags, and timestamps. Requires
the read_customers scope on the credential you connected with.
- “Look up the customer with email customer@example.com.”
- “What’s the points balance and tier for the customer with ID 1234567890?”
- “Which customers enrolled in the last 7 days?”
- “Show me customers updated since the start of the month.”
Orders
List your orders by time range, order number, ID (merchant_id, the order’s ID
in your ecommerce platform), or customer. Each order includes its amounts,
statuses, timestamps, points earned, and rewards used. Requires the read_orders
scope on the credential you connected with.
- “Show me the orders placed by customer@example.com.”
- “What points did order #1001 earn?”
- “List orders from the last 7 days and the rewards used against them.”
- “Find the order with ID 1234567890 and tell me its status.”