Usage events

Usage events track how merchants interact with your app. They provide the foundation for understanding customer behavior, supporting usage-based billing, and powering feature entitlements. This guide covers the essentials of implementing usage events in your Shopify app.

What to track

Consider tracking these common types of events:

Merchant behavioral events

Feature activations (e.g., when a specific tool is used)
Workflow completions (e.g., bulk edit completed)
Resource interactions (e.g., product created, order processed)
Interface engagements (e.g., dashboard viewed)

Billable events

Metered resource consumption (e.g., API calls, storage used)
Business transactions (e.g., orders processed, emails sent)
Premium feature access (e.g., advanced reporting generated)

Implementation options

Mantle offers multiple ways to send usage events:

Using MantleClient

const mantleClient = new MantleClient({
  appId: process.env.MANTLE_APP_ID,
  customerApiToken: customerApiToken // from identify step
});

// Send a single event
await mantleClient.sendUsageEvent({
  eventName: 'order_processed',
  properties: {
    orderId: '123',
    amount: 99.99,
    items: 5
  }
});

Direct API request

await fetch('https://appapi.heymantle.com/v1/usage_events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Mantle-App-Id': process.env.MANTLE_APP_ID,
    'X-Mantle-Customer-Api-Token': customerApiToken
  },
  body: JSON.stringify({
    eventName: 'order_processed',
    properties: {
      orderId: '123',
      amount: 99.99,
      items: 5
    }
  })
});

Batch sending

For efficiency, you can send multiple events in a single request:

await mantleClient.sendUsageEvents({
  events: [
    {
      eventName: 'order_processed',
      properties: { orderId: '123', amount: 99.99 }
    },
    {
      eventName: 'order_processed',
      properties: { orderId: '124', amount: 149.99 }
    }
  ]
});

flowchart LR 
 A --- B[fa:fa-spinner B] 
 B --> C[fa:fa-check C] 
 B --> D[fa:fa-ban D]

Best practices

Event naming

Use consistent naming conventions:

Use snake_case for event names (e.g., order_processed, product_created)
Be descriptive but concise
Consider prefixing related events (e.g., order_created, order_processed, order_fulfilled)

Properties structure

Include relevant details as properties:

Use simple types (strings, numbers, booleans) when possible
Include IDs for related objects for traceability
Consider including timestamps for time-sensitive events
Add context that might be useful for analysis

Implementation patterns

Integrate event tracking at key points:

After successful completion of important actions
When resource thresholds are reached or changed
During significant state changes in your application
At regular intervals for ongoing processes

Rate limiting

There is a rate limit of 1000 events per minute per unique event name for each customer. Exceeding this limit will return a 429 Rate limiting exceeded error.

Creating usage metrics

Once you're sending events, create metrics in Mantle to make them actionable:

Navigate to Usage metrics in your app's sidebar
Click Add Usage metric
Configure your metric:
- Select the event to track
- Choose an aggregation method (count, sum, unique)
- Set the time period (month-to-date, billing period)
- Name your metric clearly

Example metric configurations:

Total orders: Count of order_processed events
Revenue processed: Sum of amount property from order_processed events
Active users: Count of unique users with page_view events

Verifying your implementation

Confirm events are being tracked correctly:

Trigger test events from your application
Check the Usage events feed in Mantle
View customer profiles to see individual events
Monitor your usage metrics to ensure they're aggregating as expected

Next steps

Once your events are flowing:

For more details, see the Usage Events API Reference.