> ## 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.

# 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 theme={null}
   {
       "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 theme={null}
   {
       "refund_reason": "product_defect",
       "operator": "admin_001"
   }
   ```
3. **Business Process Annotation**: Add metadata to a Subscription for proprietary system recognition of subscription levels:
   ```json theme={null}
   {
       "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)
  ```mermaid theme={null}
  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)
  ```mermaid theme={null}
  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). <br />

## 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.