Skip to main content
POST
/
v0
/
costs
Create
curl --request POST \
  --url https://api.paygentic.io/v0/costs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "unitCost": 1,
  "currency": "<string>",
  "productId": "<string>",
  "eventType": "<string>",
  "unit": "<string>",
  "valueProperty": "<string>",
  "groupBy": {},
  "merchantId": "<string>"
}
'
{
  "id": "<string>",
  "object": "cost",
  "name": "<string>",
  "currency": "<string>",
  "unitCost": "<string>",
  "productId": "<string>",
  "merchantId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "unit": "<string>",
  "eventType": "<string>",
  "valueProperty": "<string>",
  "groupBy": {},
  "deletedAt": "2023-11-07T05:31:56Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
merchantId
string

The merchant organization ID that owns this cost.

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

Response

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
​
deletedAt
string<date-time> | null

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