Report Billing Events

Report custom billing events for App per-use (PER_USE) billing scenarios. Each event report deducts the corresponding credit amount from the authorized user’s account based on the Meter configuration.

POST https://api.profy.cn/v1/events

Authentication

This endpoint only supports OAuth Bearer Tokens. API Key authentication will return a 401 error.Custom billing events deduct credits from the user’s account and must go through OAuth to ensure the user’s informed consent.

Authorization: Bearer <access_token>

Request Body

string

required

Event name, must exactly match a Meter event name configured in the App. Maximum 100 characters.

string

required

Idempotency key to prevent duplicate charges. The same idempotency_key will not be charged twice. Maximum 128 characters.

object

Additional metadata as key-value pairs. Used to record extra business information without affecting billing.

Request Examples

from profy import Profy

client = Profy(api_key="<oauth_access_token>")

result = await client.events.report(
    "image_generation",
    idempotency_key="order_12345_gen_1",
    metadata={"style": "watercolor", "resolution": "1024x1024"},
)
print(f"Charged: {result['charged']} credits")
print(f"Remaining: {result['balance_remaining']} credits")

import { Profy } from "@profy-ai/sdk";

const client = new Profy({ apiKey: "<oauth_access_token>" });

const result = await client.events.report("image_generation", {
  idempotencyKey: "order_12345_gen_1",
  metadata: { style: "watercolor", resolution: "1024x1024" },
});

console.log(`Charged: ${result.charged} credits`);
console.log(`Remaining: ${result.balance_remaining} credits`);

curl -X POST https://api.profy.cn/v1/events \
  -H "Authorization: Bearer <oauth_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "image_generation",
    "idempotency_key": "order_12345_gen_1",
    "metadata": {
      "style": "watercolor",
      "resolution": "1024x1024"
    }
  }'

Response

Normal Charge

{
  "charged": 50,
  "balance_remaining": 9450
}

Field	Type	Description
`charged`	`number`	Credits deducted for this event
`balance_remaining`	`number`	Remaining credits after deduction

Idempotent Replay

When the same idempotency_key is submitted again, no duplicate charge occurs:

{
  "charged": 50,
  "balance_remaining": 9450,
  "idempotent_replay": true
}

idempotent_replay: true indicates this was an idempotent replay and credits were not deducted again.

Idempotency Guarantees

Always use meaningful idempotency keys. Recommended format: {entity}_{id}_{operation}, for example order_12345_gen_1.

Prevents duplicate charges from network retries — when clients retry on timeout, the same idempotency key ensures only one charge
Prevents duplicate charges from business logic — multiple calls for the same business operation will only charge once
Idempotency window — the same (app_uuid, idempotency_key) combination is permanently valid

How It Works

Your App → POST /v1/events → Find Meter → Deduct credits → Return result
                                  ↑
                            App-configured Meter
                          (event_name → price)

Your App obtains user authorization through OAuth
When the user uses a paid feature, call the Events API to report the event
Profy looks up the corresponding credit price from the App’s Meter configuration
Deducts the corresponding amount from the authorized user’s credits
Returns the charge result and remaining balance

Daily Spending Cap

The platform enforces a daily spending cap per App × end user, defaulting to 500 credits/day (the app_daily_cap.daily_limit column default, adjustable per user). Once reached, subsequent event reports are rejected with HTTP 429, and the response carries a daily_limit field.

Two details that commonly trip people up:

The reset boundary is UTC midnight, not local midnight. The comparison uses the date string from new Date().toISOString(), so for users in China the allowance resets at 08:00 Beijing time.
The cap is isolated per end user, not a total across your App. One end user burning through their allowance does not affect your other users — and conversely, you cannot bypass a given user’s cap on the grounds that the App has headroom overall.

Error Codes

HTTP Status Code	Error Type	Description
`400`	`invalid_request`	Missing required fields or field exceeds length
`400`	`unknown_event`	No matching Meter configuration found
`400`	`meter_disabled`	The corresponding Meter has been disabled
`401`	`unauthorized`	Requires OAuth Token, API Key not supported
`429`	`daily_cap_exceeded`	User’s daily spending cap reached

Get Started

Authentication & Keys

API Guides

SDK

Integrations

Cookbook

Reference

Report Billing Events

Authentication

Request Body

Request Examples

Response

Normal Charge

Idempotent Replay

Idempotency Guarantees

How It Works

Daily Spending Cap

Error Codes

Next Steps

Meter Configuration

Build a Profy App

​Authentication

​Request Body

​Request Examples

​Response

​Normal Charge

​Idempotent Replay

​Idempotency Guarantees

​How It Works

​Daily Spending Cap

​Error Codes

​Next Steps

Meter Configuration

Build a Profy App

Authentication

Request Body

Request Examples

Response

Normal Charge

Idempotent Replay

Idempotency Guarantees

How It Works

Daily Spending Cap

Error Codes

Next Steps