Analytics

GraphQL query examples for revenue, payment, and customer analytics

Overview

Analytics queries return pre-aggregated statistics for a single store. Every analytics query takes:

• A store identifier — storeId or storeSlug (top-level argument, at least one required).
• A required filter of type AnalyticsFilterInput!.

input AnalyticsFilterInput {
  timeRange: TimeRangeInput!   # { startDate, endDate } as ISO 8601 strings — required
  currency: String             # optional, ISO 4217
  status: String               # optional
}

Many nested fields take their own arguments, most commonly granularity and currency. The time-bucket granularity uses the TimePeriodGranularity enum: DAY, WEEK, MONTH, QUARTER, YEAR, ALL_TIME.

Each analytics query returns a structured object, not scalar totals. Amount fields are returned as display strings. Select the nested fields you need — the examples below show the available shape.

---

Order Statistics

Order counts, dual-source revenue, and buyer metrics.

query($storeId: String!) {
  orderStatistics(
    storeId: $storeId
    filter: { timeRange: { startDate: "2026-01-01T00:00:00Z", endDate: "2026-02-01T00:00:00Z" } }
  ) {
    totalCount
    countsByStatus { status count }
    countsByPeriod(granularity: MONTH) { period count }
    revenueByCurrency { currency pspTotalAmount snapshotTotalAmount mismatchCount paymentCount }
    revenueByPeriod(granularity: MONTH, currency: "usd") { period currency pspTotalAmount snapshotTotalAmount paymentCount }
    buyerMetrics { totalBuyers newBuyers returningBuyers }
    ordersByCountry { country count }
    revenueByCountry(currency: "usd") { country totalAmount paymentCount }
    b2bVsB2cBreakdown(currency: "usd") { isBusiness label totalAmount orderCount }
  }
}

revenueByCurrency / revenueByPeriod are dual-source: pspTotalAmount is the PSP actual amount, snapshotTotalAmount is the snapshot expected amount, and mismatchCount counts payments where the two disagree.

Variables:

{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx" }

---

Payment Statistics

Success rate, failure reasons, refunds, method distribution, and tax summary.

query($storeId: String!) {
  paymentStatistics(
    storeId: $storeId
    filter: { timeRange: { startDate: "2026-01-01T00:00:00Z", endDate: "2026-02-01T00:00:00Z" } }
  ) {
    successRate { totalAttempts succeeded failed pending successRate }
    failedReasons { reason count percentage }
    refunds {
      totalCount
      succeededCount
      pendingCount
      failedCount
      amountByCurrency { currency totalAmount paymentCount }
      refundRate
    }
    methodDistribution(currency: "usd") { methodType count totalAmount percentage }
    cardBrandDistribution(currency: "usd") { brand count totalAmount percentage }
    successRateByMethod { methodType total succeeded failed successRate }
    taxSummary { currency totalTax totalPreTax totalAmount paymentCount }
  }
}

successRate is an object ({ totalAttempts, succeeded, failed, pending, successRate }), not a scalar.

---

Product Statistics

Product counts, top sellers, and revenue contribution.

query($storeId: String!) {
  productStatistics(
    storeId: $storeId
    filter: { timeRange: { startDate: "2026-01-01T00:00:00Z", endDate: "2026-02-01T00:00:00Z" } }
  ) {
    onetimeCountsByStatus { status count }
    subscriptionCountsByStatus { status count }
    onetimeTotalCount
    subscriptionTotalCount
    topByOrderCount(limit: 10) { productId productType productName orderCount totalRevenue currency }
    topByRevenue(limit: 10, currency: "usd") { productId productType productName orderCount totalRevenue currency }
    revenueContribution(currency: "usd") { productId productName revenue contributionPercentage cumulativePercentage }
  }
}

---

Trend Analysis

Period-over-period growth, cumulative revenue, and moving averages.

query($storeId: String!) {
  trendAnalysis(
    storeId: $storeId
    filter: { timeRange: { startDate: "2026-01-01T00:00:00Z", endDate: "2026-02-01T00:00:00Z" } }
  ) {
    orderGrowth(granularity: MONTH) { period currentValue previousValue growthRate }
    revenueGrowth(granularity: MONTH, currency: "usd") { period currentValue previousValue growthRate }
    cumulativeRevenue(granularity: MONTH, currency: "usd") { period periodValue cumulativeValue }
    orderMovingAverage(windowDays: 7) { date dailyValue movingAverage }
  }
}

---

Distribution Analysis

Order amount percentiles, average-order-value trend, and amount buckets.

query($storeId: String!) {
  distributionAnalysis(
    storeId: $storeId
    filter: { timeRange: { startDate: "2026-01-01T00:00:00Z", endDate: "2026-02-01T00:00:00Z" } }
  ) {
    orderAmountPercentiles(currency: "usd") { p10 p25 p50 p75 p90 p95 p99 min max avg stddev count }
    aovTrend(granularity: MONTH, currency: "usd") { period averageOrderValue orderCount totalRevenue }
    orderAmountBuckets(currency: "usd", bucketCount: 10) { rangeMin rangeMax count percentage }
  }
}

---

Customer Analysis

Cohort retention, LTV distribution, purchase frequency, and top customers.

query($storeId: String!) {
  customerAnalysis(
    storeId: $storeId
    filter: { timeRange: { startDate: "2026-01-01T00:00:00Z", endDate: "2026-02-01T00:00:00Z" } }
  ) {
    cohortRetention(granularity: MONTH) {
      cohortPeriod
      cohortSize
      retention { periodOffset activeCustomers retentionRate }
    }
    ltvDistribution(currency: "usd") {
      averageLtv
      medianLtv
      percentiles { p50 p90 p99 min max }
      buckets { rangeMin rangeMax count percentage }
    }
    purchaseFrequency { purchaseCount customerCount percentage }
    topCustomers(limit: 10, currency: "usd") { buyerEmail totalSpent orderCount firstPurchaseDate lastPurchaseDate }
  }
}

---

Tax Analysis

Tax amounts by category, rate group, and country, plus B2B/B2C comparison.

query($storeId: String!) {
  taxAnalysis(
    storeId: $storeId
    filter: { timeRange: { startDate: "2026-01-01T00:00:00Z", endDate: "2026-02-01T00:00:00Z" } }
  ) {
    byCategory(currency: "usd") { taxCategory totalTax totalAmount paymentCount }
    byRateGroup(currency: "usd") { taxRate totalTax totalAmount paymentCount }
    byCountry(currency: "usd") { country totalTax totalAmount paymentCount }
    b2bVsB2c(currency: "usd") { isBusiness label totalTax totalAmount orderCount }
    effectiveTaxRateTrend(granularity: MONTH, currency: "usd") { period avgTaxRate paymentCount }
  }
}

---

Subscription Analysis

Billing period distribution, cancellation stats, trial conversion, and churn.

query($storeId: String!) {
  subscriptionAnalysis(
    storeId: $storeId
    filter: { timeRange: { startDate: "2026-01-01T00:00:00Z", endDate: "2026-02-01T00:00:00Z" } }
  ) {
    billingPeriodDistribution(currency: "usd") { billingPeriod count totalAmount percentage }
    activeCount
    cancellationStats { totalSubscriptions canceledCount cancellationRate avgLifetimeDays medianLifetimeDays }
    trialConversion { totalTrials convertedCount activeTrials conversionRate }
    churnRate(granularity: MONTH) { period startActive churned churnRate }
  }
}

---

Refund Ticket Analysis

Reason distribution, review efficiency, and approval rate.

query($storeId: String!) {
  refundTicketAnalysis(
    storeId: $storeId
    filter: { timeRange: { startDate: "2026-01-01T00:00:00Z", endDate: "2026-02-01T00:00:00Z" } }
  ) {
    reasonDistribution(currency: "usd") { reason count totalAmount percentage }
    statusDistribution { status count percentage }
    reviewEfficiency { avgHours medianHours p90Hours totalReviewed }
    ticketTrend(granularity: MONTH) { period totalCreated resolvedCount approvedCount rejectedCount }
    approvalRate { approved rejected rate }
  }
}

---

Settlement Analysis

Actual settled amounts sourced from settlement files (post-fee, post-refund). This is the ground truth for reconciliation, distinct from paymentStatistics.settlementRevenueByCurrency (a PSP projection at payment time).

query($storeId: String!) {
  settlementAnalysis(
    storeId: $storeId
    filter: { timeRange: { startDate: "2026-04-01T00:00:00Z", endDate: "2026-05-01T00:00:00Z" } }
  ) {
    countsByAccountingStatus { status count }
    netSettlementByCurrency { currency totalAmount paymentCount }
    netSettlementByPeriod(granularity: DAY, currency: "usd") { period currency totalAmount paymentCount }
    refundTotalByCurrency { currency totalAmount paymentCount }
    feeTotalByCurrency { currency totalAmount paymentCount }
  }
}

settlementAnalysis time range is based on the settlement date, not created_at. Additional analytics queries are available depending on your role, including deliveryAnalysis (webhook/email delivery) and payoutAnalysis (payout tickets, scoped to the merchant). Use schema introspection to discover their full field sets.

Variables:

{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx" }