Usage events and metrics

Want to know exactly how merchants use your app? Usage events track every meaningful interaction - from basic feature usage to complex workflows. Whether you’re charging based on usage or just want to understand customer behavior, usage events give you the insights you need to make better decisions.

What are usage events?

Think of usage events as your app’s diary - they record every significant action merchants take. This could be anything from processing an order to viewing a specific page. More than just tracking, usage events help you:

• Build usage-based pricing that reflects real value
• Understand how merchants actually use your features
• Spot opportunities for customer expansion
• Identify merchants who might need help
• Power automated workflows based on behavior

Getting started with usage events

You’ve got two ways to send usage events to Mantle - through our UI for testing or via our API for production. Let’s look at both:

Quick testing in the UI

Want to try things out? Head to Usage events → Trigger test event. This lets you:

• Send test events to specific customers
• Verify your event structure
• Experiment with different properties
• See how events appear in reports

Perfect for validating your event strategy before writing any code.

Production integration via API

Ready for real tracking? Use our Usage Events API to send events and our Usage Reports API to analyze them:

• Usage events API reference - Send events to track customer activity
• Usage reports API reference - Query usage data for specific customers

Making events more valuable

The properties field is your secret weapon for rich analytics:

1. Custom metrics
   • Track order values for percentage-based billing
   • Count items processed for volume pricing
   • Measure resource usage for tiered plans
2. Business context
   • Link events to specific orders or customers
   • Track feature-specific details
   • Add metadata for deeper analysis

Turning events into metrics

Individual events are interesting, but usage metrics make them actionable. Create metrics to:

• Count total events within a time window
• Sum specific property values (like order amounts)
• Track unique customer actions
• Measure feature adoption
• Power usage-based billing

Head to Usage metrics to create metrics like:

• “Total orders processed” (count of order_processed events)
• “Gross order value” (sum of order_amount property)
• “Active users” (unique customers with any event)

Setting up usage-based billing

Once you’ve got events flowing and metrics defined, you’re ready to build pricing around actual usage. Check out our complete guide to pricing setup for detailed instructions on configuring usage-based billing, including per-unit charges, percentage-based billing, and volume discounts.

Best practices

Here are some key tips for effective usage tracking:

1. Plan your strategy

   • Focus on key business actions
   • Include context for billing and analysis
   • Think about future pricing needs

2. Stay consistent

   • Use clear naming conventions
   • Keep property names consistent
   • Document your event structure

3. Monitor regularly

   • Check events are recording properly
   • Watch for missing or duplicate events
   • Verify billing calculations

Viewing your usage events

Once your events are flowing into Mantle, you can view them in two places:

1. Customer profile: View events for specific customers by going to Customers → Your Customer in the Mantle UI. This gives you a complete picture of how individual merchants interact with your app.
2. Usage metrics report: Get a broader view of usage patterns across your customer base in our Usage Metrics report. This helps you spot trends and understand how different customer segments engage with your features.

Remember: Good usage events tell the story of how customers find value in your app. Whether you’re using them for billing, analytics, or customer success, taking time to plan your event strategy pays off in better insights and more flexible billing options.

Need help planning your usage events or setting up usage-based billing? Our team is here to help you build an event strategy that drives growth.