​

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.