> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fluveo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fluveo.com/_mcp/server.

# Metadata

Most core objects carry a `metadata` map — string keys to string values — for
your own bookkeeping: order numbers, internal customer ids, feature flags.
Fluveo stores it and returns it on reads and in webhook payloads, but never
interprets it or shows it to your customers.

Metadata is **writable** on Checkout Sessions, Customers, Payment Intents,
Payment Links, Refunds, and Webhook Endpoints, and is **returned** on those
plus Charges and Payment Methods. See each resource in the
[API Reference](/api-reference) for the exact shape.

## Setting metadata

Use bracket syntax in form-encoded bodies, one entry per key:

```bash
curl https://api.devfluveo.com/v1/payment_intents \
  -u sk_test_123: \
  -d amount=4242 \
  -d currency=usd \
  --data-urlencode 'metadata[order_id]=ord_9001' \
  --data-urlencode 'metadata[warehouse]=lisbon-01'
```

To change a value later, set the same key again on the update endpoint — the
new value overwrites the old one:

```bash
curl https://api.devfluveo.com/v1/payment_intents/pi_3Nk8AzB2xQRH9Jf \
  -u sk_test_123: \
  --data-urlencode 'metadata[warehouse]=porto-02'
```

## Rules

* **Keys and values are strings.** Serialize anything richer (JSON, numbers)
  yourself and parse it on the way out.
* **Keys prefixed `fluveo_` are reserved.** They are used internally and are
  never returned to you; choose your own prefix for namespacing instead.
* **Never store sensitive data in metadata.** No card numbers or security
  codes, no credentials, and no personal data beyond what your integration
  genuinely needs — metadata is returned on API reads and webhook deliveries,
  so treat it as broadly visible to your own systems.

Metadata is yours: it never affects how a payment is processed, routed, or
displayed on the hosted payment page.