Metadata allows you to store custom key-value pairs on Charge API objects. Use metadata to persist information that’s not part of the core API schema.

​
How It Works

Metadata is a flexible object that accepts any key-value pairs. All metadata keys and values are stored as strings. 
{
  "metadata": {
    "color": "blue",
    "department": "fleet-ops",
    "location": "downtown",
    "priority": "high"
  }
}

​
Supported Objects

Metadata is available on these Charge API objects:
  • Accounts - Organization details, preferences
  • Fleets - Fleet-specific information, regions
  • Drivers - Driver preferences, notes, tags
  • Vehicles - Vehicle details, maintenance info
  • Charging Sessions - Session notes, purpose
  • Payment Methods - Payment preferences, notes
  • Invoices - Billing notes, cost centers
  • Webhook Endpoints - Integration details

​
Common Use Cases

​
Fleet Management

{
  "metadata": {
    "fleet_type": "delivery",
    "operating_hours": "24/7",
    "service_area": "metro",
    "fuel_card": "FC-12345"
  }
}

​
Driver Information

{
  "metadata": {
    "license_class": "CDL-A",
    "certifications": "hazmat,passenger",
    "preferred_shift": "night",
    "emergency_contact": "+1-555-0123"
  }
}

​
Vehicle Tracking

{
  "metadata": {
    "gps_device": "GT-789",
    "maintenance_due": "2024-03-15",
    "insurance_expiry": "2024-12-31",
    "last_inspection": "2024-01-15"
  }
}

​
Charging Session Notes

{
  "metadata": {
    "purpose": "route_optimization",
    "customer_id": "cust_456",
    "delivery_priority": "express",
    "notes": "Driver requested fast charging"
  }
}

​
Limits

  • Maximum keys: 50 per object
  • Key length: 40 characters maximum
  • Value length: 500 characters maximum
  • Total size: 20KB maximum

​
Searching and Filtering

​
List with Metadata Filter

# List vehicles with specific metadata
curl "https://api.chargeapi.co/v1/vehicles?metadata[fleet_id]=fleet_123" \
  -H "Authorization: Bearer ch_sk_test_..."
Sensitive Information
Don’t store sensitive data like passwords, API keys, or PII in metadata. Use secure storage for confidential information.