Metadata

Subotiz supports adding metadata fields to multiple core resource objects to store additional structured information. Metadata is key-value formatted data that does not affect Subotiz's core payment, subscription, and other business logic. It serves as a carrier for developer-defined data, facilitating the association of proprietary system information, tracking business processes, or marking resource attributes.

Core Features and Limitations

Field Limitations

• Supports a maximum of 20 keys; exceeding this will return a parameter validation error.
• Key length is limited to 40 characters, and value length is limited to 500 characters.
• Both keys and values are stored as strings, and do not support nested JSON, numbers, booleans, etc.

Supported Resource Objects

Metadata can be used for the following Subotiz resources, supporting addition during creation, subsequent queries, and updates: Checkout Session, Subscription, Invoice, Trade, Customer, Refund Order.

Common Use Cases

1. Associating Proprietary System IDs: Bind your order ID (order_id) and user ID (user_id) to Subotiz resources, such as adding metadata to a Checkout Session:
   JSON

   {
       "your_order_id": "ORD123456",
       "your_user_id": "U789"
   }

2. Refund Tracking: Store information such as refund reasons and operators. For example, add metadata to a Refund Order:
   JSON

   {
       "refund_reason": "product_defect",
       "operator": "admin_001"
   }

3. Business Process Annotation: Add metadata to a Subscription for proprietary system recognition of subscription levels:
   JSON

   {
       "plan_level": "premium",
       "renewal_reminder": "true"
   }

4. Cross-Resource Association: Use the passthrough rules of a Checkout Session to pass data to subsequently generated resources (such as Subscription, Trade).

Metadata Inheritance Mechanism

Subotiz's metadata uses an "independent storage + on-demand passthrough" mechanism, not automatically inheriting parent resource metadata. It supports passing data to subsequently generated resources through parameters specified during Checkout Session creation.

• No Product Path (mode=payment)

  graph LR
      A[Merchant] -->|Call the create checkout session API<br>Specify: trade_data.metadata parameter| B[Checkout Session]
      B -->|User payment triggers Trade generation<br>Passthrough trade_data.metadata| C[Trade]

• With Product Path (mode=checkout)

  graph LR
      A[Merchant] -->|Call the create checkout session API<br>Specify: subscription_data.metadata parameter| B[Checkout Session]
      B -->|Successful payment triggers Subscription creation<br>Passthrough subscription_data.metadata| C[Subscription]
      C -->|Renewal generates Invoice<br>Query metadata through subscription_id| D[Invoice]

Passthrough Rules

• Parameter Isolation: metadata (itself), trade_data.metadata, and subscription_data.metadata are independent parameters and must be specified separately.
• Independent Storage: Each resource only saves its own passed parameters; modifying upstream resource metadata does not affect already generated downstream resources.
• Associated Query: If downstream resources need to obtain upstream metadata that was not directly passed, they must actively query the corresponding resource details through associated IDs (such as subscription_id).
  

Notes

• Prohibit Storing Sensitive Information: Do not store sensitive data such as bank card numbers or ID numbers in metadata; it is only for non-sensitive business identifiers.
• Passthrough Parameter Requirement: If metadata needs to be passed to Trade/Subscription, the corresponding parameters must be explicitly specified when creating a Checkout Session, otherwise the downstream resource's metadata will be empty.
• Field Validation: Exceeding the key number or character length limit will return a 400 Bad Request, with error messages clearly indicating the over-limit fields.