> ## 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 クエリ例
## 単発注文
### 完了済み注文の一覧表示
```graphql theme={"system"}
query($storeId: String!) {
onetimeOrders(
storeId: $storeId
filter: { status: { eq: "completed" } }
limit: 50
) {
id
buyerEmail
currency
priceSnapshot {
currency
subtotal
taxAmount
total
taxCategory
}
status
createdAt
}
onetimeOrdersCount(storeId: $storeId)
}
```
**変数：**
```json theme={"system"}
{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx" }
```
### 日付範囲でフィルタリング
```graphql theme={"system"}
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` を渡します。
```graphql theme={"system"}
query($storeId: String!, $ref: String!) {
onetimeOrders(
storeId: $storeId
filter: { orderMerchantExternalId: { eq: $ref } }
) {
id
buyerEmail
status
orderMerchantExternalId
createdAt
}
}
```
**変数：**
```json theme={"system"}
{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx", "ref": "ORDER-2026-00891" }
```
### SDK の例
```typescript theme={"system"}
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" },
});
```
***
## サブスクリプション注文
### 有効なサブスクリプションの一覧表示
```graphql theme={"system"}
query($storeId: String!) {
subscriptionOrders(
storeId: $storeId
filter: { status: { in: ["active"] } }
) {
id
buyerEmail
status
billingPeriod
createdAt
}
subscriptionOrdersCount(storeId: $storeId)
}
```
### キャンセル中のサブスクリプションをフィルタリング
```graphql theme={"system"}
query($storeId: String!) {
subscriptionOrders(
storeId: $storeId
filter: { status: { eq: "canceling" } }
) {
id
buyerEmail
status
createdAt
}
}
```
### ビジネス番号（`orderMerchantExternalId`）でサブスクリプション注文を照会
checkout 作成時に付加した `orderMerchantExternalId` を渡します。後続のすべての更新支払いも同じ値を継承するため、1 つのビジネス番号でサブスクリプションのライフサイクル全体を辿れます。
```graphql theme={"system"}
query($storeId: String!, $ref: String!) {
subscriptionOrders(
storeId: $storeId
filter: { orderMerchantExternalId: { eq: $ref } }
) {
id
buyerEmail
status
billingPeriod
orderMerchantExternalId
createdAt
}
}
```
**変数：**
```json theme={"system"}
{ "storeId": "STO_3bVzrkD0FJjFdZNLk8Ualx", "ref": "SUB-2026-01045" }
```
***
## 支払い
### 成功した支払いの一覧表示
```graphql theme={"system"}
query {
payments(
filter: { status: { eq: "succeeded" } }
limit: 100
) {
id
orderId
status
refundStatus
snapshotAmountDetails {
subtotal
taxAmount
total
currency
}
createdAt
}
paymentsCount(filter: { status: { eq: "succeeded" } })
}
```
### 日付範囲でフィルタリング
```graphql theme={"system"}
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 で支払いを照会
```graphql theme={"system"}
query($paymentId: String!) {
payment(id: $paymentId) {
id
orderId
status
refundStatus
orderMerchantExternalId
snapshotAmountDetails { total currency }
}
}
```
**変数：**
```json theme={"system"}
{ "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA" }
```
### ビジネス番号（`orderMerchantExternalId`）で支払いを照会
checkout 作成時に付加した `orderMerchantExternalId` を渡します（webhook ペイロード `data.orderMerchantExternalId` と同名）。
```graphql theme={"system"}
query($ref: String!) {
payments(filter: { orderMerchantExternalId: { eq: $ref } }) {
id
orderId
status
refundStatus
orderMerchantExternalId
createdAt
}
}
```
**変数：**
```json theme={"system"}
{ "ref": "ORDER-2026-00891" }
```
サブスクリプション注文では、各更新支払いは**同じ `orderMerchantExternalId` を継承**します。上記クエリは同じビジネス番号の全支払い履歴を `createdAt DESC` 順で返します。
***
## 集計とソート
### 支払いを日次で集計
`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`）は時間次元にのみ適用されます。
```graphql theme={"system"}
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` です。
```graphql theme={"system"}
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 ペイロードと同名。
```graphql theme={"system"}
query($refundId: String!) {
refund(id: $refundId) {
id
paymentId
ticketId
status
orderMerchantExternalId
refundTicketMerchantExternalId
pspAmountDetails { amount currency }
createdAt
}
}
```
**変数：**
```json theme={"system"}
{ "refundId": "RFD_8aHbCcDdEeFfGgHhIiJjKk" }
```
### 支払い（Waffo 支払い ID）で返金を照会
```graphql theme={"system"}
query($paymentId: String!) {
refunds(filter: { paymentId: { eq: $paymentId } }) {
id
status
orderMerchantExternalId
refundTicketMerchantExternalId
pspAmountDetails { amount currency }
createdAt
}
}
```
### ビジネス番号で返金を照会
**返金チケットのビジネス番号**（返金チケット作成時に付加したもの）で一致 — `refundTicketMerchantExternalId` フィルタを使用：
```graphql theme={"system"}
query($ref: String!) {
refunds(filter: { refundTicketMerchantExternalId: { eq: $ref } }) {
id
paymentId
ticketId
status
orderMerchantExternalId
refundTicketMerchantExternalId
pspAmountDetails { amount currency }
createdAt
}
}
```
または**注文のビジネス番号**で一致（この reference を持つ支払いの全返金を返す、サブスク更新シナリオ向け）— payment 層でフィルタリングし、その nested refunds を読み取ります：
```graphql theme={"system"}
query($paymentRef: String!) {
payments(filter: { orderMerchantExternalId: { eq: $paymentRef } }) {
id
orderMerchantExternalId
refunds {
id
status
refundTicketMerchantExternalId
pspAmountDetails { amount currency }
createdAt
}
}
}
```
***
## 返金チケット
### すべての返金チケットを一覧表示
```graphql theme={"system"}
query {
refundTickets {
id
paymentId
status
requestedAmount
reason
createdAt
}
refundTicketsCount
}
```
### 保留中の返金をフィルタリング
```graphql theme={"system"}
query {
refundTickets(filter: { status: { eq: "pending" } }) {
id
paymentId
requestedAmount
reason
createdAt
}
}
```
### 特定の支払いの返金
```graphql theme={"system"}
query($paymentId: String!) {
refundTickets(filter: { subjectId: { eq: $paymentId } }) {
id
status
refundTicketMerchantExternalId
versionData {
reason
requestedAmount { amount currency }
}
createdAt
}
}
```
**変数：**
```json theme={"system"}
{ "paymentId": "PAY_6eYCunG3IMmIgcQOnaXdoA" }
```
### ビジネス番号（`refundTicketMerchantExternalId`）で返金チケットを照会
```graphql theme={"system"}
query($ref: String!) {
refundTickets(filter: { refundTicketMerchantExternalId: { eq: $ref } }) {
id
status
refundTicketMerchantExternalId
versionData {
reason
requestedAmount { amount currency }
}
reviewNote
rejectReason
executedAt
createdAt
}
}
```
**変数：**
```json theme={"system"}
{ "ref": "REF-2026-00891" }
```
`RefundTicket`(リクエスト)と `Refund`(実行レコード)は**異なる 2 つの GraphQL 型**ですが、ビジネス側識別子は webhook ペイロードと同じフラット名を持ちます:`RefundTicket` と `Refund` の両方が `refundTicketMerchantExternalId` を公開し、`Refund` はさらに `orderMerchantExternalId`(元の注文から継承)も公開します。Webhook ペイロードは同じ 2 つの値を `data.orderMerchantExternalId` と `data.refundTicketMerchantExternalId` として運びます。
***
## チェックアウトセッション
### セッション詳細のクエリ
```graphql theme={"system"}
query($sessionId: ID!) {
checkoutSession(id: $sessionId) {
id
productType
currency
status
expiresAt
createdAt
}
}
```
**変数：**
```json theme={"system"}
{ "sessionId": "cs_550e8400-e29b-41d4-a716-446655440000" }
```