在创建订单前预览结账会话的税额计算。此端点在消费者输入或更新账单信息时从托管结账页面调用。
POST /v1/actions/checkout/preview-tax
请求体
| 字段 | 类型 | 必需 | 说明 |
|---|
checkoutSessionId | string | 是 | 结账会话 ID（cs_ + UUID 格式） |
billingDetail | object | 是 | 用于税额计算的账单信息 |
账单信息对象
| 字段 | 类型 | 必需 | 说明 |
|---|
country | string | 是 | ISO 3166-1 alpha-2 国家代码 |
isBusiness | boolean | 是 | 是否为企业购买 |
state | string | 条件 | US 和 CA 必填 |
请求示例
const response = await fetch("https://api.waffo.ai/v1/actions/checkout/preview-tax", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Store-Slug": "my-store-abc123",
"X-Environment": "test",
},
body: JSON.stringify({
checkoutSessionId: "cs_550e8400-e29b-41d4-a716-446655440000",
billingDetail: {
country: "US",
isBusiness: false,
state: "CA",
},
}),
});
const { data } = await response.json();
console.log(data.total); // => "31.61"
成功响应
{
"data": {
"subtotal": "29.00",
"taxAmount": "2.61",
"total": "31.61",
"taxRate": 0.09
}
}
响应字段
| 字段 | 类型 | 说明 |
|---|
subtotal | string | 产品价格的显示格式字符串（如 “29.00” = $29.00） |
taxAmount | string | 计算的税额显示格式字符串 |
total | string | subtotal + taxAmount |
taxRate | number | 适用税率（小数形式，如 0.09 = 9%） |
| 状态码 | 消息 | 说明 |
|---|
| 400 | 缺少必填字段 | checkoutSessionId 或 billingDetail 缺失 |
| 400 | US/CA 缺少 state | country 为 US 或 CA 时 state 必填 |
| 404 | 会话未找到 | 没有匹配给定 ID 的结账会话 |
| 404 | 会话已过期 | 结账会话已过期 |
所有金额为显示格式字符串（如 USD 的 “29.00”，JPY 的 “4500”）。例如，USD 中的 "29.00" 表示 $29.00。
