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 for the exact shape.

Setting metadata

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

$
curl https://api.fluveo.dev/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:

$
curl https://api.fluveo.dev/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.