shopify-admin-payout-reconciliation

用途

该技能用于将 Shopify Payments 的付款（payout）与为其提供资金的订单交易进行对账。针对每笔付款，它会汇总毛销售额、退款、调整和费用，计算预期净额，并与付款报告的实际净额进行比较。差异会被标记，并附带差额和疑似原因。该技能为只读，不执行任何变更操作。

前置条件

已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_shopify_payments_payouts,read_orders
API 权限范围：read_shopify_payments_payouts、read_orders
商店必须使用 Shopify Payments。如果商店仅使用第三方支付网关，该技能会干净退出并给出提示。

参数

参数	类型	必填	默认值	说明
store	string	是	—	商店域名（例如 mystore.myshopify.com）
days_back	integer	否	30	覆盖该期间内已发放付款的回溯窗口
tolerance	number	否	0.01	标记差异前可接受的商店货币差额
format	string	否	human	输出格式：human 或 json

安全性

该技能为只读，不执行任何变更操作。对账输出仅供参考；在 Shopify 后台审查底层交易之前，不应将标记的差异视为已确认的错误。

工作流程

查询 shopifyPaymentsAccount，获取窗口内所有付款（含 id、issuedAt、status、net、gross 及 summary 中的各项金额）。如果账户为 null，则退出——商店未使用 Shopify Payments。
对每笔付款计算对账预期：

expected_net = chargesGross - chargesFee
             - refundsGross + refundsFee   (refundsFee 通常为负 / 冲回)
             + adjustmentsGross - adjustmentsFee
             + retriedPayoutsGross - retriedPayoutsFee

delta = reported_net - expected_net

仅对标记的付款，查询 orders 进行下钻，获取可能为该付款提供资金的候选订单，用于对差额最大的付款做订单级交叉核对。
对每笔付款分类：若 |delta| <= tolerance 则为 ok；否则为 discrepancy，并记录符号（正：付款多付给我们；负：付款少付给我们）。
汇总窗口内的总计：付款总数、已对账数、差异数、绝对差额之和。

GraphQL 操作

# shopifyPaymentsAccount:query — 已针对 api_version 2025-01 验证
query PayoutReconciliation($payoutQuery: String!, $payoutAfter: String) {
  shopifyPaymentsAccount {
    id
    payoutSchedule { interval }
    payouts(first: 100, after: $payoutAfter, query: $payoutQuery) {
      edges {
        node {
          id
          issuedAt
          status
          net { amount currencyCode }
          gross { amount currencyCode }
          summary {
            chargesGross { amount currencyCode }
            chargesFee { amount currencyCode }
            refundsFeeGross { amount currencyCode }
            refundsFee { amount currencyCode }
            adjustmentsGross { amount currencyCode }
            adjustmentsFee { amount currencyCode }
            retriedPayoutsGross { amount currencyCode }
            retriedPayoutsFee { amount currencyCode }
          }
        }
      }
      pageInfo { hasNextPage endCursor }
    }
  }
}

# orders:query — 已针对 api_version 2025-01 验证
query OrdersFundingPayout($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        processedAt
        totalPriceSet { shopMoney { amount currencyCode } }
        totalReceivedSet { shopMoney { amount currencyCode } }
        transactions {
          id
          gateway
          kind
          status
          processedAt
          amountSet { shopMoney { amount currencyCode } }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

会话跟踪

Claude 必须在每个阶段输出以下内容（强制要求）。

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Payout Reconciliation                ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

每步之后输出：

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>

完成时输出。对于 format: human（默认）：

══════════════════════════════════════════════
PAYOUT RECONCILIATION  (<days_back> days)
  Payouts in window:    <n>
  Reconciled (ok):      <n>
  Discrepancies:        <n>   ⚠️
  Sum of abs deltas:    $<amount>

  Top discrepancies:
    Payout <date>  Reported: $<n>  Expected: $<n>  Δ: $<n>

  Output: payout_reconciliation_<date>.csv
══════════════════════════════════════════════

对于 format: json：

{
  "skill": "payout-reconciliation",
  "store": "<domain>",
  "period_days": 30,
  "payouts_count": 0,
  "reconciled_count": 0,
  "discrepancy_count": 0,
  "sum_abs_delta": 0,
  "currency": "USD",
  "output_file": "payout_reconciliation_<date>.csv"
}

输出格式

CSV 文件 payout_reconciliation_<YYYY-MM-DD>.csv，列包括： payout_id, issued_at, status, reported_net, expected_net, delta, currency, charges_gross, charges_fee, refunds_gross, refunds_fee, adjustments_gross, verdict

错误处理

错误	原因	恢复方式
THROTTLED	超过 API 速率限制	等待 2 秒，最多重试 3 次
shopifyPaymentsAccount 为 null	商店未使用 Shopify Payments	干净退出；建议通过第三方网关仪表板对账
付款内货币不匹配	多货币商店	仅对与账户货币一致的呈报货币付款对账；其他标记为 currency_mismatch
付款仍为 IN_TRANSIT	尚未最终确定	跳过——待状态变为 PAID 后再对账

最佳实践

在付款计划发放后的次日早晨每周运行一次——当日对账能在交易易于调查时发现差异。
对任何标记的差异进行下钻：在付款窗口内处理的退款常常出现在下一笔付款的 refundsGross 中，如果忘记跨窗口对账，可能看起来像少付。
将此技能与会计导出配合使用——这些数字应与记账软件的存款记录精确到分。
谨慎使用大于 $0.01 的容差：超过几美分的任何金额通常反映真实的费用或调整，值得解释。
该技能不检测欺诈；它检测会计差额。如果怀疑欺诈，请通过 Shopify 后台的付款详情视图上报。