LogoPlandalfDOCS

Documentation

Tracking Usage

You will learn the following:

  • Track usage events and apply fallback charges
  • Retrieve usage summaries and apply fallback charges
  • Track usage and apply fallback charges in your own backend

Before you start

Endpoint: Post Usage Events

This endpoint allows you to submit usage events for your customers.

HTTP Method

POST

URL

https://api.plandalf.com/v1/usage/events

Headers

  • Authorization: Bearer <API_KEY>
  • Content-Type: application/json or application/x-www-form-urlencoded

Request Body

The request body can be either JSON-encoded or form-encoded. It should contain either a single event object or an array of event objects.

Event Structure

FieldTypeOptionalDescription
eventstringNoThe type of event. In this case, it should be "FeatureUsageEvent".
idstringNoA unique identifier for the event (any format).
userstringNoThe user identifier associated with the event.
quantitynumberYesThe quantity of the event (default is 1).
customerstringNoThe customer identifier from your Billing Service Provider.
propertiesobjectYesAdditional properties related to the event.
timestampnumberYesThe Unix timestamp of when the event occurred.

Example Request

json
POST /v1/usage/events HTTP/1.1
Host: api.plandalf.com
Authorization: Bearer your_api_key_here
Content-Type: application/json

[
  {
    "event": "FeatureUsageEvent",
    "id": "6f8978aa-8676-11ef-b864-0242ac120002",
    "user": "6706dca2efcdee6a019840e5",
    "quantity": 1,
    "customer": "cust_oyN54LsjNtr9uC00",
    "properties": {
      "greeting": "hello"
    },
    "timestamp": 1728502852
  }
]

Response

The API response structure is not specified in the provided information. Typically, a successful response would include a status code (e.g., 200 OK) and potentially a JSON body with details about the processed events.

Usage Summary API

The Usage Summary endpoint allows you to retrieve a detailed report of usage and associated fees for a given customer within a specified date range. This endpoint is useful for tracking customer usage, calculating fees, and applying fallback charges if minimum thresholds are not met.

HTTP Method

GET

URL

text
https://api.plandalf.com/v1/customers/\{customer_id}/usage

Replace {customer_id} with the ID of the customer whose usage summary you wish to retrieve.

Headers

Authorization: Bearer <API_KEY>
Content-Type: application/json

Response Structure

The response will contain an object with the following fields:

FieldTypeDescription
period_start_atintegerThe start timestamp of the usage period in Unix format.
period_end_atintegerThe end timestamp of the usage period in Unix format.
amountintegerThe total charge amount for the period.
currencystringThe currency of the charge (e.g., USD, AUD).
feesarrayAn array of fee details applied to the usage, each with charge and metric information.
FieldTypeDescription
amountstringThe amount charged for the usage.
descriptionstringA description of the fee.
chargeobjectDetails about the associated charge, including name, type, and currency.
metricobjectDetails about the metric used, such as event name, aggregation type, and metric type.

Example Resposne

json
{
  "period_start_at": 1728502852,
  "period_end_at": 1728502852,
  "amount": 500,
  "currency": "USD",
  "fees": [
    {
      "amount": "500",
      "description": null,
      "usage": 123,
      "charge": {
        "name": "fallback charge",
        "invoicing_interval": null,
        "currency": "AUD",
        "type": "standard",
        "amount_minimum_spend": "500",
        "minimum_billable_usage": null,
        "amount": "5",
        "mode": "in_arrears"
      },
      "metric": {
        "id": "metric_1CH9XvWgnP4kjdfQvQSLGY",
        "event_name": "fallback_video_sent",
        "aggregation": "COUNT",
        "type": "persistent"
      }
    }
  ]
}

Error Handling

Error responses are not specified in the provided information. Common HTTP status codes for errors might include:

  • 400 Bad Request: Invalid input
  • 401 Unauthorized: Invalid or missing API key
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server-side issues

For more detailed information about error responses, please refer to the full API documentation or contact the API provider.