AI Billing

🔍 Problem Statement

Billing and operations administrators managing complex recurring revenue models (usage-based, step-up, hybrid, or exception-based pricing) face significant challenges configuring and maintaining plans in the Pelcro platform.

💡 User Stories

1. As a Product or Billing Admin, I want to define billing logic in natural language (e.g., “bill $5 for the first month and increase by $1 per month”), so that I can launch and maintain complex billing plans.

🎯 Definition of Done (DoD)

1. AI Plan Creation (UI)

1. Admin can select “AI Plan” during plan setup.

2. Required field: Plan Prompt (natural language billing rule).

3. Usage DB selector defaults to shipment table with predefined queries.

4. Available only to abstracted accounts.

*2. Billing Agent Invocation

1. At the time of subscription creation, the Billing Agent (via OpenAI API) determines whether to create an invoice immediately or defer the first invoice until renewal.

2. Send the AI Prompt + Usage data from shipments

3. if AI billing plan, use period end for invoice creation.

4. For standard or step-up pricing plans, the first invoice is created at subscription start.

5. For usage-based or hybrid plans, the first invoice is generated upon renewal, covering usage from the previous billing period.

6. The Billing Agent returns a structured JSON payload containing subscription updates and invoice details:

{ "subscription_updates": { "current_period_start": "ISO-8601", "current_period_end": "ISO-8601" }, "invoice": { "amount": 10, "currency": "USD", "start_date": "ISO-8601", "end_date": "ISO-8601" "line_items": [ {"description": "Base charge", "amount": 5}, {"description": "Usage (Shipment) charge", "amount": 5}, ] } }

3. Shipment Data Retrieval

1. Billing Agent queries the shipment and returns tables via predefined SQL templates.

2. Usage data is aggregated (sum per day of week) and fed into AI with the prompt for rate computation.

4. Subscription quantity field must be modifiable from the subscription update flow on the platform without requiring a renewal.

4. Open API & JS SDK

AI Plans are exposed via the same API structure as standard plans.

5. Accounting

For PoC, all invoices should have time-based revenue recognition.

6. Taxes

Taxes must be collected on the final invoice amount that gets generated by the billing agent.

7. Logs

1. All actions, data inputs, AI responses, and results are logged to OpenSearch.