# Ingest a usage event

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


This endpoint ingests a usage event into Chargebee.

**See also**

-   [Limits for Usage-based Billing in Chargebee](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/understanding-usages#usage-based-billing-limits)

## Sample Request

#### cURL

```bash
curl  https://{site}.ingest.chargebee.com/api/v2/usage_events \
     -u {site_api_key}:\
     --header 'Content-Type: application/json;charset=UTF-8' \
     --data '{
     "deduplication_id": "usage-6315161283",
     "subscription_id": "S-300000001",
     "usage_timestamp": "1737612931000",
     "properties": {
          "input_tokens": 1200,
          "output_tokens": 7200,
          "token_ratio": 6,
          "model_name": "gpt-4",
          "prompt_type": "text_completion",
          "temperature": 0.8,
          "top_p": 0.9,
          "frequency_penalty": 0.2,
          "presence_penalty": 0.1,
          "fine_tuned": false,
          "response_time_ms": 150,
          "completion_success_rate_percent": 98.6,
          "api_endpoints": "generateCompletion",
          "cpu_usage_percent": 68,
          "memory_usage_mb": 2100,
          "webhook_events_sent": 42
     }
}'
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;
using System.Collections.Generic;

ApiConfig.Configure("{site}","{site_api_key}");
var properties = new Dictionary<string, object>();
properties.Add("input_tokens", 1200);
properties.Add("output_tokens", 7200);
properties.Add("token_ratio", 6);
properties.Add("model_name", "gpt-4");
properties.Add("prompt_type", "text_completion");
properties.Add("temperature", 0.8);
properties.Add("top_p", 0.9);
properties.Add("frequency_penalty", 0.2);
properties.Add("presence_penalty", 0.1);
properties.Add("fine_tuned", false);
properties.Add("response_time_ms", 150);
properties.Add("completion_success_rate_percent", 98.6);
properties.Add("api_endpoints", "generateCompletion");
properties.Add("cpu_usage_percent", 68);
properties.Add("memory_usage_mb", 2100);
properties.Add("webhook_events_sent", 42);
EntityResult result = UsageEvent.Create()
		.DeduplicationId("usage-6315161283")
		.SubscriptionId("S-300000001")
		.UsageTimestamp(1737612931000)
		.Properties(properties)
		.Request();

UsageEvent usageEvent = result.UsageEvent;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    usageeventAction "github.com/chargebee/chargebee-go/v3/actions/usageevent"
    "github.com/chargebee/chargebee-go/v3/models/usageevent"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := usageeventAction.Create(&usageevent.CreateRequestParams{
        DeduplicationId : "usage-6315161283",
        SubscriptionId : "S-300000001",
        UsageTimestamp : chargebee.Int64(1737612931000),
        Properties : map[string]interface{}{
            "input_tokens" : 1200,
            "output_tokens" : 7200,
            "token_ratio" : 6,
            "model_name" : "gpt-4",
            "prompt_type" : "text_completion",
            "temperature" : 0.8,
            "top_p" : 0.9,
            "frequency_penalty" : 0.2,
            "presence_penalty" : 0.1,
            "fine_tuned" : false,
            "response_time_ms" : 150,
            "completion_success_rate_percent" : 98.6,
            "api_endpoints" : "generateCompletion",
            "cpu_usage_percent" : 68,
            "memory_usage_mb" : 2100,
            "webhook_events_sent" : 42,
        },
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        UsageEvent := res.UsageEvent
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.UsageEventCreateRequest{
    DeduplicationId : "usage-6315161283",
    SubscriptionId : "S-300000001",
    UsageTimestamp : chargebee.Int64(1737612931000),
    Properties : map[string]interface{}{
        "input_tokens" : 1200,
        "output_tokens" : 7200,
        "token_ratio" : 6,
        "model_name" : "gpt-4",
        "prompt_type" : "text_completion",
        "temperature" : 0.8,
        "top_p" : 0.9,
        "frequency_penalty" : 0.2,
        "presence_penalty" : 0.1,
        "fine_tuned" : false,
        "response_time_ms" : 150,
        "completion_success_rate_percent" : 98.6,
        "api_endpoints" : "generateCompletion",
        "cpu_usage_percent" : 68,
        "memory_usage_mb" : 2100,
        "webhook_events_sent" : 42,
    },
}
  res, err := client.UsageEvent.Create(req)
      if err != nil {
        fmt.Println(err)
    } else {
        UsageEvent := res.UsageEvent
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        Result result = UsageEvent.create()
            .deduplicationId("usage-6315161283")
            .subscriptionId("S-300000001")
            .usageTimestamp(1737612931000L)
            .properties(new java.util.HashMap<String, Object>() {{ put("input_tokens", 1200); put("output_tokens", 7200); put("token_ratio", 6); put("model_name", "gpt-4"); put("prompt_type", "text_completion"); put("temperature", 0.8); put("top_p", 0.9); put("frequency_penalty", 0.2); put("presence_penalty", 0.1); put("fine_tuned", false); put("response_time_ms", 150); put("completion_success_rate_percent", 98.6); put("api_endpoints", "generateCompletion"); put("cpu_usage_percent", 68); put("memory_usage_mb", 2100); put("webhook_events_sent", 42); }})
            .request();

        UsageEvent usageEvent = result.usageEvent();
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.usageEvent.UsageEvent;
import com.chargebee.v4.models.usageEvent.params.UsageEventCreateParams;
import com.chargebee.v4.models.usageEvent.responses.UsageEventCreateResponse;
import java.util.List;
import java.util.Map;

public class UsageEventCreate {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        UsageEventCreateParams params = UsageEventCreateParams.builder()
            .deduplicationId("usage-6315161283")
            .subscriptionId("S-300000001")
            .usageTimestamp(1737612931000L)
            .properties(Map.ofEntries(Map.entry("input_tokens", 1200), Map.entry("output_tokens", 7200), Map.entry("token_ratio", 6), Map.entry("model_name", "gpt-4"), Map.entry("prompt_type", "text_completion"), Map.entry("temperature", 0.8), Map.entry("top_p", 0.9), Map.entry("frequency_penalty", 0.2), Map.entry("presence_penalty", 0.1), Map.entry("fine_tuned", false), Map.entry("response_time_ms", 150), Map.entry("completion_success_rate_percent", 98.6), Map.entry("api_endpoints", "generateCompletion"), Map.entry("cpu_usage_percent", 68), Map.entry("memory_usage_mb", 2100), Map.entry("webhook_events_sent", 42)))
            .build();

        UsageEventCreateResponse response = client.usageEvents().create(params);

        UsageEvent usageEvent = response.getUsageEvent();
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.usageEvent.create({
        deduplication_id: "usage-6315161283",
        subscription_id: "S-300000001",
        usage_timestamp: 1737612931000,
        properties: {
            input_tokens: 1200,
            output_tokens: 7200,
            token_ratio: 6,
            model_name: "gpt-4",
            prompt_type: "text_completion",
            temperature: 0.8,
            top_p: 0.9,
            frequency_penalty: 0.2,
            presence_penalty: 0.1,
            fine_tuned: false,
            response_time_ms: 150,
            completion_success_rate_percent: 98.6,
            api_endpoints: "generateCompletion",
            cpu_usage_percent: 68,
            memory_usage_mb: 2100,
            webhook_events_sent: 42
        }
    });

    console.log(result);
    const usageEvent = result.usage_event;
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->usageEvent()->create([
    "deduplication_id" => "usage-6315161283",
    "subscription_id" => "S-300000001",
    "usage_timestamp" => 1737612931000,
    "properties" => '{"input_tokens":1200,"output_tokens":7200,"token_ratio":6,"model_name":"gpt-4","prompt_type":"text_completion","temperature":0.8,"top_p":0.9,"frequency_penalty":0.2,"presence_penalty":0.1,"fine_tuned":false,"response_time_ms":150,"completion_success_rate_percent":98.6,"api_endpoints":"generateCompletion","cpu_usage_percent":68,"memory_usage_mb":2100,"webhook_events_sent":42}'
]);
$usageEvent = $result->usage_event;
```

#### Python

```python
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.UsageEvent.create(
    cb_client.UsageEvent.CreateParams(
        deduplication_id="usage-6315161283",
        subscription_id="S-300000001",
        usage_timestamp=1737612931000,
        properties={
            "input_tokens": 1200,
            "output_tokens": 7200,
            "token_ratio": 6,
            "model_name": "gpt-4",
            "prompt_type": "text_completion",
            "temperature": 0.8,
            "top_p": 0.9,
            "frequency_penalty": 0.2,
            "presence_penalty": 0.1,
            "fine_tuned": False,
            "response_time_ms": 150,
            "completion_success_rate_percent": 98.6,
            "api_endpoints": "generateCompletion",
            "cpu_usage_percent": 68,
            "memory_usage_mb": 2100,
            "webhook_events_sent": 42
        }
    )
)
usage_event = response.usage_event
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

result = ChargeBee::UsageEvent.create({
  :deduplication_id => "usage-6315161283",
  :subscription_id => "S-300000001",
  :usage_timestamp => 1737612931000,
  :properties => {:input_tokens => 1200,:output_tokens => 7200,:token_ratio => 6,:model_name => "gpt-4",:prompt_type => "text_completion",:temperature => 0.8,:top_p => 0.9,:frequency_penalty => 0.2,:presence_penalty => 0.1,:fine_tuned => false,:response_time_ms => 150,:completion_success_rate_percent => 98.6,:api_endpoints => "generateCompletion",:cpu_usage_percent => 68,:memory_usage_mb => 2100,:webhook_events_sent => 42}
})

usage_event = result.usage_event
```

## Sample Response

```json
{
  "usage_timestamp": "179506024062",
  "subscription_id": "SUB-1",
  "deduplication_id": "usage-301513005",
  "properties": {
    "input_tokens": 1100,
    "output_tokens": 7400,
    "token_ratio": 6.73,
    "model_name": "gpt-3.5",
    "prompt_type": "code_completion",
    "temperature": 0.6,
    "top_p": 0.85,
    "frequency_penalty": 0.4,
    "presence_penalty": 0.15,
    "fine_tuned": false,
    "response_time_ms": 180,
    "completion_success_rate_percent": 99.1,
    "api_endpoints": "generateCompletion",
    "cpu_usage_percent": 65,
    "memory_usage_mb": 2200,
    "webhook_events_sent": 45
  }
}
```

## URL Format

**POST** https://[site].ingest.chargebee.com/api/v2/usage_events

## Input Parameters

- `deduplication_id` (required, string, max chars=36)
  An identifier used by the Chargebee's customer to distinguish between multiple events generated at the same timestamp for a single `subscription_id`.  
  The combination of `usage_timestamp`, `subscription_id`, and `deduplication_id` uniquely identifies each event.
  
  **Example**: If 3 events are generated for `subscription_id` = `sub-1` at `2025-04-01T00:00:00.000Z`, each event must have a distinct `deduplication_id`.

- `subscription_id` (required, string, max chars=50)
  The unique identifier of a subscription.
  
  **Note:**
  
  -   If an existing `subscription_id` is provided, usage data is recorded against it.
  -   If the subscription does not exist yet in Chargebee, a new `subscription_id` can be used, and the subscription can be imported later, once the usage is successfully recorded.
  -   During invoice generation, recorded usage linked to the `subscription_id` will be applied to the invoice.

- `usage_timestamp` (required, long)
  The timestamp indicating when this usage occurred, represented as [Epoch](https://en.wikipedia.org/wiki/Unix_time) time in **milliseconds** . Example: `1738732394123` represents the timestamp for February 5, 2025, at 05:13:14.123 UTC.
  
  **Note**: The timestamp must be within the last **12 hours** .

- `properties` (required, jsonobject)
  A schema-less field that accepts any JSON-formatted data to define the attributes of the ingested event. It is a requirement to structure the data in a flat format wherever possible for better compatibility with downstream processing. We strongly encourage using unique field names-particularly for fields intended for metering purposes. This approach enhances clarity and maintainability in the future. For example, a field named `status`,
  
  -   Can represent `string` values such as `accepted` or `processing` in one context.
      
  -   In another scenario, it might hold numeric values, such as HTTP response codes like `200`, `300`, or `400`.
      
  
  **Note**:
  
  -   Learn more about [field naming guidelines](/docs/api/usage_files).

## Returns

- `usage_event` (Usage event object)
  Resource object representing usage\_event