元数据

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:
   {
       "your_order_id": "ORD123456",
       "your_user_id": "U789"
   }
   
2. 退款追踪：存储退款原因、操作人等信息。例如给 Refund Order 添加 metadata:
   {
       "refund_reason": "product_defect",
       "operator": "admin_001"
   }
   
3. 业务流程标注：给 Subscription 添加 metadata，用于自有系统识别订阅等级
   {
       "plan_level": "premium",
       "renewal_reminder": "true"
   }
   
4. 跨资源关联：通过 Checkout Session 的透传规则，实现数据向后续生成资源（如 Subscription、Trade）的传递

​

Metadata 继承机制

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

• 无商品路径（mode=payment）
• 有商品路径（mode=checkout）

​

透传规则

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

​

注意事项

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