Skip to main content

​
Overview

Every major API object (PaymentIntents, Customers, Refunds) supports a metadata field. Metadata is a set of key-value string pairs that you can use to store additional information relevant to your application. The API does not use metadata internally — it exists purely for your own record-keeping.

​
Constraints

PropertyLimit
Maximum keys per object50
Key maximum length40 characters
Value maximum length500 characters
Key and value typesStrings only

​
Setting metadata on creation

Pass a metadata object when creating a resource: 
curl -X POST https://api.leanrails.com/v1/payment_intents \
  -u "$API_KEY:" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 2000,
    "currency": "usd",
    "payment_method": "pm_card_visa",
    "metadata": {
      "order_id": "order_9876",
      "fulfillment_type": "digital",
      "internal_ref": "INV-2026-0042"
    }
  }'
Response: 
{
  "id": "pi_1abc123def456",
  "object": "payment_intent",
  "amount": 2000,
  "currency": "usd",
  "status": "requires_confirmation",
  "metadata": {
    "order_id": "order_9876",
    "fulfillment_type": "digital",
    "internal_ref": "INV-2026-0042"
  },
  ...
}

​
Updating metadata

When updating metadata, the provided keys are merged with existing metadata. Keys not included in the update are left unchanged. 
curl -X PATCH https://api.leanrails.com/v1/payment_intents/pi_1abc123def456 \
  -u "$API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "fulfillment_type": "physical",
      "tracking_number": "1Z999AA10123456784"
    }
  }'
Result: The metadata now contains all four keys: 
{
  "metadata": {
    "order_id": "order_9876",
    "fulfillment_type": "physical",
    "internal_ref": "INV-2026-0042",
    "tracking_number": "1Z999AA10123456784"
  }
}

​
Deleting a metadata key

To remove a specific key, set its value to an empty string "": 
curl -X PATCH https://api.leanrails.com/v1/payment_intents/pi_1abc123def456 \
  -u "$API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "internal_ref": ""
    }
  }'
Result: The internal_ref key is removed: 
{
  "metadata": {
    "order_id": "order_9876",
    "fulfillment_type": "physical",
    "tracking_number": "1Z999AA10123456784"
  }
}

​
Clearing all metadata

To remove all metadata keys at once, pass an empty object: 
curl -X PATCH https://api.leanrails.com/v1/payment_intents/pi_1abc123def456 \
  -u "$API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {}
  }'

​
Common use cases

  • Linking to external systems: Store your internal order ID, CRM record ID, or ERP reference.
  • Categorization: Tag payments by department, product line, or campaign.
  • Audit trail: Record who initiated the payment or which system triggered it.
Do not store sensitive information (PII, card numbers, passwords) in metadata. Metadata is visible to anyone with access to your API keys and dashboard.