> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# アナリティクス

> 収益、支払い、顧客分析の GraphQL クエリ例

## 概要

アナリティクスクエリは単一ストアの事前集計済み統計を返します。各アナリティクスクエリは以下を受け取ります：

* ストア識別子 —— `storeId` **または** `storeSlug`（トップレベル引数、いずれか一方が必須）。
* 必須の `filter`（型は `AnalyticsFilterInput!`）。

```graphql theme={"system"}
input AnalyticsFilterInput {
  timeRange: TimeRangeInput!   # { startDate, endDate } ISO 8601 文字列 —— 必須
  currency: String             # 任意、ISO 4217
  status: String               # 任意
}
```

多くのネストされたフィールドは独自の引数を持ち、最も一般的なのは `granularity` と `currency` です。時間の粒度は `TimePeriodGranularity` 列挙型を使用します：`DAY`、`WEEK`、`MONTH`、`QUARTER`、`YEAR`、`ALL_TIME`。

<Note>
  各アナリティクスクエリはスカラーの合計値ではなく**構造化オブジェクト**を返します。金額フィールドは表示用文字列として返されます。必要なネストされたフィールドを選択してください —— 以下の例で利用可能な構造を示します。
</Note>

***

## 注文統計

注文数、デュアルソース収益、購入者メトリクス。

```graphql theme={"system"}
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 }
  }
}
```

<Note>
  `revenueByCurrency` / `revenueByPeriod` は**デュアルソース**です：`pspTotalAmount` は PSP の実際の金額、`snapshotTotalAmount` はスナップショットの予想金額、`mismatchCount` は両者が一致しない支払い件数です。
</Note>

**変数：**

```json theme={"system"}
{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx" }
```

***

## 支払い統計

成功率、失敗理由、返金、支払い方法の分布、税額サマリー。

```graphql theme={"system"}
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 }
  }
}
```

<Note>
  `successRate` は**オブジェクト**（`{ totalAttempts, succeeded, failed, pending, successRate }`）であり、スカラーではありません。
</Note>

***

## 商品統計

商品数、売れ筋ランキング、収益貢献度。

```graphql theme={"system"}
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 }
  }
}
```

***

## トレンド分析

期間比成長率、累積収益、移動平均。

```graphql theme={"system"}
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 }
  }
}
```

***

## 分布分析

注文金額のパーセンタイル、AOV（平均注文額）トレンド、金額分布バケット。

```graphql theme={"system"}
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 }
  }
}
```

***

## 顧客分析

リテンション、LTV 分布、購入頻度、優良顧客。

```graphql theme={"system"}
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 }
  }
}
```

***

## 税務分析

税区分、税率グループ、国別の税額、および B2B/B2C 比較。

```graphql theme={"system"}
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 }
  }
}
```

***

## サブスクリプション分析

請求期間の分布、キャンセル統計、トライアル転換、チャーン率。

```graphql theme={"system"}
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 }
  }
}
```

***

## 返金チケット分析

返金理由の分布、レビュー効率、承認率。

```graphql theme={"system"}
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 }
  }
}
```

***

## 清算分析

清算ファイルに基づく実際の入金額（手数料控除後・返金控除後）。これは照合のグラウンドトゥルースであり、`paymentStatistics.settlementRevenueByCurrency`（支払い時点の PSP 見積り換算値）とは口径が異なります。

```graphql theme={"system"}
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 }
  }
}
```

<Note>
  `settlementAnalysis` の期間は `created_at` ではなく清算日に基づきます。ロールに応じて、`deliveryAnalysis`（Webhook/メール配信）や `payoutAnalysis`（出金チケット、マーチャント主体スコープ）など、他のアナリティクスクエリも利用できます。完全なフィールドセットは schema イントロスペクションで確認してください。
</Note>

**変数：**

```json theme={"system"}
{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx" }
```