Metadata
metadata is a JSON object of your own keys and values that HL Hunt stores on a resource and returns to you unchanged. Use it to carry your order id, CRM id or any correlation data.
Which resources accept it
| Resource | Accepted on | Returned by | Carried in webhooks |
|---|---|---|---|
| Charge | POST /v1/charges | GET /v1/charges/{id} | charge.succeeded, charge.failed (always; metadata is part of the charge object, {} when none) |
| Customer | POST /v1/customers, PUT /v1/customers/{id} (replaces) | GET /v1/customers/{id} | customer.created, customer.updated |
| Checkout Session | POST /v1/checkout/sessions | session object | checkout.session.completed, checkout.session.expired; also copied onto the resulting charge |
| Subscription | POST /v1/subscriptions, PUT /v1/subscriptions/{id} | subscription object | subscription.* |
| Product | POST /v1/products, PUT /v1/products/{id} | product object | product.created |
| Payment Arrangement | POST /v1/arrangements | arrangement object | arrangement.* |
Refunds, payment methods, payouts and webhook endpoints do not take metadata.
Rules the code applies
- Any JSON object is accepted; values may be strings, numbers, booleans, nested objects or arrays. The validators do not enforce a key count or a size limit, and nothing truncates values. The only bound is the request body size. Keep it small (a few short keys) so webhook payloads stay small.
- Keys are stored exactly as sent. Webhook payloads convert resource field names to snake_case, but keys inside
metadataare passed through untouched. - Charges: HL Hunt adds nothing to your metadata in the stored copy. After an ACH return the charge's metadata gains a
bankReturnobject (see ACH & bank accounts). Reserve that key. - Checkout Sessions: keys beginning with
_are reserved for HL Hunt and are stripped from the public session object and webhooks. When the session is paid, the remaining keys are copied onto the charge with every value converted to a string (objects are JSON-encoded). - Customers:
PUTwithmetadatareplaces the whole object; it is not merged. tagsis not a request field. Older pages showed atagsobject onPOST /v1/charges; the handler ignores it. Usemetadata.