Skip to main content
POST
/
billing
/
usage
cURL
curl --request POST \
  --url https://api.valyx.com/billing/usage \
  --header 'Content-Type: application/json' \
  --header 'X-Valyx-Signature: <x-valyx-signature>' \
  --data '
{
  "buyerId": "buyer_12345",
  "eventTimeStamp": 1755079200000,
  "tags": {
    "region": "US-East",
    "plan": "Enterprise",
    "feature": "premium_support"
  },
  "metrics": [
    {
      "usage_driver_id": "usage_driver_001",
      "quantity": 42.5,
      "count": 1
    }
  ],
  "usageReferenceId": "usage_ref_98765",
  "contractId": "contract_67890",
  "eventId": "event_abc123",
  "metadata": {
    "company_id": "3932",
    "recon_date": "2025-05-06 00:00:00",
    "company_name": "Reliance Europa Limited",
    "old_bag_status": "Returned"
  }
}
'
{
  "error": "<string>",
  "message": "<string>",
  "data": {
    "usagesAdded": [
      {
        "usageDriverId": "<string>",
        "usageDriverName": "<string>",
        "contractId": "<string>",
        "value": 123
      }
    ],
    "errors": [
      "<string>"
    ]
  }
}

Headers

​
X-Valyx-Signature
string
required

Auth key to authenticate the request

Body

application/json
​
buyerId
string
required

Unique identifier of the buyer associated with this usage event

Example:

"buyer_12345"

​
eventTimeStamp
integer
required

Unix timestamp in milliseconds representing when the usage occurred

Example:

1755079200000

​
tags
object
required

Custom key-value tags associated with this usage

Example:
{
  "region": "US-East",
  "plan": "Enterprise",
  "feature": "premium_support"
}
​
metrics
object[]
required

List of usage metrics for this event

​
usageReferenceId
string
required

A unique reference ID for tracking this usage event across systems

Example:

"usage_ref_98765"

​
contractId
string

Identifier of the contract under which the usage is recorded

Example:

"contract_67890"

​
eventId
string

Optional unique ID for this usage event, useful for idempotency

Example:

"event_abc123"

​
metadata
object

Optional metadata for storing extra key-value information about the usage event.

Example:
{
  "company_id": "3932",
  "recon_date": "2025-05-06 00:00:00",
  "company_name": "Reliance Europa Limited",
  "old_bag_status": "Returned"
}

Response

200 - application/json

Success

​
error
string
​
message
string
​
data
object