> ## 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`。每次续期支付都会继承相同的值，因此一个业务号能串起整个订阅生命周期。
```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` 值为**最小货币单位**（如分）的整数字符串。金额按命中 filter 的所有行求和，因此涉及多币种时应按 `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` 上两个业务号以扁平字段公开:`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` filter：
```graphql theme={"system"}
query($ref: String!) {
refunds(filter: { refundTicketMerchantExternalId: { eq: $ref } }) {
id
paymentId
ticketId
status
orderMerchantExternalId
refundTicketMerchantExternalId
pspAmountDetails { amount currency }
createdAt
}
}
```
或按**订单业务号**匹配（返回所有挂在此 reference 下的支付的全部退款,适合订阅续期场景）— 在 payment 层 filter 并读取其 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`(执行记录)是**两个不同的 GraphQL 类型**,但它们的业务侧标识跟 webhook 载荷同名:`RefundTicket` 和 `Refund` 都暴露 `refundTicketMerchantExternalId`;`Refund` 额外暴露 `orderMerchantExternalId`(从原始订单继承)。Webhook 载荷上携带相同的两个值 `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" }
```