Usage Events

Usage events are how your application reports metered consumption to Prolifi. Events are aggregated per billing period to calculate usage-based charges on invoices.

Endpoints

Key concepts

• Event definitions: Before reporting events, configure usage event definitions in the Prolifi dashboard. The event_name in your API call must match an active definition.
• Properties: Attach custom key-value properties to events for segmentation and filtering (e.g., endpoint, model, region). If no properties are provided, a default count: 1 property is added.
• Batch reporting: For high-volume integrations, use the batch endpoint to send up to 1,000 events per request. Each event is processed independently — the response shows accepted and rejected counts.
• Idempotency: Include an idempotency_key on usage events to prevent double-counting during retries. This is separate from the Idempotency-Key header (which applies to the HTTP request level).
• Usage summaries: The customer usage endpoint returns aggregated counts grouped by event type, useful for dashboards and quota displays.