注文と支払い

単発注文

完了済み注文の一覧表示

query($storeId: String!) {
  onetimeOrders(
    storeId: $storeId
    filter: { status: { eq: "completed" } }
    limit: 50
  ) {
    id
    buyerEmail
    currency
    priceSnapshot {
      currency
      subtotal
      taxAmount
      total
      taxCategory
    }
    status
    metadata
    createdAt
  }
  onetimeOrdersCount(storeId: $storeId)
}

変数：

{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx" }

日付範囲でフィルタリング

query($storeId: String!) {
  onetimeOrders(
    storeId: $storeId
    filter: {
      createdAt: {
        gte: "2026-01-01T00:00:00.000Z"
        lte: "2026-03-31T23:59:59.999Z"
      }
    }
  ) {
    id
    buyerEmail
    status
    createdAt
  }
}

ビジネス番号（`orderMerchantExternalId`）で単発注文を照会

checkout 作成時に付加した orderMerchantExternalId を渡します。

query($storeId: String!, $ref: String!) {
  onetimeOrders(
    storeId: $storeId
    filter: { orderMerchantExternalId: { eq: $ref } }
  ) {
    id
    buyerEmail
    status
    orderMerchantExternalId
    createdAt
  }
}

変数：

{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx", "ref": "ORDER-2026-00891" }

SDK の例

const result = await client.graphql.query<{
  onetimeOrders: Array<{
    id: string;
    buyerEmail: string;
    priceSnapshot: { total: number; currency: string };
    status: string;
  }>;
}>({
  query: `query($storeId: String!) {
    onetimeOrders(storeId: $storeId, filter: { status: { eq: "completed" } }) {
      id buyerEmail priceSnapshot { total currency } status
    }
  }`,
  variables: { storeId: "STO_3bVzrkD0FJjFdZNLk8Ualx" },
});

サブスクリプション注文

有効なサブスクリプションの一覧表示

query($storeId: String!) {
  subscriptionOrders(
    storeId: $storeId
    filter: { status: { in: ["active"] } }
  ) {
    id
    buyerEmail
    status
    billingPeriod
    createdAt
  }
  subscriptionOrdersCount(storeId: $storeId)
}

キャンセル中のサブスクリプションをフィルタリング

query($storeId: String!) {
  subscriptionOrders(
    storeId: $storeId
    filter: { status: { eq: "canceling" } }
  ) {
    id
    buyerEmail
    status
    createdAt
  }
}

ビジネス番号（`orderMerchantExternalId`）でサブスクリプション注文を照会

checkout 作成時に付加した orderMerchantExternalId を渡します。後続のすべての更新支払いも同じ値を継承するため、1 つのビジネス番号でサブスクリプションのライフサイクル全体を辿れます。

query($storeId: String!, $ref: String!) {
  subscriptionOrders(
    storeId: $storeId
    filter: { orderMerchantExternalId: { eq: $ref } }
  ) {
    id
    buyerEmail
    status
    billingPeriod
    orderMerchantExternalId
    createdAt
  }
}

変数：

{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx", "ref": "SUB-2026-01045" }

サブスクリプションが何期目かを照会

そのサブスクリプションが現在いる請求期間です。決済チャネルの通知をそのまま保存したもので、 Waffo 側では計算も推測も行いません。初回期間は 1、N 期目は N。0 はチャネルが承認済みでまだ請求していない状態です。請求が失敗した場合も進むため、成功した請求の回数ではありません。最初のチャネル通知が届くまでは null、本フィールド提供開始前に作成されたサブスクリプションも null です。 webhook の data.periodNumber および Payment.periodNumber と同じ概念で、アンカーが異なるだけです —— フィールド説明を参照してください。本フィールドは更新に伴って進みますが、Payment.periodNumber は所属する課金に固定されます。

query($storeId: String!) {
  subscriptionOrders(storeId: $storeId, filter: { status: { in: ["active"] } }) {
    id
    orderMerchantExternalId
    currentPeriodStart
    currentPeriodEnd
    currentPeriodNumber
  }
}

支払い

成功した支払いの一覧表示

query {
  payments(
    filter: { status: { eq: "succeeded" } }
    limit: 100
  ) {
    id
    orderId
    status
    refundStatus
    snapshotAmountDetails {
      subtotal
      taxAmount
      total
      currency
    }
    createdAt
  }
  paymentsCount(filter: { status: { eq: "succeeded" } })
}

日付範囲でフィルタリング

query {
  payments(
    filter: {
      status: { eq: "succeeded" }
      createdAt: {
        gte: "2026-01-01T00:00:00.000Z"
        lte: "2026-03-31T23:59:59.999Z"
      }
    }
  ) {
    id
    orderId
    snapshotAmountDetails {
      subtotal
      taxAmount
      total
      currency
    }
    createdAt
  }
}

Waffo 支払い ID で支払いを照会

query($paymentId: String!) {
  payment(id: $paymentId) {
    id
    orderId
    status
    refundStatus
    orderMerchantExternalId
    snapshotAmountDetails { total currency }
  }
}

変数：

{ "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA" }

ビジネス番号（`orderMerchantExternalId`）で支払いを照会

checkout 作成時に付加した orderMerchantExternalId を渡します（webhook ペイロード data.orderMerchantExternalId と同名）。

query($ref: String!) {
  payments(filter: { orderMerchantExternalId: { eq: $ref } }) {
    id
    orderId
    status
    refundStatus
    orderMerchantExternalId
    createdAt
  }
}

変数：

{ "ref": "ORDER-2026-00891" }

サブスクリプション注文では、各更新支払いは同じ orderMerchantExternalId を継承します。上記クエリは同じビジネス番号の全支払い履歴を createdAt DESC 順で返します。

課金が何期目の支払いかを照会

periodNumber はその課金が属する期間です —— 初回課金は 1、N 回目の更新は N —— サブスクリプション決済 webhook がその課金に対して送った値と同じです。請求が失敗した場合も 1 期間を消費するため、成功した請求の回数ではありません。一回限りの決済、および本フィールド提供開始前に作成された決済では null です。値はその課金に固定されます。現在 3 期目のサブスクリプションでも、初回決済は periodNumber: 1 のままです。サブスクリプションが今どの期間にいるかを知りたい場合は SubscriptionOrder.currentPeriodNumber を使用してください。

query($ref: String!) {
  payments(filter: { orderMerchantExternalId: { eq: $ref } }) {
    id
    orderId
    status
    periodNumber
    createdAt
  }
}

変数：

{ "ref": "SUB-2026-01045" }

集計とソート

支払いを日次で集計

paymentsAggregate は、マッチした全行の count と金額メトリクス amount（sum、avg、min、max）を返し、任意で最大 2 次元でグループ化できます。利用可能な次元：status、currency、payment_method_type、card_brand、store、および時間次元 created_period。granularity（day、week、month、quarter、year；デフォルト day）は時間次元にのみ適用されます。

query {
  paymentsAggregate(
    filter: { status: { eq: "succeeded" }, currency: { eq: "USD" } }
    groupBy: [created_period]
    granularity: day
  ) {
    count
    amount { sum avg min max }
    groups {
      keys { dimension value }
      count
      amount { sum }
    }
    isTruncated
  }
}

集計の amount 値は最小通貨単位（例：セント）の整数文字列です。金額はフィルターにマッチした全行にわたって合計されるため、複数通貨が含まれる場合は currency でグループ化またはフィルターしてください。グループは count 降順でソートされ、上限は 100 グループ（isTruncated が切り捨てを示す）。トップレベルの count/amount は常に全マッチ行をカバーします。他のエンティティも同じ構造を公開しています：refundsAggregate、onetimeOrdersAggregate、subscriptionOrdersAggregate、payoutTicketsAggregate、settlementBatchesAggregate、webhookDeliveriesAggregate、emailDeliveriesAggregate。

`orderBy` によるソート

ソートをサポートするリストクエリは orderBy: [XxxOrderBy!]（列挙のホワイトリスト）を受け付け、デフォルトは created_at DESC です。支払いの選択肢は created_at_desc、created_at_asc、amount_desc、amount_asc です。

query {
  payments(
    filter: { status: { eq: "succeeded" } }
    orderBy: [amount_desc]
    limit: 20
  ) {
    id
    status
    snapshotAmountDetails { total currency }
    createdAt
  }
}

返金（実行されたレコード）

返金レコード（order.refunds）は PSP が返金を確認した後に書き込まれます。これらは返金チケットとは別 — チケットはリクエストのライフサイクルを保持し、返金レコードは実行結果を保持します。

Waffo 返金 ID で返金を照会

Refund は 2 つのビジネス番号をフラットフィールドで公開します:orderMerchantExternalId(元の注文から継承)と refundTicketMerchantExternalId(元の返金チケットから継承) — webhook ペイロードと同名。

query($refundId: String!) {
  refund(id: $refundId) {
    id
    paymentId
    ticketId
    status
    orderMerchantExternalId
    refundTicketMerchantExternalId
    pspAmountDetails { amount currency }
    createdAt
  }
}

変数：

{ "refundId": "RFD_8aHbCcDdEeFfGgHhIiJjKk" }

Refund には 2 つの金額があります。amount は最小通貨単位の Money オブジェクト（USD 49.00 なら "4900"、display は "49.00"）で、pspAmountDetails.amount は決済チャネルが実際に購入者へ返金した金額を表示形式の文字列（"49.00"）で持ちます。チャネル明細との照合には pspAmountDetails を使ってください。申請金額とチャネル金額が一致しない場合は isAmountMismatch が true になります。

支払い（Waffo 支払い ID）で返金を照会

query($paymentId: String!) {
  refunds(filter: { paymentId: { eq: $paymentId } }) {
    id
    status
    orderMerchantExternalId
    refundTicketMerchantExternalId
    pspAmountDetails { amount currency }
    createdAt
  }
}

ビジネス番号で返金を照会

返金チケットのビジネス番号（返金チケット作成時に付加したもの）で一致 — refundTicketMerchantExternalId フィルタを使用：

query($ref: String!) {
  refunds(filter: { refundTicketMerchantExternalId: { eq: $ref } }) {
    id
    paymentId
    ticketId
    status
    orderMerchantExternalId
    refundTicketMerchantExternalId
    pspAmountDetails { amount currency }
    createdAt
  }
}

または注文のビジネス番号で一致（この reference を持つ支払いの全返金を返す、サブスク更新シナリオ向け）— payment 層でフィルタリングし、その nested refunds を読み取ります：

query($paymentRef: String!) {
  payments(filter: { orderMerchantExternalId: { eq: $paymentRef } }) {
    id
    orderMerchantExternalId
    refunds {
      id
      status
      refundTicketMerchantExternalId
      pspAmountDetails { amount currency }
      createdAt
    }
  }
}

返金チケット

すべての返金チケットを一覧表示

query {
  refundTickets {
    id
    paymentId
    status
    requestedAmount
    reason
    createdAt
  }
  refundTicketsCount
}

保留中の返金をフィルタリング

query {
  refundTickets(filter: { status: { eq: "pending" } }) {
    id
    paymentId
    requestedAmount
    reason
    createdAt
  }
}

特定の支払いの返金

query($paymentId: String!) {
  refundTickets(filter: { subjectId: { eq: $paymentId } }) {
    id
    status
    refundTicketMerchantExternalId
    versionData {
      reason
      requestedAmount { amount currency }
    }
    createdAt
  }
}

変数：

{ "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA" }

ビジネス番号（`refundTicketMerchantExternalId`）で返金チケットを照会

query($ref: String!) {
  refundTickets(filter: { refundTicketMerchantExternalId: { eq: $ref } }) {
    id
    status
    refundTicketMerchantExternalId
    versionData {
      reason
      requestedAmount { amount currency }
    }
    reviewNote
    rejectReason
    executedAt
    createdAt
  }
}

変数：

{ "ref": "REF-2026-00891" }

RefundTicket(リクエスト)と Refund(実行レコード)は異なる 2 つの GraphQL 型ですが、ビジネス側識別子は webhook ペイロードと同じフラット名を持ちます:RefundTicket と Refund の両方が refundTicketMerchantExternalId を公開し、Refund はさらに orderMerchantExternalId(元の注文から継承)も公開します。Webhook ペイロードは同じ 2 つの値を data.orderMerchantExternalId と data.refundTicketMerchantExternalId として運びます。

概要

認証

マーチャント API（API Key）

Customer Portal API（Session Token）

GraphQL

単発注文

完了済み注文の一覧表示

日付範囲でフィルタリング

ビジネス番号（`orderMerchantExternalId`）で単発注文を照会

SDK の例

サブスクリプション注文

有効なサブスクリプションの一覧表示

キャンセル中のサブスクリプションをフィルタリング

ビジネス番号（`orderMerchantExternalId`）でサブスクリプション注文を照会

サブスクリプションが何期目かを照会

支払い

成功した支払いの一覧表示

日付範囲でフィルタリング

Waffo 支払い ID で支払いを照会

ビジネス番号（`orderMerchantExternalId`）で支払いを照会

課金が何期目の支払いかを照会

集計とソート

支払いを日次で集計

`orderBy` によるソート

返金（実行されたレコード）

Waffo 返金 ID で返金を照会

支払い（Waffo 支払い ID）で返金を照会

ビジネス番号で返金を照会

返金チケット

すべての返金チケットを一覧表示

保留中の返金をフィルタリング

特定の支払いの返金

ビジネス番号（`refundTicketMerchantExternalId`）で返金チケットを照会

​単発注文

​完了済み注文の一覧表示

​日付範囲でフィルタリング

​ビジネス番号（orderMerchantExternalId）で単発注文を照会

​SDK の例

​サブスクリプション注文

​有効なサブスクリプションの一覧表示

​キャンセル中のサブスクリプションをフィルタリング

​ビジネス番号（orderMerchantExternalId）でサブスクリプション注文を照会

​サブスクリプションが何期目かを照会

​支払い

​成功した支払いの一覧表示

​日付範囲でフィルタリング

​Waffo 支払い ID で支払いを照会

​ビジネス番号（orderMerchantExternalId）で支払いを照会

​課金が何期目の支払いかを照会

​集計とソート

​支払いを日次で集計

​orderBy によるソート

​返金（実行されたレコード）

​Waffo 返金 ID で返金を照会

​支払い（Waffo 支払い ID）で返金を照会

​ビジネス番号で返金を照会

​返金チケット

​すべての返金チケットを一覧表示

​保留中の返金をフィルタリング

​特定の支払いの返金

​ビジネス番号（refundTicketMerchantExternalId）で返金チケットを照会

単発注文

完了済み注文の一覧表示

日付範囲でフィルタリング

ビジネス番号（`orderMerchantExternalId`）で単発注文を照会

SDK の例

サブスクリプション注文

有効なサブスクリプションの一覧表示

キャンセル中のサブスクリプションをフィルタリング

ビジネス番号（`orderMerchantExternalId`）でサブスクリプション注文を照会

サブスクリプションが何期目かを照会

支払い

成功した支払いの一覧表示

日付範囲でフィルタリング

Waffo 支払い ID で支払いを照会

ビジネス番号（`orderMerchantExternalId`）で支払いを照会

課金が何期目の支払いかを照会

集計とソート

支払いを日次で集計

`orderBy` によるソート

返金（実行されたレコード）

Waffo 返金 ID で返金を照会

支払い（Waffo 支払い ID）で返金を照会

ビジネス番号で返金を照会

返金チケット

すべての返金チケットを一覧表示

保留中の返金をフィルタリング

特定の支払いの返金

ビジネス番号（`refundTicketMerchantExternalId`）で返金チケットを照会