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

event

string

required

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

idempotency_key

string

required

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

metadata

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 sets a daily spending cap for each user per App. When the cap is reached, subsequent event reports will be rejected (HTTP 429). Refer to the real-time cap displayed in the product.

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

Overview

Platform API

Authentication & Keys

Integrations

SDK

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