Maple enables ingestion of events to dynamically calculate customer usage-based metrics in just a few steps. Usage-based events can be triggered based on user activity or usage of a resource provided by your application.

Once you have covered the basics in Basic API Guide and have an API token ready to go, you can kickstart usage-based billing in Maple.

​
Setup a billable item

Billable items in Maple help track distinct entities for which you would like to track usage in your application. For example, this could be “API Calls”.

​
Setup a billable metric

The billable metric helps Maple determine what logic to apply when aggregating events on the billable item set up above. For example, a billable metric could be a “Count” of “API Calls” with some filtering on arbitrary properties you can send in such as type.

​
Setup pricing for the billable items and overall plan

You can set up a price for each metric type. For instance, in the following example, you can set up multiple prices based on the event type.

Once you have set up each individual prices based on event type, you can group them into a plan that is exposed to your customers.

The resulting API call plan will look as follows

​
Setup a customer and subscription for usage tracking

Send a POST request to the Customers endpoint with the following parameters.

curl --request POST \
   --url https://api.maplebilling.com/api/v1/companies/my_company_id/customers \
   --header 'accept: application/json' \
   --header 'authorization: Bearer my_token' \
   --header 'content-type: application/json' \
   --data '
{
"email": "[email protected]",
"name": "Hello Person",
"org_name": "Hello Co.",
"phone": "444-4444-4444",
"identifier": "your_customer_db_id"
}
'

Start a subscription for the customer based on the API Pricing Plan set up above

curl --request POST \
     --url https://api.maplebilling.com/api/v1/companies/my_company_id/subscriptions \
     --header 'accept: application/json' \
     --header 'authorization: Bearer my_token' \
     --header 'content-type: application/json' \
     --data '
{
    "auto_charges": true,
    "auto_renews": true,
    "product_pricing_ids": [
        "product_pricing_id_from_previous_step"
    ],
    "customer_id": "customer_id_from_previous_step",
    "term": {
        "count": 1,
        "frequency": "YEAR"
    },
    "config_items": [
        {
            "num_licenses": 1
        }
    ]
}
'

​
Start tracking dynamic usage with the events ingest endpoint

Once the customer and the subscription are set up, you can start tracking usage-events for different types of API calls as and when they happen in your application. Based on the metric we set up earlier, we would be counting API calls for each model type and charging them at a different rate.

The billable event takes in a unique customer identifier that maps back to your application along with properties for any metadata that will eventually be used for creating billable metrics. For example, you can use Maple to count the number of API calls made by your customer.

curl --request POST \
     --url https://api.maplebilling.com/api/v1/companies/company_id/events/ingest \
     --header 'authorization: Bearer my_token' \
     --header 'content-type: application/json' \
     --data '
{
  "events": [
    {
      "customer_id": "customer_id_from_previous_step",
      "customer_identifier": "your_customer_db_id",
      "transaction_id": "111-111-111",
      "timestamp": "2024-04-09T21:21:21+00:00",
      "item_id": "maple_api_calls_item_id",
      "properties": {
        "time_used": 10,
        "type": "model1"
      }
    }
  ]
}
'

The transaction_id serves as an idempotency key for your events. Any events with the same transaction_id received within a 24 hour window for a customer will not be counted multiple times. The item_id is the unique identifier for the billable item in Maple that these events are logged against. In the above example, the item_id refers to a billable item for API calls.

As events are sent to Maple, billable metrics are evaluated and leveraged towards billing the customer based on their subscription and pricing plan.

​
Review the customer’s usage on their next invoice in real-time

You can track live usage metrics on the customer’s next invoice from the customer’s subscription page.

​
Retrieving usage through the API

Total usage aggregation for the customer can be retrieved with the Get Subscription Usage API. The results of the call can be used to display the usage for each period for the customer in your application.

​
Viewing Billable Events in the UI

You can easily audit all your billable events and troubleshoot any issues with your usage-based billing plans by going Developers > Events to see all your billable events sent to Maple.

Clicking on an event will show you all the relevant event details.

You can filter the events for a given time period. You can also export the filtered results or export all events.