Metadata

What Is Metadata?

The field name is metadatas (with an "s"). A common mistake is to use metadata — this will result in your metadata not being stored. Always use metadatas in your API requests.

Metadata lets you store custom key-value data on Inflow resources. This is useful for:

Linking payments to your internal order IDs
Storing customer references
Tracking marketing attribution
Any custom data your application needs

Metadata is stored as JSON and returned in API responses and webhook payloads.

Where Metadata Is Supported

Resource	Create	Read	Webhook
Payments	Yes	Yes	Yes
Subscriptions	Yes	Yes	Yes
Subscription Offers	Yes	Yes	--

Setting Metadata

On Payment Creation

curl -X POST https://api.inflowpay.xyz/api/checkout/payment \
  -H "X-Inflow-Api-Key: inflow_priv_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [{ "name": "Product", "price": 4999, "quantity": 1 }],
    "currency": "EUR",
    "customerEmail": "[email protected]",
    "metadatas": {
      "orderId": "order_12345",
      "source": "website",
      "customerId": "cust_abc"
    }
  }'

On Subscription Initiation

curl -X POST https://api.inflowpay.xyz/subscription/offer/{offerId}/initiate \
  -H "X-Inflow-Api-Key: inflow_priv_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customerEmail": "[email protected]",
    "metadatas": {
      "planType": "pro",
      "referralCode": "REF_2025"
    }
  }'

Reading Metadata

Metadata is included in API responses:

{
  "id": "pay_abc123",
  "status": "PAYMENT_SUCCESS",
  "metadatas": {
    "orderId": "order_12345",
    "source": "website",
    "customerId": "cust_abc"
  }
}

And in webhook payloads:

{
  "data": [
    {
      "eventType": "payment_status_updated",
      "payload": {
        "id": "pay_abc123",
        "status": "PAYMENT_SUCCESS",
        "metadatas": {
          "orderId": "order_12345"
        }
      }
    }
  ]
}

Accepted Types

Endpoint	Accepted Value Types
Checkout payment (`POST /api/checkout/payment`)	string, number, boolean, null, nested objects, arrays
Server payment (`POST /api/server/payment`)	string, number, boolean (flat key-value only)

Checkout Payment Example

{
  "orderId": "order_12345",
  "amount": 49.99,
  "isPremium": true,
  "customer": {
    "id": "cust_abc",
    "tier": "gold"
  }
}

Server Payment Example

{
  "orderId": "order_12345",
  "amount": 49.99,
  "isPremium": true
}

Best Practices

Use metadata to link Inflow resources to your internal systems.
Keep keys descriptive and consistent across your integration.
Avoid storing sensitive information (PII, passwords, credentials) in metadata.
Use metadata in combination with webhooks to reconcile payments with your backend.