Usage-Based Billing

Report customer usage for metered and hybrid billing products

Billing Models

Revnu supports three billing models:

Model	Flat Fee	Usage Charges
Flat	Fixed monthly or one-time price	None
Metered	None	Pay per unit of usage
Hybrid	Fixed monthly fee	Plus usage charges on top

For metered and hybrid products, your app reports usage events via the API. Stripe aggregates usage over the billing period and invoices customers automatically.

API Endpoint

POST/api/v1/usage

Report a usage event for a customer.

Headers

Authorization: Bearer rev_xxxxx
Content-Type: application/json

Request Body

{
  "productId": "k57abc123...",
  "stripeCustomerId": "cus_xxxxx",
  "value": 150
}

Field	Type	Description
productId	string	Your Revnu product ID
stripeCustomerId	string	The Stripe customer ID (from the purchase record)
value	integer	Usage amount (must be a positive whole number)

Success Response (200)

{
  "success": true,
  "value": 150,
  "eventName": "api_calls"
}

Error Responses

Status	Description
400	Value must be a positive whole number, or product does not support metered billing
401	Invalid API key
404	Product not found
429	Rate limit exceeded (500 requests per minute per creator)
502	Failed to report usage to Stripe

Integration Example

// Report usage from your app's backend
async function reportUsage(customerId: string, units: number) {
  const response = await fetch("https://your-store.revnu.app/api/v1/usage", {
    method: "POST",
    headers: {
      "Authorization": "Bearer rev_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      productId: "your_product_id",
      stripeCustomerId: customerId,
      value: units,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    console.error("Usage report failed:", error);
  }
}

// Example: report 1 unit per API call
app.use("/api/*", async (req, res, next) => {
  next();
  // Report usage (fire and forget)
  reportUsage(req.customerId, 1).catch(console.error);
});

Important Notes

Values must be whole numbers. Use 1 for "1 API call", not 0.5.

Report usage as it happens. Don't batch over long periods. Stripe aggregates for you.

Rate limit: 500 requests per minute per creator. For higher throughput, batch multiple units into a single event (e.g., value: 100 instead of 100 separate events).

First invoice for metered subscriptions only includes the flat fee (if hybrid). Usage charges appear on the second invoice onwards.

Finding the Stripe Customer ID

The stripeCustomerId is available in the purchase record after checkout. You can:

Query GET /api/v1/access?email=customer@example.com
Store it in your own database when you receive the checkout webhook
Look it up in the Revnu dashboard under Purchases