> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 元数据

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

## 核心特性与限制

### 字段限制

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

### 支持的资源对象

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

## 常见使用场景

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

## Metadata 继承机制

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

* **无商品路径**（mode=payment）
  ```mermaid theme={null}
  graph LR
      A[商户] -->|调用创建结账会话接口<br>指定：trade_data.metadata 参数| B[Checkout Session]
      B -->|用户支付触发生成 Trade<br>透传 trade_data.metadata| C[Trade]
  ```
* **有商品路径**（mode=checkout）
  ```mermaid theme={null}
  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）主动查询对应资源详情。 <br />

## 注意事项

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