Metadata & External Correlation

Use metadata to attach custom fields to commerce objects and to correlate events with external systems (CRMs, fulfillment partners, affiliate networks, healthcare platforms, plan-management services, etc.). This guide covers which objects support custom metadata, how to read it back through the API and webhooks, and the canonical pattern for correlating an external identifier across a customer's full subscription lifecycle.

Supported Objects

The Metadata API lets you define custom fields ("definitions") on a fixed set of object types. The supported types are:

• attribution — Marketing attribution
• customer — Customers
• dispute — Disputes
• line — Order line items
• order — Orders
• product — Products
• variant — Product variants
• blog — Blog posts
• page — CMS pages

Define fields via metadataCreate. Each definition specifies the object type (from the list above), a key, a name, and a data type. Once defined, the field appears on the corresponding API responses and webhook payloads under that object's metadata block.

Setting and Reading Metadata

After defining a field on a supported object type, set values on individual records via the resource's standard update endpoint. For example, to set order metadata:

{
    "metadata": {
        "external_order_id": "ext_abc123",
        "fulfillment_priority": "rush"
    }
}

The values come back in:

• The corresponding GET endpoint (GET /orders/{number}/)
• The relevant *.created and *.updated webhooks for that object

Field validation (data type, allowed values) is enforced based on the definitions you registered.

Cross-Rebill Correlation via Attribution

A common integration pattern is: store an external system's identifier on a customer's subscription once, and receive it inline on every charge event for the lifetime of that subscription — without follow-up API calls.

For example: a merchant integrating with an external plan-management service (subscription plans, healthcare plans, affiliate plans, etc.) wants the plan_id to travel with every rebill order and every capture transaction so their fulfillment service can correlate back to the external system.

The pattern: store the identifier on the subscription's marketing attribution metadata. Every renewal order created by that subscription inherits the same attribution record, so attribution.metadata flows through automatically.

Step 1 — Define an attribution metadata field

Create a metadata definition with object: attribution to register the field shape:

{
    "object": "attribution",
    "key": "plan_id",
    "name": "Plan ID",
    "type": "string"
}

Step 2 — Set the value on the subscription's attribution

Patch the subscription with attribution metadata:

{
    "attribution": {
        "metadata": {
            "plan_id": "plan_abc123"
        }
    }
}

Step 3 — Receive it inline on every charge event

The same attribution.metadata object is included in:

• subscription.updated payloads
• order.created payloads — including every renewal order, because rebill order placement reuses the subscription's attribution record
• transaction.created payloads — for both initial captures and rebill captures

{
    "event_type": "transaction.created",
    "data": {
        "type": "debit",
        "amount": "29.99",
        "subscription": {
            "id": 12345,
            "billing_cycle": 3
        },
        "attribution": {
            "metadata": {
                "plan_id": "plan_abc123"
            },
            "utm_source": "...",
            "utm_campaign": "..."
        }
    }
}

Set the value once when the subscription is created (or when the external system first issues an identifier), and your webhook receiver can read it back from data.attribution.metadata on every subsequent charge.

When to Use Which Surface

For data that doesn't fit any of these — for example, cart-level data or session-level data — you'll need to handle it in your application layer; those resources are not part of the public Metadata API surface.