tax-liability-summary

用途

Tax Liability Summary 是一个只读的 Shopify 管理技能，用于汇总一段时间内所有订单中已收取的税额，并按税务管辖区（州/省、国家）和税率进行细分。它生成适合周期性税务申报准备的摘要。该技能为只读操作，不执行任何变更。

主要能力

按管辖区或税率对已收取税额进行分组汇总。
支持指定回溯窗口（默认 90 天），可匹配申报周期（如 30 天或 90 天）。
可选择排除已全额退款订单的税额（默认排除）。
输出人类可读摘要或 JSON 格式。
生成 CSV 文件，包含管辖区、国家代码、省/州代码、税率、订单数、总税额和货币等列。

使用方式

前置条件

已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_orders
API 权限范围：read_orders

参数

参数	类型	必填	默认值	说明
store	string	是	—	商店域名（例如 mystore.myshopify.com）
days_back	integer	否	90	回溯窗口（使用 30/90 以匹配申报周期）
group_by	string	否	jurisdiction	分组方式：jurisdiction 或 rate
exclude_refunded	bool	否	true	排除已全额退款订单的税额
format	string	否	human	输出格式：human 或 json

工作流程

查询已付款订单：使用查询 financial_status:paid created_at:>='<NOW - days_back days>'，每页 250 条，选择 taxLines { title, rate, priceSet }、refunds { refundLineItems }，并处理分页游标，直到 hasNextPage: false。
如果 exclude_refunded 为真，则减去已全额退款订单的税额。
按 group_by（管辖区标题或税率）分组，汇总 taxLine.priceSet.shopMoney.amount。

GraphQL 操作

# orders:query — validated against api_version 2025-01
query TaxLiabilityOrders($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        displayFinancialStatus
        totalTaxSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        taxLines {
          title
          rate
          priceSet {
            shopMoney {
              amount
              currencyCode
            }
          }
        }
        shippingAddress {
          countryCode
          provinceCode
        }
        refunds {
          totalRefundedSet {
            shopMoney {
              amount
              currencyCode
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪

Claude 必须在每个阶段发出以下输出。这是强制性的。

开始时发出：

╔══════════════════════════════════════════════╗
║  SKILL: Tax Liability Summary                ║
║  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（默认）：

══════════════════════════════════════════════
TAX LIABILITY SUMMARY  (<days_back> days)
  Orders analyzed:   <n>
  Total tax collected: $<amount>

  By Jurisdiction:
    CA - California     $<amount>  (<n> orders)
    NY - New York       $<amount>  (<n> orders)
  Output: tax_liability_<date>.csv
══════════════════════════════════════════════

对于 format: json，发出：

{
  "skill": "tax-liability-summary",
  "store": "<domain>",
  "period_days": 90,
  "orders_analyzed": 0,
  "total_tax_collected": 0,
  "currency": "USD",
  "by_jurisdiction": [],
  "output_file": "tax_liability_<date>.csv"
}

输出格式

CSV 文件 tax_liability_<YYYY-MM-DD>.csv，包含列： jurisdiction, country_code, province_code, tax_rate, order_count, total_tax_collected, currency

适用场景

为周期性税务申报准备数据，例如月度或季度申报。
按管辖区或税率了解已收取税额的分布。
需要快速生成内部税务汇总报告，而不修改任何商店数据。

限制与注意事项

该技能为只读，不执行任何变更，可随时安全运行。
报告仅用于内部准备目的，实际申报义务请咨询税务专业人士。
该报告反映从客户处收取的税额，不能替代 Shopify Tax 或专业的关联分析（nexus analysis）。
对于美国多州商家，在依赖此输出之前，请检查 Shopify Tax 是否针对每个关联州正确配置。
taxLines.title 中的 jurisdiction 字段由 Shopify Tax 设置，通常包含州/省名称，请验证格式是否与您的申报系统匹配。
如果订单没有税行（未配置税或免税订单），报告这些订单为 $0。
部分退款订单的税额抵免计算复杂，会在输出中标记；如果 exclude_refunded: true，则从总计中排除。
错误处理：THROTTLED（API 速率限制超出）时，等待 2 秒，最多重试 3 次。

最佳实践

将 days_back 与您的申报周期对齐（月度申报者 30 天，季度申报者 90 天）。
对于美国多州商家，在依赖此输出之前，请检查 Shopify Tax 是否针对每个关联州正确配置。
验证 taxLines.title 中的 jurisdiction 格式是否与您的申报系统匹配。