Create

Create a new metered cost for a product.

POST /v0/costs

Create

cURL

curl --request POST \
  --url https://api.paygentic.io/v0/costs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "metered",
  "name": "<string>",
  "unitCost": 1,
  "currency": "<string>",
  "productId": "<string>",
  "eventType": "<string>",
  "unit": "<string>",
  "valueProperty": "<string>",
  "groupBy": {},
  "merchantId": "<string>"
}
'

201

{
  "id": "<string>",
  "object": "cost",
  "type": "metered",
  "name": "<string>",
  "currency": "<string>",
  "unitCost": "<string>",
  "productId": "<string>",
  "merchantId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "unit": "<string>",
  "aggregation": "SUM",
  "eventType": "<string>",
  "valueProperty": "<string>",
  "groupBy": {},
  "deletedAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

API key authentication

Body

application/json

type · enum<string> · required

The cost type. Only metered costs are supported; they track usage via events.

Available options: metered

name · string · required

Human-readable name for the cost.

unitCost · number · required

Cost per unit, multiplied by measured quantity to compute total cost. Must be non-negative.

Required range: x >= 0

currency · string · required

ISO 4217 currency code (e.g. USD, EUR).

productId · string · required

The product ID this cost belongs to.

Pattern: ^prod_[a-zA-Z0-9]+$

aggregation · enum<string> · required

Aggregation method for the metered event.

Available options: SUM, COUNT, AVG, MIN, MAX, UNIQUE_COUNT, LATEST

eventType · string · required

CloudEvents type that identifies the metered event.

unit · string

Unit label for metered costs (e.g. 'token', 'request'). Only valid for metered costs.

valueProperty · string

JSONPath to extract a numeric value from event data. Must start with $. (example: $.amount or $.payload.bytes). Required for SUM/AVG/MIN/MAX/LATEST aggregations.

Pattern: ^\$\.[a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)*$

groupBy · object

Map of dimension name to JSONPath for group-by queries. Each value must start with $. (example: $.region). Only valid for metered costs.

Show child attributes

merchantId · string

The merchant organization ID that owns this cost.

Pattern: ^org_[a-zA-Z0-9]+$

Response

201

application/json

Cost created successfully

id · string · required

Unique identifier for a cost

Pattern: ^cst_[a-zA-Z0-9]+$

object · enum<string> · default: cost · required

Available options: cost

type · enum<string> · required

Available options: metered

name · string · required

currency · string · required

unitCost · string · required

Decimal as string to avoid floating point precision loss.

productId · string · required

Unique identifier for a product

Pattern: ^prod_[a-zA-Z0-9]+$

merchantId · string · required

Unique identifier for an organization

Pattern: ^org_[a-zA-Z0-9]+$

createdAt · string<date-time> · required

updatedAt · string<date-time> · required

unit · string | null

aggregation · enum<string> | null

Available options: SUM, COUNT, AVG, MIN, MAX, UNIQUE_COUNT, LATEST

eventType · string | null

valueProperty · string | null

groupBy · object | null

Show child attributes

deletedAt · string<date-time> | null

Soft-delete timestamp. Always null for active costs returned by the API.