Skip to main content
POST
/
v0
/
usage
Create
curl --request POST \
  --url https://api.paygentic.io/v0/usage \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customerId": "<string>",
  "entitlementId": "<string>",
  "idempotencyKey": "<string>",
  "merchantId": "<string>",
  "metadata": {},
  "properties": [
    {
      "billableMetricId": "<string>",
      "price": "<string>",
      "quantity": 123
    }
  ],
  "timestamp": "2023-11-07T05:31:56Z"
}'
{
  "id": "usg_f3g4h5i6j7k8l9m0",
  "object": "usageEvent",
  "billing": null,
  "consumerId": "org_v9w8x7y6z5a4b3c2",
  "createdAt": "2024-04-15T10:30:05Z",
  "customerId": "cus_n1o2p3q4r5s6t7u8",
  "description": "Claude language model text generation",
  "entitlementId": null,
  "idempotencyKey": "usg_2024_04_15_abc123",
  "merchantId": "org_v9w8x7y6z5a4b3c2",
  "metadata": {
    "input_tokens": "1500",
    "model_name": "claude-3-opus",
    "output_tokens": "800"
  },
  "properties": [
    {
      "billableMetricId": "bm_l5m6n7o8p9q0r1s2",
      "price": null,
      "quantity": 2500
    }
  ],
  "subscriptionId": "sub_d1e2f3g4h5i6j7k8",
  "timestamp": "2024-04-15T10:30:00Z"
}

Authorizations

​
Authorization
string
header
required

API key authentication

Body

application/json
​
customerId
string
required

Customer identifier that generated this consumption event. Sample values: 'cus_abc123xyz', 'cus_789def456'

​
idempotencyKey
string
required

Unique deduplication key preventing duplicate event processing. Sample values: 'usg_2024_01_15_abc123', 'event_wallet_xyz789', 'consumption_ref_456def'

​
merchantId
string
required

Merchant organization identifier owning this consumption event. Sample values: 'org_abc123xyz', 'org_789def456'

​
properties
object[]
required
​
timestamp
string<date-time>
required

Actual occurrence timestamp for the consumption event in ISO 8601 format. Sample values: '2024-01-15T10:30:00Z', '2024-02-01T14:45:30Z'. Represents when the event occurred, not when Paygentic received it.

​
entitlementId
string

Commitment identifier for this consumption event. Sample values: 'com_abc123xyz', 'com_789def456'

​
metadata
object

Custom key-value attributes providing context about the consumption event. Sample values: {"model_name": "claude-3-opus", "input_tokens": "1500", "output_tokens": "800"} or {"storage_tier": "premium", "data_center": "eu-west-1", "encryption": "enabled"} or {"image_resolution": "1024x1024", "generation_model": "stable-diffusion-xl"}

Response

Usage event created successfully

​
id
string

Unique identifier for a usage event

​
object
enum<string>
Available options:
usageEvent
​
billing
object

Billing information for the usage event when it has been billed.

​
consumerId
string
​
createdAt
string<date-time>
​
customerId
string
​
description
string

Readable summary explaining what triggered this consumption event. Sample values: 'Claude language model text generation', 'Customer data warehouse storage allocation', 'DALL-E image creation batch job', 'GPT-4 fine-tuning compute session', 'Vector database query operations'

​
entitlementId
string

Commitment identifier used for this consumption event. Sample values: 'com_abc123xyz', 'com_789def456'

​
idempotencyKey
string
​
merchantId
string
​
metadata
object
​
properties
object[]
​
subscriptionId
string
​
timestamp
string<date-time>