diff --git a/developer-resources/event-filtering-usage-based-billing.mdx b/developer-resources/event-filtering-usage-based-billing.mdx new file mode 100644 index 0000000..a92f837 --- /dev/null +++ b/developer-resources/event-filtering-usage-based-billing.mdx @@ -0,0 +1,187 @@ +--- +title: Advanced Event Filtering in Usage Based Billing. +description: This guide demonstrates how to implement advanced event filtering in Usage Based Billing. +icon: "credit-card" +--- + + +## Creating a Meter + +Meters define how your usage events are aggregated and measured for billing purposes. + +Before creating a meter, plan your usage tracking strategy: +- Identify what usage events you want to track +- Determine how events should be aggregated (count, sum, etc.) +- Define any filtering requirements for specific use cases + +### Step-by-Step Meter Creation + +Follow this comprehensive guide to set up your usage meter: + + + +Set up the fundamental details for your meter. + + +Choose a clear, descriptive name that identifies what this meter tracks. + +Examples: "Tokens", "API Calls", "Storage Usage", "Compute Hours" + + + +Provide a detailed explanation of what this meter measures. + +Example: "Counts each POST /v1/orders request made by the customer" + + + +Specify the event identifier that will trigger this meter. + +Examples: "token", "api.call", "storage.usage", "compute.session" + + + +The event name must match exactly what you send in your usage events. Event names are case-sensitive. + + + + +Define how the meter calculates usage from your events. + + +Select how events should be aggregated: + + + +Simply counts the number of events received. + +Use case: API calls, page views, file uploads + +Calculation: Total number of events + + + +Adds up values from a specific property in your events. + +Use case: Data transfer, storage consumption, processing time + +Calculation: Sum of all property values + + + + +Records the highest value of a specific property during the billing period. + +Use case: Peak concurrent users, maximum storage used, highest bandwidth + +Calculation: Maximum property value observed + + + +Uses the most recent value of a specific property. + +Use case: Current plan tier, latest configuration setting + +Calculation: Last recorded property value + + + + + +The property name from event metadata to aggregate over. + + +This field is required when using Sum, Max, or Last aggregation types. + + + + +Define the unit label for display purposes in reports and billing. + +Examples: "calls", "GB", "hours", "tokens" + + + + +Set up criteria to control which events are included in the meter. + + +**Enable Event Filtering** + +Toggle **Enable Event Filtering** to activate conditional event processing. + +**Choose Filter Logic** + +Select how multiple conditions are evaluated: + + + Event Filtering + + + + Filters in the image means any event with status code of `200` at `/v1/api` by the customer with `premium` plan under `14th` hour will be counted and else ignored. + + + + +All conditions must be true for an event to be counted. Use this when you need events to meet multiple strict criteria simultaneously. + +**Example:** Count API calls where `user_tier = "premium"` AND `endpoint = "/api/v2/users"` + + + +At least one condition must be true for an event to be counted. Use this when you want to include events that meet any of several criteria. + +**Example:** Count events where `method = "POST"` OR `method = "PUT"` OR `method = "DELETE"` + + + +**Setting Up Filter Conditions** + + + +Click **Add condition** to create a new filter rule. + + + +Specify the property name from your event metadata. + + + +Choose from available operators: +- `equals` - Exact match +- `not equals` - Exclusion filter +- `greater than` - Numeric comparison +- `greater than or equals` - Numeric comparison (inclusive) +- `less than` - Numeric comparison +- `less than or equals` - Numeric comparison (inclusive) +- `contains` - String contains substring +- `does not contain` - String exclusion filter + + + +Set the target value for comparison. + + + +Use **Add Group** to create additional condition groups for complex logic. + + + + + +Filtered properties must be included in your event metadata for the conditions to work properly. Events missing required properties will be excluded from counting. + + + + +Review your meter configuration and click on **Create Meter**. + + +Your meter is now ready to receive and aggregate usage events. + + + + + +This is how we can implement advanced events filtering in Usage Based Billing. \ No newline at end of file diff --git a/docs.json b/docs.json index 38b059c..31f9269 100644 --- a/docs.json +++ b/docs.json @@ -125,6 +125,7 @@ "pages": [ "developer-resources/checkout-session", "developer-resources/usage-based-billing-guide", + "developer-resources/event-filtering-usage-based-billing", "developer-resources/integration-guide", "developer-resources/subscription-integration-guide", "developer-resources/integration-tutorial", diff --git a/images/guides/advanced-event-filtering-ubb/event-filtering.png b/images/guides/advanced-event-filtering-ubb/event-filtering.png new file mode 100644 index 0000000..b1ef5c0 Binary files /dev/null and b/images/guides/advanced-event-filtering-ubb/event-filtering.png differ