​
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.