Billing API Guide

The Billing API enables you to charge customers based on their consumption of services or resources. Whether you need prepaid credits, postpaid invoicing, or subscription-based billing with overages, Frame provides a flexible system to track usage and automate payment collection.

Key Concepts

Billing Modes

Frame supports two primary billing modes:

1. Prepaid (Credits) — Customers purchase credits upfront. Usage is deducted from their credit balance until exhausted.

2. Postpaid (Usage-Based) — Customers use services freely. Usage accumulates as pending charges and is invoiced at period end or when a threshold is exceeded.

Note: Concurrent billing modes for a single customer are not currently supported.

Getting Started

This section walks through a basic prepaid billing integration.

Step 1: Create a Billing Meter

Define the metrics you want to track. Each meter represents a billable action or resource.

curl -X POST "https://api.framepayments.com/v1/billing/meters" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "event_name": "api_request",
    "display_name": "API Request",
    "description": "Single API request to the platform",
    "value": "10.0",
    "aggregation": "sum",
    "markup_percentage": "0"
  }'

Response:

{
  "id": "41411633-b804-4cf0-bb75-a9fc2c35b36e",
  "status": "active",
  "livemode": false,
  "aggregation": "sum",
  "event_name": "api_request",
  "description": "Single API request to the platform",
  "display_name": "API Request",
  "value": "10.0",
  "object": "billing_meter",
  "created": 1760024670,
  "updated": 1760024670
}

Step 2: Issue Billing Credits

For prepaid billing, allocate credits to a customer before they begin using your service.

curl -X POST "https://api.framepayments.com/v1/billing/billing_credit" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "customer": "5c5286be-ca91-47d7-92d1-4f211963fce9",
    "product": "d3b8cf6f-a350-4c09-834b-b58a81fd78b5",
    "collection_method": "request_payment",
    "billing_credits": 400000,
    "expires": "2026-12-12",
    "metadata": {"plan": "starter"}
  }'

Response:

{
  "id": "d005ca7e-b608-4ef8-bb70-51ae4fcece4f",
  "billing_credits": "400000.0",
  "available_credits": "400000.0",
  "used_credits": "0.0",
  "status": "active",
  "expires": 1797033600,
  "customer": "5c5286be-ca91-47d7-92d1-4f211963fce9",
  "object": "billing_credit",
  "livemode": false,
  "created": 1762367148,
  "updated": 1762367148
}

Step 3: Record Billing Events

As customers consume resources, send billing events to track usage. Include a reference field as an idempotency key to prevent duplicate charges.

curl -X POST "https://api.framepayments.com/v1/billing/metering_events" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "event_name": "api_request",
    "customer": "5c5286be-ca91-47d7-92d1-4f211963fce9",
    "value": 2,
    "timestamp": "2025-08-29T09:09:09Z",
    "reference": "req_abc123"
  }'

Response:

{
  "id": "41411633-b804-4cf0-bb75-a9fc2c35b36e",
  "meter_id": "41411633-b804-4cf0-bb75-a9fc2c35b36e",
  "customer": "5c5286be-ca91-47d7-92d1-4f211963fce9",
  "value": "2.0",
  "timestamp": "2025-08-29T09:09:09Z",
  "object": "billing_metric_event",
  "livemode": false,
  "created": 1760024670,
  "updated": 1760024670
}

Step 4: Generate Usage Reports

Retrieve aggregated usage data for a customer within a specified period.

curl -X GET "https://api.framepayments.com/v1/billing/reports?customer=5c5286be-ca91-47d7-92d1-4f211963fce9&from=2025-08-01&to=2025-08-31" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "customer": "5c5286be-ca91-47d7-92d1-4f211963fce9",
  "usage": "18000.0",
  "livemode": false,
  "aggregated_usage": [
    {
      "object": "billing_report",
      "aggregation": "sum",
      "event_name": "api_request",
      "usage": "18000.0",
      "billing_meter": "41411633-b804-4cf0-bb75-a9fc2c35b36e"
    }
  ]
}

Step 5: Generate an Invoice

For postpaid billing or when credits are exhausted, generate an invoice for the usage period.

curl -X POST "https://api.framepayments.com/v1/billing/billing_invoice" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "customer": "5c5286be-ca91-47d7-92d1-4f211963fce9",
    "collection_method": "request_payment",
    "start_date": "2025-08-01",
    "end_date": "2025-08-31"
  }'

Collection Methods:

Recipes

Prepaid Billing: Utility Company

A utility company sells prepaid electricity units. Customers purchase credits, and usage is deducted as they consume power. When credits are exhausted, the merchant is notified via webhook.

Implementation:

1. Create a billing meter for electricity usage (kWh)
2. Issue billing credits when the customer purchases a bundle
3. Record billing events as the customer consumes power
4. Handle the billing_credit.exhausted webhook to notify the customer

Meter Configuration:

curl -X POST "https://api.framepayments.com/v1/billing/meters" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "event_name": "electricity_kwh",
    "display_name": "Electricity Usage",
    "description": "Electricity consumption in kilowatt-hours",
    "value": "1.0",
    "aggregation": "sum"
  }'

When credits are exhausted, Frame sends a webhook to your configured endpoint. You can then prompt the customer to replenish their credits or transition them to postpaid billing.

Recurring Billing: SaaS Platform

A SaaS platform offers monthly subscriptions with included API credits. Usage beyond the allowance is billed as overage at the end of each billing period.

Implementation:

1. Create a billing product with credits and overage settings
2. Create a subscription for the customer
3. Record billing events as the customer uses the API
4. Frame automatically handles overage invoicing at period end

Product Configuration:

curl -X POST "https://api.framepayments.com/v1/products" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "name": "Professional Plan",
    "default_price": 5000,
    "description": "50,000 API calls per month",
    "purchase_type": "recurring",
    "recurring_interval": "monthly",
    "billing_credits": 50000,
    "billing_details": {
      "billing_type": "true_up_charge",
      "billing_credits": 50000,
      "can_rollover": true,
      "max_rollover_credits": 25000
    }
  }'

Postpaid Billing: AI Platform

An AI platform charges customers based on token usage. Customers use the API freely, and usage is invoiced when it exceeds a configured threshold or at the end of the billing period.

Pricing Model:

Implementation:

1. Create billing meters for input and output tokens
2. Configure threshold-based auto-charging
3. Record billing events for each API request
4. Frame automatically generates invoices when the threshold is exceeded

Advanced Configuration

Markup Pricing

Apply a markup percentage to billing meters for resale, partner billing, or margin management.

How It Works:

• The markup_percentage is applied on top of the base meter value
• Final billable amount = value × (1 + markup_percentage / 100)

Example:

{
  "event_name": "api_request",
  "display_name": "API Request",
  "value": "0.10",
  "markup_percentage": "25.0"
}

Rollover Credits

Allow unused credits to roll over to the next billing period instead of expiring.

Configuration:

{
  "billing_details": {
    "billing_credits": 200000,
    "can_rollover": true,
    "max_rollover_credits": 100000
  }
}

Overage Billing

Automatically track and invoice usage that exceeds the prepaid credit allocation.

Configuration:

{
  "billing_details": {
    "billing_credits": 200000,
    "overage_enabled": true,
    "collection_method": "auto_charge"
  }
}

When credits are exhausted, additional usage is tracked and invoiced at period end or when a threshold is reached.

True-Up Billing

Combine committed usage with overage charges. Customers commit to a minimum usage level and pay for any excess at the standard rate.

Note: Frame treats all subscriptions as true-up billing by default. The subscription fee covers the committed amount, and overages are billed separately.

Configuration:

{
  "billing_details": {
    "billing_type": "true_up_charge",
    "billing_credits": 200000,
    "can_rollover": true,
    "max_rollover_credits": 200000
  }
}

Threshold-Based Auto-Charging

Configure automatic invoicing when accumulated usage exceeds a threshold.

How It Works:

1. Billing events accumulate as pending charges
2. When total charges exceed the threshold, Frame automatically:
   • Generates an invoice for all pending charges
   • Charges the customer's default payment method
   • Marks all included events as invoiced

Configuration:

{
  "billing_auto_charge": true,
  "billing_auto_charge_threshold": 5000
}

Example Scenario:

Stale Charge Handling:

To prevent charges from accumulating indefinitely, Frame invoices pending charges when:

• Charges are older than 7 days (default)
• The configured billing cycle ends (daily, weekly, monthly)
• Manually triggered via API

Glossary