Event Ingestion

Ingest events from your application

Events are the core of Usage Based Billing. They represent some usage done by a customer in your application. Typical examples of events are:

• A customer consumed AI LLM tokens
• A customer streamed minutes of video
• A customer uploaded a file to your application

Events are sent to Polar using the Events Ingestion API and are stored in our database. An event consists of the following fields:

• A name, which is a string that can be used to identify the type of event. For example, ai_usage, video_streamed or file_uploaded.
• A customer_id or external_customer_id, which is Polar’s customer ID or your user’s ID. This is used to identify the customer that triggered the event.
• A metadata object, which is a JSON object that can contain any additional information about the event. This is useful for storing information that can be used to filter the events or compute the actual usage. For example, you can store the duration of the video streamed or the size of the file uploaded.

Here is an example of an event:

{
  "name": "ai_usage",
  "external_customer_id": "cus_123",
  "metadata": {
    "model": "gpt-4.1-nano",
    "requests": 1,
    "total_tokens": 77,
    "request_tokens": 58,
    "response_tokens": 19
  }
}

Ingest events using the Polar SDK

To ingest events, you can use the Polar SDKs.

TypeScript Example

import { Polar } from "@polar-sh/sdk";

const polar = new Polar({
  accessToken: process.env["POLAR_ACCESS_TOKEN"] ?? "",
});

await polar.events.ingest({
  events: [
    {
      name: "<value>",
      externalCustomerId: "<id>",
      metadata: {
        key: "value",
      },
    },
  ],
});

You are always responsible for checking the balance of your customers’ Usage Meter. As events always are ingested, we will never prohibit any customer’s action based on their Usage Meter balance.

Ingestion Strategies

To make it easier to ingest events, we have created a set of ingestion strategies for common event sources.

Learn more about our Ingestion Strategies.

Good to know

Events are immutable

Once an event is ingested, it cannot be changed, nor can it be deleted.