> ## Documentation Index > Fetch the complete documentation index at: https://dodopayments-mintlify-external-integration-datafast-autosen.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Ingest Events > Ingest events for usage-based billing. ## OpenAPI ````yaml post /events/ingest openapi: 3.1.0 info: title: public description: '' license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: 1.61.5 servers: - url: https://test.dodopayments.com/ description: Test Mode Server Host - url: https://live.dodopayments.com/ description: Live Mode Server Host security: [] tags: - name: Products - name: Payments - name: Subscriptions - name: Addons - name: Customers - name: Refunds - name: Disputes - name: Events - name: License Keys - name: Licenses - name: Discounts - name: Meters - name: Outgoing Webhooks - name: Checkout - name: Webhook Events paths: /events/ingest: post: tags: - Events summary: Ingest events for usage-based billing and analytics description: >- This endpoint allows you to ingest custom events that can be used for: - Usage-based billing and metering - Analytics and reporting - Customer behavior tracking ## Important Notes: - **Duplicate Prevention**: - Duplicate `event_id` values within the same request are rejected (entire request fails) - Subsequent requests with existing `event_id` values are ignored (idempotent behavior) - **Rate Limiting**: Maximum 1000 events per request - **Time Validation**: Events with timestamps older than 1 hour or more than 5 minutes in the future will be rejected - **Metadata Limits**: Maximum 50 key-value pairs per event, keys max 100 chars, values max 500 chars ## Example Usage: ```json { "events": [ { "event_id": "api_call_12345", "customer_id": "cus_abc123", "event_name": "api_request", "timestamp": "2024-01-15T10:30:00Z", "metadata": { "endpoint": "/api/v1/users", "method": "GET", "tokens_used": "150" } } ] } ``` operationId: ingest_events requestBody: content: application/json: schema: $ref: '#/components/schemas/IngestEventsRequest' required: true responses: '200': description: Events ingested successfully content: application/json: schema: $ref: '#/components/schemas/IngestEventsResponse' '400': description: >- Invalid request - validation errors, duplicate event IDs, or invalid timestamps '401': description: Unauthorized - invalid or missing API key '413': description: Payload too large - request exceeds maximum allowed size '422': description: Unprocessable entity - malformed JSON or schema validation errors '429': description: Too many requests - rate limit exceeded security: - API_KEY: [] x-codeSamples: - lang: JavaScript source: |- import DodoPayments from 'dodopayments'; const client = new DodoPayments({ bearerToken: 'My Bearer Token', }); const response = await client.usageEvents.ingest({ events: [{ customer_id: 'customer_id', event_id: 'event_id', event_name: 'event_name' }], }); console.log(response.ingested_count); - lang: Python source: |- from dodopayments import DodoPayments client = DodoPayments( bearer_token="My Bearer Token", ) response = client.usage_events.ingest( events=[{ "customer_id": "customer_id", "event_id": "event_id", "event_name": "event_name", }], ) print(response.ingested_count) - lang: Go source: | package main import ( "context" "fmt" "github.com/dodopayments/dodopayments-go" "github.com/dodopayments/dodopayments-go/option" ) func main() { client := dodopayments.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.UsageEvents.Ingest(context.TODO(), dodopayments.UsageEventIngestParams{ Events: dodopayments.F([]dodopayments.EventInputParam{dodopayments.EventInputParam{ CustomerID: dodopayments.F("customer_id"), EventID: dodopayments.F("event_id"), EventName: dodopayments.F("event_name"), }}), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.IngestedCount) } - lang: Java source: >- package com.dodopayments.api.example; import com.dodopayments.api.client.DodoPaymentsClient; import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient; import com.dodopayments.api.models.usageevents.EventInput; import com.dodopayments.api.models.usageevents.UsageEventIngestParams; import com.dodopayments.api.models.usageevents.UsageEventIngestResponse; public final class Main { private Main() {} public static void main(String[] args) { DodoPaymentsClient client = DodoPaymentsOkHttpClient.fromEnv(); UsageEventIngestParams params = UsageEventIngestParams.builder() .addEvent(EventInput.builder() .customerId("customer_id") .eventId("event_id") .eventName("event_name") .build()) .build(); UsageEventIngestResponse response = client.usageEvents().ingest(params); } } - lang: Kotlin source: >- package com.dodopayments.api.example import com.dodopayments.api.client.DodoPaymentsClient import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient import com.dodopayments.api.models.usageevents.EventInput import com.dodopayments.api.models.usageevents.UsageEventIngestParams import com.dodopayments.api.models.usageevents.UsageEventIngestResponse fun main() { val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv() val params: UsageEventIngestParams = UsageEventIngestParams.builder() .addEvent(EventInput.builder() .customerId("customer_id") .eventId("event_id") .eventName("event_name") .build()) .build() val response: UsageEventIngestResponse = client.usageEvents().ingest(params) } - lang: Ruby source: |- require "dodopayments" dodo_payments = Dodopayments::Client.new( bearer_token: "My Bearer Token", environment: "test_mode" # defaults to "live_mode" ) response = dodo_payments.usage_events.ingest( events: [{customer_id: "customer_id", event_id: "event_id", event_name: "event_name"}] ) puts(response) components: schemas: IngestEventsRequest: type: object required: - events properties: events: type: array items: $ref: '#/components/schemas/EventInput' description: List of events to be pushed maxItems: 1000 minItems: 1 IngestEventsResponse: type: object required: - ingested_count properties: ingested_count: type: integer minimum: 0 EventInput: type: object required: - event_id - customer_id - event_name properties: customer_id: type: string description: customer_id of the customer whose usage needs to be tracked event_id: type: string description: >- Event Id acts as an idempotency key. Any subsequent requests with the same event_id will be ignored event_name: type: string description: Name of the event metadata: oneOf: - type: 'null' - $ref: '#/components/schemas/EventMetadata' description: >- Custom metadata. Only key value pairs are accepted, objects or arrays submitted will be rejected. timestamp: type: - string - 'null' format: date-time description: >- Custom Timestamp. Defaults to current timestamp in UTC. Timestamps that are older that 1 hour or after 5 mins, from current timestamp, will be rejected. EventMetadata: type: object title: EventMetadata description: >- Arbitrary key-value metadata. Values can be string, integer, number, or boolean. additionalProperties: oneOf: - type: string title: String - type: integer title: Integer format: int64 - type: number title: Number format: double - type: boolean title: Boolean title: Event Metadata Value description: Metadata value can be a string, integer, number, or boolean securitySchemes: API_KEY: type: http scheme: bearer ````