Skip to main content
POST
/
v1
/
events
Ingest Event
curl --request POST \
  --url https://api.example.com/v1/events \
  --header 'Content-Type: application/json' \
  --data '
{
  "event_name": "<string>",
  "external_customer_id": "<string>",
  "event_id": "<string>",
  "customer_id": "<string>",
  "timestamp": "<string>",
  "source": "<string>",
  "properties": {}
}
'
{
  "202": {},
  "400": {},
  "401": {},
  "500": {},
  "message": "<string>",
  "event_id": "<string>"
}
Use this endpoint when sending a single usage event from your application (e.g., one API call, one GB stored, or one transaction processed). Events are processed asynchronously and return immediately with a 202 status.

​
Use Cases

  • Track API requests or function calls
  • Record storage usage or data transfer
  • Log feature usage events
  • Monitor compute time or resource consumption
  • Capture transaction or message events

​
Request Body

​
event_name
string
required
Unique identifier for the type of event. Used for filtering and aggregation in meters.Examples: api_request, storage_gb, function_call, message_sent
​
external_customer_id
string
required
Your system’s unique identifier for the customer. This is the ID you use in your application, not FlexPrice’s internal ID.
​
event_id
string
Optional idempotency key. If provided, duplicate events with the same event_id will be ignored. If omitted, FlexPrice generates a unique ID.Recommended for ensuring exactly-once processing.
​
customer_id
string
FlexPrice’s internal customer ID. Optional if you’re using external_customer_id.
​
timestamp
string
ISO 8601 timestamp for when the event occurred. Defaults to current server time if omitted.Format: 2024-03-20T15:04:05Z
​
source
string
Optional identifier for the event source (e.g., api, mobile_app, webhook, batch_import).Useful for filtering and debugging event origins.
​
properties
object
Arbitrary key-value pairs containing additional event metadata. Values can be strings, numbers, or booleans.Examples:
  • {"request_size": 100, "response_status": 200}
  • {"region": "us-east-1", "instance_type": "t3.medium"}
  • {"user_tier": "premium", "api_version": "v2"}
Properties can be used in meters for:
  • Filtering (only count events where response_status = 200)
  • Aggregation (sum request_size values)
  • Grouping in analytics

​
Response

​
message
string
Confirmation message: "Event accepted for processing"
​
event_id
string
The event ID (either provided or generated). Use this for tracking and debugging.

​
Examples

curl -X POST https://us.api.flexprice.io/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "api_request",
    "external_customer_id": "customer_123",
    "event_id": "req_xyz789",
    "timestamp": "2024-03-20T15:04:05Z",
    "source": "api",
    "properties": {
      "endpoint": "/v1/users",
      "method": "GET",
      "response_status": 200,
      "response_time_ms": 45
    }
  }'

​
Response Codes

​
202
Accepted
Event accepted for processing. The event is queued and will be processed asynchronously.
​
400
Bad Request
Invalid request payload. Check that:
  • event_name and external_customer_id are provided
  • timestamp is in ISO 8601 format if provided
  • properties values are valid JSON types
​
401
Unauthorized
Missing or invalid API key.
​
500
Server Error
Internal server error. The event was not accepted.

​
Best Practices

  1. Use idempotency keys: Always provide event_id for critical events to prevent duplicate processing during retries.
  2. Batch when possible: If sending many events, use the batch endpoint for better performance.
  3. Include rich properties: Add relevant metadata to enable flexible filtering and aggregation in meters.
  4. Use consistent naming: Standardize your event_name values across your application (e.g., snake_case or kebab-case).
  5. Set accurate timestamps: Backfilling historical events requires accurate timestamps to ensure correct billing periods.