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>",
  "idempotencyKey": "<string>",
  "merchantId": "<string>",
  "properties": [
    {
      "billableMetricId": "<string>",
      "quantity": 123,
      "price": "<string>"
    }
  ],
  "timestamp": "2023-11-07T05:31:56Z",
  "entitlementId": "<string>",
  "metadata": {}
}
'
{
  "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. This object is populated by the server and returned in GET and PATCH responses. It cannot be set directly in request bodies.

​
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[]
​
refund
object

Refund information for the usage event when it has been refunded. This object is populated by the server and returned in GET and PATCH responses. It cannot be set directly in request bodies.

​
subscriptionId
string
​
timestamp
string<date-time>