元数据

Subotiz 支持为多个核心资源对象添加 metadata 字段，用于存储额外的结构化信息。metadata 是键值对（key-value）格式的数据，不会影响 Subotiz 核心支付、订阅等业务逻辑，仅作为开发者自定义数据的载体，方便关联自有系统信息、追踪业务流程或标注资源属性。

核心特性与限制

字段限制

最多支持 20 个键（key），超出会返回参数校验错误
键（key）长度最多 40 个字符，值（value）长度最多 500 个字符
键和值均以字符串（string）形式存储，不支持嵌套 JSON、数字、布尔值等类型

支持的资源对象

metadata 可用于以下 Subotiz 资源，支持创建时添加、后续查询和更新：Checkout Session、Subscription、Invoice、Trade、Customer、Refund Order

常见使用场景

关联自有系统 ID：将你的订单号（order_id）、用户 ID（user_id）绑定到 Subotiz 资源，例如给 Checkout Session 添加 metadata:
```
{
    "your_order_id": "ORD123456",
    "your_user_id": "U789"
}
```
退款追踪：存储退款原因、操作人等信息。例如给 Refund Order 添加 metadata:
```
{
    "refund_reason": "product_defect",
    "operator": "admin_001"
}
```
业务流程标注：给 Subscription 添加 metadata，用于自有系统识别订阅等级
```
{
    "plan_level": "premium",
    "renewal_reminder": "true"
}
```
跨资源关联：通过 Checkout Session 的透传规则，实现数据向后续生成资源（如 Subscription、Trade）的传递

Metadata 继承机制

Subotiz 的 metadata 采用「独立存储 + 按需透传」机制，不自动继承父资源 metadata。支持通过 Checkout Session 创建时指定的参数，将数据透传到后续生成的资源中。

无商品路径（mode=payment）

graph LR
    A[商户] -->|调用创建结账会话接口<br>指定：trade_data.metadata 参数| B[Checkout Session]
    B -->|用户支付触发生成 Trade<br>透传 trade_data.metadata| C[Trade]

有商品路径（mode=checkout）

graph LR
    A[商户] -->|调用创建结账会话接口<br>指定：subscription_data.metadata 参数| B[Checkout Session]
    B -->|支付成功触发创建 Subscription<br>透传 subscription_data.metadata| C[Subscription]
    C -->|续订生成 Invoice<br>通过 subscription_id 关联查询 metadata| D[Invoice]

透传规则

参数隔离：metadata（自身）、trade_data.metadata、subscription_data.metadata 是独立参数，需分别指定。
独立存储：每个资源仅保存自身被透传的参数，修改上游资源的 metadata 不会影响已生成的下游资源。
关联查询：下游资源若需获取上游未直接透传的 metadata，需通过关联 ID（如 subscription_id）主动查询对应资源详情。

注意事项

禁止存储敏感信息：不要在 metadata 中存储银行卡号、身份证号等敏感数据，仅用于非敏感业务标识。
透传参数必填性：若需向 Trade/Subscription 透传 metadata，需在创建 Checkout Session 时明确指定对应参数，否则下游资源的 metadata 为空。
字段校验：超过键数量、字符长度限制会返回 400 Bad Request，错误信息会明确提示超限字段。