订单和支付

一次性订单

列出已完成订单

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。每次续期支付都会继承相同的值，因此一个业务号能串起整个订阅生命周期。

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($id: String!) {
  subscriptionOrder(id: $id) {
    id
    status
    priceSnapshot {
      currency
      specialPhaseDays
      specialPhase { total listTotal discountAmount discountedTaxAmount }
      regularPhase { total listTotal discountAmount discountedTaxAmount }
      firstPeriod { total listTotal discountAmount discountedTaxAmount }
    }
    discount {
      code
      appliedVia
      status
      listAmount { display }
      discountAmount { display }
    }
    activeDiscount { code couponId status duration durationInPeriods periodsUsed isActive endsAt }
    payments {
      id
      status
      periodNumber
      snapshotAmountDetails { currency listTotal discountAmount taxAmount total phase }
    }
  }
}

Variables:

{ "id": "ORD_7cWxyzAbCdEfGhIjKlMnOp" }

字段	说明
`discount`	订单上的优惠：`code`、`appliedVia`（优惠的应用方式：`coupon_id` —— 你传的 `couponId`；`promotion_code` —— 你预填的 `promotionCode`；`discount_code` —— 商品链接的 `discount_code`；`checkout` —— 买家输入；该字段上线前的部分优惠为 `null`）、`status`（第一笔享受优惠的扣款成功前为 `reserved`，之后为 `applied`）、`listAmount`（第一笔享受优惠的扣款的优惠前价格 —— 付费试用为试用价）与 `discountAmount`（由该笔支付确认；确认前为 `null`）。订单没有优惠或名额已归还时为 `null`。更换方案延续的优惠从 `activeDiscount` 读取 —— 例外：延续时仍为 `reserved` 的优惠在更换方案成功后转到新订单，也会出现在新订单的 `discount` 中
`activeDiscount`	优惠的持续期与进度。`duration`；`durationInPeriods`（仅 `repeating`）；`periodsUsed` —— 成功且优惠前金额大于 0 的扣款笔数（零元试用不计）；`isActive` —— 下一笔扣款是否仍预期享受优惠：订阅仍在计费、优惠券的到期时间晚于下一笔扣款日（当期结束日）、持续期未用完；`endsAt` —— 优惠券的到期时间，不限时为 `null`。订单自身没有优惠、也没有从换方案延续的优惠时为 `null` —— 延续的优惠即使 `discount` 为 `null` 也会出现在这里。由更换方案产生的订阅，这里给出换方案时输入的新码，没带码时给出从上一个订阅延续的优惠，`periodsUsed` 跨换方案累计。`code` 为所用的码，`couponId` 为优惠券 ID（`CPN_xxx`），`status` 为这次用码的状态（`reserved`、`applied` 或 `needs_reconcile`，同 `discount`）；延续的优惠给出原来那次用码的值。买家查询自己的订单与订阅时没有 `appliedVia`、`couponId` 与 `status`；你用 `couponId` 指定的优惠（含延续的）`code` 为 `null` —— 买家看到优惠但不显示码；其余情况 `code` 与你看到的相同
`specialPhase` / `regularPhase` → `total`	该 phase 的优惠前含税标价（`specialPhase` 为试用价）。`listTotal` 恒等于它
`specialPhase` / `regularPhase` → `discountAmount` / `discountedTaxAmount`	该 phase 的一期享受优惠时的优惠额与税额。按持续期不可能享受优惠的 phase 为 `0` 与 `taxAmount`：无优惠、零元试用，以及付费试用 + `once` 或 `repeating` 1 期时的正价期。某一期是否真的享受优惠看该期的支付
`firstPeriod`	只出现在由立即生效、未给试用的更换方案产生的订阅上：第 1 期，与正价期分开定价。`total` 是它的优惠前金额 —— 新方案价减去按天折抵，或商户指定的金额；`discountAmount` / `discountedTaxAmount` 与上面的 phase 相同，第 1 期不享受优惠时为 `0` 与 `taxAmount`。`discountAmount` 按新方案全价计算，以 `total` 为上限（新方案 99.00、折抵 8.90、减 20% → `total` 90.10、`discountAmount` 19.80，买家实付 70.30）。折抵覆盖整个第 1 期时 `total`、`discountAmount`、`discountedTaxAmount` 均为 `0`。新订阅的第一笔支付按它写入 `snapshotAmountDetails`，`phase` 为 `regular`（`total` 为 `0` 时这笔是 $0 支付），之后的支付按正价期写入。其他情况为 `null`
`snapshotAmountDetails` → `listTotal` / `discountAmount` / `total`	这笔支付的预期：优惠前价格（该 phase 的标价 —— 试用期扣款为试用价）、本期优惠额（不享受时为 `0`）与应付额，满足 `listTotal − discountAmount = total`。`taxAmount` 为 `total` 中的税额。下周期生效的更换方案在切换前完成的 $0 授权，三项预期均为 `0`，`phase` 为 `special`；切换后的第一笔扣款按正价期写入

这些字段上线前记录的支付回落为 listTotal = total、discountAmount = 0。

支付

列出成功的支付

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

snapshotAmountDetails.total 是这笔支付的预期金额（含优惠后）。listTotal 与 discountAmount 分别是优惠前价格与优惠额，满足 listTotal − discountAmount = total；无优惠时 discountAmount 为 0。

按日期范围过滤

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 为它下发的值相同。扣款失败同样占用一期，因此它不是成功扣款次数。一次性支付与本字段上线前创建的支付为 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 值为最小货币单位（如分）的整数字符串。金额按命中 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。

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 载荷同名。

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

变量：

{ "refundId": "RFD_8aHbCcDdEeFfGgHhIiJjKk" }

Refund 上有两个金额。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 filter：

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

或按订单业务号匹配（返回所有挂在此 reference 下的支付的全部退款,适合订阅续期场景）— 在 payment 层 filter 并读取其 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(执行记录)是两个不同的 GraphQL 类型,但它们的业务侧标识跟 webhook 载荷同名:RefundTicket 和 Refund 都暴露 refundTicketMerchantExternalId;Refund 额外暴露 orderMerchantExternalId(从原始订单继承)。Webhook 载荷上携带相同的两个值 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`）查询退款工单