Skip to main content

Documentation Index

Fetch the complete documentation index at: https://getlago.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

In this article, you will learn how to build a ‘pay-as-you-go’ billing system. This template is suitable for companies whose pricing fully depends on usage, such as cloud service providers and API companies, that only charge their customers for the resources they consume.

​
Pricing structure

For one of its products, Algolia Search, the platform offers its customers to subscribe for free and only pay based on usage.
ModelSearch API
Monthly price$1.50 / 1,000 requests
Free usage (each month)10,000 requests
Although users don’t need to subscribe to access the platform, Algolia offers its customers discounts based on volume and commitment (rates available upon request).

​
Get started

1

Set up Lago

LAGO_URL="https://api.getlago.com"
API_KEY="__API_KEY__"
2

Create billable metrics

Create billable metrics to track request usage for Search and Recommend APIs.
  1. Set the aggregation_type to sum_agg to sum all request volumes
  2. Set the field_name to search_requests_volume for Search API tracking
  3. Set the recurring to false for metered billing
curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
  --header 'Authorization: Bearer __API_KEY__' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "billable_metric": {
      "name": "Search API Requests",
      "code": "__BILLABLE_METRIC_CODE__",
      "description": "Search API request volume",
      "aggregation_type": "sum_agg",
      "field_name": "search_requests_volume",
      "recurring": false
    }
  }'
3

Create a plan

Create a plan to price packages of requests used.
  1. Set the amount_cents to 0 since there is no subscription fee
  2. Set the charges to use package pricing model with Algolia’s rates
  3. Configure free_units of 10,000 requests per month included
curl --location --request POST "$LAGO_URL/api/v1/plans" \
  --header 'Authorization: Bearer __API_KEY__' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "plan": {
      "name": "Algolia Search",
      "code": "__PLAN_CODE__",
      "interval": "monthly",
      "description": "Pay-as-you-go pricing for Algolia Search API",
      "amount_cents": 0,
      "amount_currency": "USD",
      "pay_in_advance": false,
      "charges": [
        {
          "billable_metric_id": "__BILLABLE_METRIC_ID__",
          "charge_model": "package",
          "properties": {
            "amount": "1.50",
            "free_units": 10000,
            "package_size": 1000
          }
        }
      ]
    }
  }'
Refer to the API reference and guide on package charges to learn more.
4

Create a customer

Create a customer with a unique external_id.
curl --location --request POST "$LAGO_URL/api/v1/customers" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "customer": {
      "external_id": "__EXTERNAL_CUSTOMER_ID__",
      "name": "Acme Inc",
      "email": "john@acme.com",
      "currency": "USD",
      "timezone": "America/New_York"
    }
  }'
Refer to the API reference to create a customer.
5

Create a subscription

Create a subscription for the customer with the plan’s code.
curl --location --request POST "$LAGO_URL/api/v1/subscriptions" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "subscription": {
      "external_customer_id": "__EXTERNAL_CUSTOMER_ID__",
      "plan_code": "__PLAN_CODE__",
      "external_id": "__EXTERNAL_SUBSCRIPTION_ID__"
    }
  }'
Refer to the API reference to create a subscription.
6

Ingest usage via events

Send usage events to Lago to track API requests.
  1. Set the code to match your billable metric code
  2. Include search_requests_volume property with the number of requests
curl --location --request POST "$LAGO_URL/api/v1/events" \
  --header 'Authorization: Bearer __API_KEY__' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "event": {
      "transaction_id": "__TRANSACTION_ID__",
      "code": "__BILLABLE_METRIC_CODE__",
      "external_subscription_id": "__EXTERNAL_SUBSCRIPTION_ID__",
      "properties": {
        "search_requests_volume": 5000
      }
    }
  }'
Refer to the API reference to create an event.
7

Monitor current usage

Track real-time customer usage for the current billing period.
curl --location --request GET "$LAGO_URL/api/v1/customers/__EXTERNAL_CUSTOMER_ID__/current_usage?external_subscription_id=__EXTERNAL_SUBSCRIPTION_ID__" \
--header 'Authorization: Bearer __API_KEY__' \
--header 'Content-Type: application/json'
Refer to the API reference to get the current usage.

​
Wrap-up

‘Pay-as-you-go’ pricing strategies are popular among API companies like Algolia. With Lago, you can adapt this template to your products and services, using some of our most popular features:
  1. Plan models, with or without subscription;‍
  2. Billable metrics, including the ‘sum’ aggregation type; and‍
  3. Charges, including our package and graduated pricing models.
Give it a try, click here to get started!