Metadata
Constraints and supported value types for the user-defined `metadata` bag attached to orders and related resources.
Many Decal resources accept a metadata field — a flat key/value bag for attaching your own data
that round-trips on every API response and webhook delivery. This page documents the constraints
that apply everywhere metadata is accepted.
Constraints
| Constraint | Limit |
|---|---|
| Max keys | 50 |
| Key length | 1 - 40 characters |
| Key pattern | [a-zA-Z0-9_-] — letters, numbers, underscores, hyphens only |
| Value types | string, number (finite), boolean, null, or an array of those primitives |
| String value length | Up to 500 characters (applies to top-level strings and strings inside arrays) |
| Array length | Up to 10 elements |
Examples
Valid:
{
"source": "landing-page",
"campaign_id": "spring-2026",
"count": 3,
"active": true,
"referrer": null,
"tags": ["gift", "priority"],
"priority_scores": [1, 2, 3]
}Not supported: nested objects, arrays of objects, NaN, Infinity. If you need to attach
structured data, serialize it yourself:
{
"metadata": {
"payload": "{\"shipping\":{\"carrier\":\"ups\",\"service\":\"ground\"}}"
}
}Why these limits exist
These constraints keep payloads predictable across API responses and webhook deliveries, and prevent a single merchant's metadata from bloating stored rows or blowing past webhook timeouts.
Requests that exceed any limit are rejected with 400 and a validation error identifying the
offending field.