Class: Dodopayments::Resources::UsageEvents

Inherits:
Object
  • Object
show all
Defined in:
lib/dodopayments/resources/usage_events.rb

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ UsageEvents

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of UsageEvents.

Parameters:



188
189
190
 
# File 'lib/dodopayments/resources/usage_events.rb', line 188

def initialize(client:)
  @client = client
end

Instance Method Details

#ingest(events: , request_options: {}) ⇒ Dodopayments::Models::UsageEventIngestResponse

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"
    }
  }
]

} “‘

Parameters:

Returns:

See Also:



174
175
176
177
178
179
180
181
182
183
 
# File 'lib/dodopayments/resources/usage_events.rb', line 174

def ingest(params)
  parsed, options = Dodopayments::UsageEventIngestParams.dump_request(params)
  @client.request(
    method: :post,
    path: "events/ingest",
    body: parsed,
    model: Dodopayments::Models::UsageEventIngestResponse,
    options: options
  )
end

#list(customer_id: nil, end_: nil, event_name: nil, meter_id: nil, page_number: nil, page_size: nil, start: nil, request_options: {}) ⇒ Dodopayments::Internal::DefaultPageNumberPagination<Dodopayments::Models::Event>

Some parameter documentations has been truncated, see Models::UsageEventListParams for more details.

Fetch events from your account with powerful filtering capabilities. This endpoint is ideal for:

  • Debugging event ingestion issues

  • Analyzing customer usage patterns

  • Building custom analytics dashboards

  • Auditing billing-related events

## Filtering Options:

  • **Customer filtering**: Filter by specific customer ID

  • **Event name filtering**: Filter by event type/name

  • **Meter-based filtering**: Use a meter ID to apply the meter’s event name and filter criteria automatically

  • **Time range filtering**: Filter events within a specific date range

  • Pagination: Navigate through large result sets

## Meter Integration:

When using ‘meter_id`, the endpoint automatically applies:

  • The meter’s configured ‘event_name` filter

  • The meter’s custom filter criteria (if any)

  • If you also provide ‘event_name`, it must match the meter’s event name

## Example Queries:

  • Get all events for a customer: ‘?customer_id=cus_abc123`

  • Get API request events: ‘?event_name=api_request`

  • Get events from last 24 hours: ‘?start=2024-01-14T10:30:00Z&end=2024-01-15T10:30:00Z`

  • Get events with meter filtering: ‘?meter_id=mtr_xyz789`

  • Paginate results: ‘?page_size=50&page_number=2`

Parameters:

  • customer_id (String) —

    Filter events by customer ID

  • end_ (Time) —

    Filter events created before this timestamp

  • event_name (String) —

    Filter events by event name. If both event_name and meter_id are provided, they

  • meter_id (String) —

    Filter events by meter ID. When provided, only events that match the meter’s eve

  • page_number (Integer) —

    Page number (0-based, default: 0)

  • page_size (Integer) —

    Number of events to return per page (default: 10)

  • start (Time) —

    Filter events created after this timestamp

  • request_options (Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/dodopayments/resources/usage_events.rb', line 114

def list(params = {})
  parsed, options = Dodopayments::UsageEventListParams.dump_request(params)
  @client.request(
    method: :get,
    path: "events",
    query: parsed.transform_keys(end_: "end"),
    page: Dodopayments::Internal::DefaultPageNumberPagination,
    model: Dodopayments::Event,
    options: options
  )
end

#retrieve(event_id, request_options: {}) ⇒ Dodopayments::Models::Event

Some parameter documentations has been truncated, see Models::UsageEventRetrieveParams for more details.

Fetch detailed information about a single event using its unique event ID. This endpoint is useful for:

  • Debugging specific event ingestion issues

  • Retrieving event details for customer support

  • Validating that events were processed correctly

  • Getting the complete metadata for an event

## Event ID Format:

The event ID should be the same value that was provided during event ingestion via the ‘/events/ingest` endpoint. Event IDs are case-sensitive and must match exactly.

## Response Details:

The response includes all event data including:

  • Complete metadata key-value pairs

  • Original timestamp (preserved from ingestion)

  • Customer and business association

  • Event name and processing information

## Example Usage:

“‘text GET /events/api_call_12345 “`

Parameters:

  • event_id (String) —

    Unique event identifier (case-sensitive, must match the ID used during ingestion

  • request_options (Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



47
48
49
50
51
52
53
54
 
# File 'lib/dodopayments/resources/usage_events.rb', line 47

def retrieve(event_id, params = {})
  @client.request(
    method: :get,
    path: ["events/%1$s", event_id],
    model: Dodopayments::Event,
    options: params[:request_options]
  )
end