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

# Custom metadata

> Attach your own references to accounts, purchases, traders, plans, and rules.

Trading accounts, purchases, traders, plans, and rules all carry a free-form
`metadata` JSON object. Use it to store your own references — payment IDs,
campaign tags, payout records, internal notes. Hyperprop stores and returns
it **verbatim** and never interprets it.

```bash theme={null}
curl -X PATCH "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}" \
  -H "X-API-Key: hp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": { "stripePaymentId": "pi_123", "campaign": "august-sale" },
    "mergeMetadata": true
  }'
```

## Merging vs. replacing

Update endpoints replace the whole `metadata` object by default. Pass
`mergeMetadata: true` for a **shallow (top-level) merge** instead — existing
keys you don't mention are kept.

## Filtering by metadata

List endpoints can filter on metadata, for example:

```text theme={null}
GET /v1/organization/trading-accounts?metadata=stripePaymentId:pi_123
```

This makes `metadata` the natural place to store the identifiers you'll later
need to look accounts up by — order IDs, customer IDs, invoice references.


## Related topics

- [Update a trader](/platform-api/organization/update-a-trader.md)
- [Get a specific purchase](/platform-api/organization/get-a-specific-purchase.md)
- [Quickstart](/quickstart.md)
- [Get purchases for your organization](/platform-api/organization/get-purchases-for-your-organization.md)
- [Get trading plans for your organization](/platform-api/organization/get-trading-plans-for-your-organization.md)