Usage events

In addition to monthly/annual subscription fees, many Shopify partners and SaaS businesses often provide services to their customers using metered billing and/or usage charges.

Using Mantle Integrated, you will be able to offer usage-based billing in addition to the subscription fees you have attached to your plans.

Depending on the payment platform you’ll be using, ex. Shopify or Stripe, Mantle will provide an abstraction layer which take cares of boilerplate-heavy tasks such as:

  • Processing usage events in real-time.
  • Handling multiple types of events, ex. per order, per page view, etc.
  • The bundling of usage events into charges based on custom rules, ex. money-based thresholds or time-based thresholds.
  • Charge flat or percentage based amounts.
  • Determine minimum & maximum charges per month.

Sending usage events to Mantle

You can easily send app events to Mantle, either via Mantle’s UI or through the API.

Sending usage events using Mantle’s UI

To send app events to Mantle, you can utilize Mantle’s intuitive user interface:

  • Navigate to the Usage metrics section in the Mantle navigation bar.
  • Select Usage event explorer from the dropdown.
  • Click on Trigger test event.

From this point, you’ll have the ability to create a usage event tailored to a specific customer.

usage event

Sending usage events using Mantle’s API

Sending usage events to Mantle through the API is a breeze. All you need to do is make a POST request to Mantle’s usage_events endpoint.

Here are the key components you’ll need:

  • event_name: This can be any name you choose to associate with the usage event.
  • event_id: You can create your own event ID, or simply leave it blank, and Mantle will generate one for you.
  • properties: Add the specific details of the usage event here.

The properties parameter allows you to include additional data that can enhance the functionality and informativeness of your usage events:

  • Custom Metrics: Utilize properties to construct custom metrics in Mantle’s UI. For instance, if you’re charging a percentage of an order value, you can send events with properties: {"order_amount": 99.00}. Your usage metrics in Mantle can then be configured to sum(order_amount).

  • Additional Context: Even if you’re not using properties for custom metrics, it can serve as a repository for any extra information related to an event. This additional context can be helpful when viewing the data in the Mantle Event Explorer. For example, you might want to store the order ID to know to which order a particular event belongs.

By leveraging the properties parameter, you can make your usage events more detailed, providing either statistical insight or useful context.


Usage metrics

Once you’ve collected your usage events, you can harness their power by aggregating them through usage metrics. With usage metrics, you have the ability to group usage events together based on criteria like counting or summing the quantity of events.

You can also define the time window for this aggregation to suit your needs.

usage metric

Usage billing

Now that you’ve successfully sent usage events and set up metrics in Mantle, it’s time to monetize them by configuring your billing plans.

To get started, navigate to the Plans tab within Mantle. Here, you can enable Usage billing, which leverages your predefined usage metrics to calculate charges for merchants based on the thresholds you’ve defined.

usage billing

Once you have usage billing set up, your plan is fully equipped to charge your merchants based on their app usage.

All that’s left to do is consistently send the events to Mantle in accordance with how each merchant utilizes your app throughout their billing cycle.