Metadata

In the current public API, metadata is documented as part of public webhook payloads, not as a universal write field on every REST resource.

When a webhook event includes metadata, it appears on the event payload object:

{
  "type": "order.created",
  "data": {
    "object": {
      "id": "ord_example",
      "object": "order",
      "metadata": {
        "external_order_ref": "ORD-4821",
        "source": "mobile-app",
        "priority": true
      }
    }
  }
}

Webhook payload metadata is public-safe integration context. It can be an object or null, and metadata values may be strings, numbers, booleans, or null. Do not treat it as a place for secrets, tokens, passwords, private database IDs, or other internal-only fields.

Some domains, such as orders, invoices, subscriptions, customers, products, brands, categories, and services, may include metadata in their webhook payloads when that context is available. The exact fields are defined by the generated webhook event contracts and examples for each event.

REST API writes

Do not send metadata to a REST endpoint unless that endpoint explicitly documents metadata in its request body. Resource-level metadata writes will be added only through the public API contracts, and each supported resource will document its behavior in the generated reference before clients should rely on it.