> ## Documentation Index
> Fetch the complete documentation index at: https://docs.justpaid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage based billing

# JustPaid Usage Billing Guide

Usage-based billing allows companies to charge their customers based on actual usage of services or products. This guide will walk you through setting up usage-based billing in the JustPaid platform.

### Example Use Cases

* A payments company might charge based on the number of ACH transactions or check payments.
* A KYC compliance API might bill based on the number of KYC checks performed.
* An OCR platform might charge based on the number of invoices or receipts processed.

### Step 1: Create a Customer

#### Method 1: Dashboard

1. **Upload a Contract**: Start by uploading a contract to the JustPaid dashboard.
2. **Create Line Items**: Define the billable items (usage-based or fixed-fee).
3. **Invoice Schedule**: Set up the invoice schedule.
4. **Accept Contract**: Accepting the contract creates the customer and associates the contract with the customer.

#### Method 2: API

1. **Create Customer Endpoint**: Call the `create customer` endpoint with the customer's email and name.
2. **Customer ID**: The system will return a unique customer ID to be used in subsequent steps.

### Step 2: Retrieve Billable Items

* Use the `/items` endpoint to get all usage-based items associated with a customer.
* Filter items by passing the customer ID to retrieve specific events.
* The endpoint returns event details like `item name` and `item ID`.

### Step 3: Ingest Usage Data

1. **Ingest Endpoint**: Use the `usage/ingest` endpoint to record usage data.
2. **Parameters**:
   * `Customer ID`
   * `Event Name`
   * `Event Value` (quantity of usage)
   * `Timestamp` (ISO 8601 format, converted to UTC)
3. **Additional Properties**: Optionally pass additional key-value pairs for further filtering or billing metrics.
4. **Idempotency Key**: Use a unique UUID to prevent duplicate records.

#### Example

For an OCR company:

* **Customer ID**: Provided by the system.
* **Event Name**: `invoices`
* **Event Value**: Number of invoices (e.g., 50)
* **Timestamp**: When the event occurred (e.g., `2024-07-15T11:30:00Z`)

### Step 4: Create Billable Metrics

1. **Billing Metrics Endpoint**: Use the `/billing/metrics` endpoint to create billing metrics.
2. **Metric Types**:
   * **Sum**: Aggregate usage events (e.g., total number of invoices processed).
   * **Custom**: Define specific billing rules (e.g., bulk billing rates).

### Step 5: Invoice Generation

1. **Pre-Generated Invoices**: The system generates invoices for the service period before it ends.
2. **Usage Data Association**: Recorded usage data is mapped to the corresponding invoice.
3. **Invoice Details**: View detailed usage information under invoice details.
4. **Automatic Send**: If enabled, invoices are sent automatically after the service period ends.
5. **Manual Review**: If automatic send is disabled, invoices are held for manual review and approval.

## Error Handling

* **Invalid Input**: The system will return error messages for any invalid data (e.g., missing idempotency key, incorrect event ID).
* **Duplicate Events**: The system uses idempotency keys to identify and handle duplicate events.

## Conclusion

By following these steps, you can effectively implement usage-based billing in JustPaid, ensuring accurate and timely billing based on actual usage. For further assistance, refer to the API documentation or contact support.