Core Concepts

Metadata

Attach your own key/value pairs to any LuniPay resource — use it to store internal IDs, tags, customer context, or any structured information you want to retrieve later.

Every mutable LuniPay resource — customers, invoices, payments, payment links, checkout sessions, and events — carries a metadata object. LuniPay never interprets the contents; metadata is purely for your bookkeeping.

Limits

Up to 20 keys per object.
Keys are strings, max 40 characters.
Values are strings, max 500 characters.
Keys must be unique within a single metadata object.

Do not store secrets

Metadata is visible in the dashboard, webhook payloads, and event history. Never put API keys, passwords, credit card numbers, or anything else that should stay private.

Setting metadata

Pass a metadata object on any create or update request:

curl https://lunipay.io/api/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "usd",
    "success_url": "https://example.com/thanks",
    "metadata": {
      "order_id": "ORD-9821",
      "channel": "web",
      "referrer": "promo-email-april"
    }
  }'

Updating metadata

PATCH requests merge the metadata you send with what is already on the object. To delete a key, pass it with a value of null:

curl -X PATCH https://lunipay.io/api/v1/customers/cus_01JRZK... \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "internal_id": "ACCT-42",
      "old_tag": null
    }
  }'

Metadata in webhooks

Metadata round-trips through webhooks. Every event payload contains the full snapshot of the resource at the time the event fired, including whatever metadata you set. That makes it ideal for correlating LuniPay activity to your own records without an extra API call.

{
  "id": "evt_01JRZKD1KMN8RZJX4QV5W7YEFH",
  "object": "event",
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "cs_01JRZK...",
      "status": "COMPLETE",
      "metadata": {
        "order_id": "ORD-9821",
        "channel": "web"
      }
    }
  }
}

Common patterns

Foreign keys: store your own user id, order id, or subscription id so you can bridge LuniPay state to your database without a lookup table.
Attribution: tag payments with the marketing campaign, referrer, or acquisition channel.
A/B tests: record which variant of your checkout flow a given session came from.
Audit trails: stamp the employee who issued a refund, or the automation that created an invoice.