AI Billing Agent

Overview

The Pelcro AI Billing Agent is an intelligent billing assistant built into your publisher dashboard. Create subscription plans in plain English, define pricing rules conversationally, and let the agent handle every billing cycle automatically — no manual configuration, no formulas, no guesswork.

It is powered by an AI orchestration layer with direct access to your Pelcro account — plans, subscriptions, invoices, shipments, and billing cycles.

What Is It?

The AI Billing Agent has two connected functions:

1. AI Plan Creation — A conversational chat panel that lets you build a subscription plan by describing it in plain language. As you chat, the plan configuration updates in real time on the left side of the screen. No forms, no dropdowns — just describe what you want.

2. AI-Controlled Billing — Once a subscriber is on an AI Plan, the agent takes over the entire billing lifecycle. It reads your pricing rules, calculates the correct amount for each cycle, handles step-up pricing, processes shipment-based billing, and synchronizes billing periods automatically.

How to Create an AI Plan

1. Navigate to Plans in your Pelcro dashboard
2. Click Create AI Plan
3. The AI Plan Assistant panel opens on the right — your live plan configuration appears on the left
4. Type your plan specifications in plain language, or choose a Quick Start option
5. The assistant asks follow-up questions to fill in any missing details
6. Review the auto-populated configuration on the left as it updates
7. Confirm to save the plan

Quick start options:

• ⚡ Create Basic Plan
• 🎁 Create Premium Plan
• 🏢 Create Enterprise Plan

How Does the Billing Agent Work?

Once a subscriber is on an AI Plan, every renewal is handled automatically by the agent. Here is the pipeline it follows on each billing cycle:

Step 1 — Routing & Classification

The agent reads the billing_type to determine the correct billing path:

• Receivable → Charges the customer via the Invoice Customer Agent
• Payable → Pays the vendor via the Office-Pay-Bills Agent

Step 2 — Pricing Rule Parsing

The agent scans your plan's natural-language pricing rules to extract:

• Rate identification — distinguishes plan prices (invoices) from Vendor commissions (bills)
• Step-up detection — identifies whether a price increase applies:
  • Time-based: triggered by keywords like "every 6 months"
  • Cycle-based: triggered per renewal (e.g., "each renewal")
• Rate type — fixed amount or percentage (percentages default to compounded growth)

Step 3 — Shipment & Return Processing

If the plan includes shipment data, the agent switches to per-unit pricing instead of a flat fee:

• Only shipments with an approved_at timestamp are processed
• Shipment day (week_day or created.date) is matched against day-specific rates in your rules
• Return deductions (e.g., "-$0.50 per return") are calculated and subtracted from the total

Step 4 — Amount Calculation

The agent calculates the final amount based on the current billing cycle:

Step 5 — Billing Period Synchronization

The agent calculates the exact timestamps for the next cycle:

• New start — set to the current subscription.current_period_end
• New end — calculated by adding the plan.interval to the new start date
• All dates output in YYYY-MM-DD HH:MM:SS UTC format

What Triggers the Billing Agent?

The agent is triggered automatically on each subscription renewal for any subscription on an AI Plan. No manual action is required.

Three internal data points drive its logic on each trigger:

What You Can Ask the AI Plan Assistant

Create a standard plan

"Create a monthly plan at $29.99 USD that auto-renews and is refundable."

Set up step-up pricing

"Charge $1,500 CAD per month, increasing by 3% on each renewal."

Define shipment-based billing

"Bill $3 CAD per shipment delivered on Thursdays, and $1 CAD for Fridays."

Configure carrier/dealer plans

"Carrier commission $0.37 per copy. Dealer price $0.70 per copy."

Set billing intervals

"Bill every 6 months in GBP with no auto-renewal."

Shipment-Based Plans: Renew or Expire by Shipments Remaining

For print subscriptions billed by shipment, an AI Plan can renew or expire the subscription when its shipments remaining reaches 0, instead of on a calendar date. Subscribers get exactly the number of shipments they paid for, whether those shipments arrive early, late, or on a different schedule than the plan's billing interval.

How it Works

1. You define the number of shipments per cycle in the AI Plan Assistant. The count is saved on the plan as a structured renewal trigger.
2. Each approved shipment (one with an approved_at timestamp) reduces the subscription's shipments remaining.
3. When shipments remaining reaches 0, Pelcro acts based on the subscription's renewal setup:

4. When the subscription renews, the AI Billing Agent prices the new cycle using your pricing rules, and the next cycle runs until its shipment count is used up.

> 📘 Renewal vs. Billing

> Pelcro's renewal engine detects when shipments remaining reaches 0 and triggers the renewal. The AI Billing Agent does not decide when a subscription renews; it calculates the amount for the cycle that the renewal opens. Expiration is also handled by Pelcro, not the agent.

Revenue Recognition Is Required

When your prompt includes a shipment count per cycle, it must also state that revenue is recognized per shipment. If it doesn't, the assistant blocks the save and asks you for the revenue recognition method before the plan can be created.

Example Prompts

Auto-renewing plan with a flat price per cycle
> "Create a print plan at $52 CAD, 10 shipments per cycle, auto-renewing and refundable. Renew when shipments remaining reaches 0. Recognize revenue per shipment."

Auto-renewing plan billed per shipment
> "Bill $4.50 CAD per approved shipment, 26 shipments per cycle, monthly interval, auto-renew. Open the next cycle once all 26 are delivered, not on the end date. Recognize revenue on shipment delivery."

Fixed-issue plan that expires
> "Create a 12-issue print plan at $60 CAD total, no auto-renewal, non-refundable. Expire the subscription when shipments remaining reaches 0. Recognize revenue per issue shipped."

How Shipments Are Counted Across Invoices

- Each approved shipment is associated with an invoice, and the shipments per cycle in effect when that invoice was created is stored on the invoice. Later changes to the plan do not change the shipment allowance of past invoices.
- When a subscription has more than one invoice with shipments available, shipments are counted against the oldest invoice first. Once its allowance is used up, the next invoice is used.
- A shipment approved outside its original invoice period is still counted and recognized against an invoice that has shipments available.

Rules and Limitations

- Applies to print-only subscriptions.
- Only shipments with an approved_at timestamp count toward shipments remaining. Pending shipments are ignored.
- The subscription's end date and renewal date do not trigger renewal or expiration on these plans.
- A renewal phase cannot be added to a subscription whose current period end is empty.
- The agent cannot change a subscriber's plan_id.
- Subscriptions on non-shipment plans continue to renew by date, unchanged.

Input & Output Format

Input (Plan Creation)

Plain natural language — no structured format required. The assistant extracts all plan fields from your conversation, including:

• Plan name, amount, currency
• Billing interval and interval count
• Auto-renew, refundable, availability settings
• Pricing rules (step-up logic, shipment rates, carrier/dealer splits)
• Shipments per interval

Input

{
  "plan": {
    "id": "integer | string",
    "nickname": "string",
    "amount": "string (formatted amount)",
    "currency": "string (3-letter code)",
    "interval": "string (Minute, Hour, Day, Week, Month, Year)",
    "interval_count": "integer"
  },
  "subscription": {
    "id": "integer | string",
    "quantity": "integer",
    "billing_type": "string (Receivable | Payable | null)",
    "current_period_end": "string (YYYY-MM-DD HH:MM:SS)",
    "created_at": "string (YYYY-MM-DD HH:MM:SS)",
    "start_date": "string (YYYY-MM-DD HH:MM:SS)",
    "invoice_count": "integer"
  },
  "pricing_rules": "string (natural language pricing and increase logic)",
  "shipments": [
    {
      "id": "integer | string",
      "quantity": "integer",
      "approved_at": "string | null (YYYY-MM-DD HH:MM:SS)",
      "created": {
        "date": "string (YYYY-MM-DD)",
        "time": "string (HH:MM:SS)",
        "week_day": "string (e.g., Monday)"
      },
      "returns": [
        {
          "id": "integer | string",
          "quantity_returned": "integer",
          "reason": "string"
        }
      ]
    }
  ]
}

Output

{
  "code": 200,
  "message": "string (Success message)",
  "invoice_params | Bills_params": {
    "shipments_to_update": {
      "shipment_id_string": "integer (unit rate in cents)"
    },
    "returns_to_update": {
      "return_id_string": "integer (negative deduction in cents)"
    },
    "line_items": [
      {
        "unit_price": "integer (cents)",
        "quantity": "integer",
        "description": "string",
        "plan_id": "integer"
      }
    ],
    "subtotal": "integer (total cents before tax)",
    "total": "integer (total cents after tax)",
    "tax": "integer (defaults to 0)",
    "currency": "string (3-letter code)",
    "subscription_current_period_start": "string (YYYY-MM-DD HH:MM:SS)",
    "subscription_current_period_end": "string (YYYY-MM-DD HH:MM:SS)",
    "metadata": {}
  }
}

Sample Scenarios

Sample 1 — Carrier Commission (Payable)

The agent detects billing_type: "Payable" and extracts the carrier rate of $0.37, ignoring the dealer price.

Input:

{
  "plan": { "id": "P-9314-AR", "nickname": "Dealer Fulfillment Invoice", "amount": "0.00", "currency": "usd" },
  "subscription": {
    "id": "SUB-DEALER-101", "quantity": 1, "billing_type": "Payable",
    "current_period_end": "2026-02-11 18:11:59",
    "plan": { "interval": "month", "interval_count": 1 }
  },
  "pricing_rules": "Carrier commission $0.37 per copy. Dealer price $0.70 per copy.",
  "shipments": [
    { "id": 101, "quantity": 2800, "approved_at": "2026-02-11 10:00:00", "created": { "week_day": "Wednesday" } }
  ]
}

Output:

{
  "code": 200,
  "message": "Bill parameters calculated successfully",
  "Bills_params": {
    "shipments_to_update": { "101": 37 },
    "returns_to_update": {},
    "line_items": [
      { "unit_price": 37, "quantity": 2800, "description": "Renewing subscription on Dealer Fulfillment Invoice shipments of 4m", "plan_id": 9314 }
    ],
    "subtotal": 103600, "total": 103600, "tax": 0, "currency": "usd",
    "subscription_current_period_start": "2026-02-11 18:11:59",
    "subscription_current_period_end": "2026-03-11 18:11:59",
    "metadata": {}
  }
}

Sample 2 — Shipment-Based Invoice (Receivable)

A Thursday delivery triggers the $3 CAD per-shipment rule.

Input:

{
  "plan": { "id": 40527, "nickname": "Basic 2m plan", "amount": "0.00", "currency": "cad", "interval": "Month", "interval_count": 1 },
  "subscription": { "quantity": 1, "billing_type": "Receivable", "current_period_end": "2025-09-14 12:26:05" },
  "pricing_rules": "Shipments delivered on Thursday at 3 CAD per shipment; on Friday at 1 CAD per shipment.",
  "shipments": [
    { "id": 41234613, "created": { "date": "2025-11-13", "week_day": "Thursday" }, "quantity": 1, "approved_at": "2025-11-13 07:06:30" }
  ]
}

Output:

{
  "code": 200,
  "message": "Successfully generated invoice parameters",
  "invoice_params": {
    "shipments_to_update": { "41234613": 300 },
    "returns_to_update": {},
    "line_items": [
      { "unit_price": 300, "quantity": 1, "description": "Renewing subscription on Basic 2m plan", "plan_id": 40527 }
    ],
    "subtotal": 300, "total": 300, "tax": 0, "currency": "cad",
    "subscription_current_period_start": "2025-09-14 12:26:05",
    "subscription_current_period_end": "2025-10-14 12:26:05",
    "metadata": {}
  }
}

Sample 3 — Cycle-Based Step-Up Pricing

A 3% compounded increase per renewal. With invoice_count: 2, the next cycle is 3.
Formula: $1,500 × (1 + (0.03 × (3 - 1))) = $1,590

Input:

{
  "plan": { "id": 422144, "nickname": "AI Demo Plan", "amount": "1,500", "currency": "cad", "interval": "Month", "interval_count": 1 },
  "subscription": {
    "billing_type": "Receivable",
    "current_period_end": "2025-12-17 16:48:55",
    "invoice": { "invoice_count": 2 }
  },
  "pricing_rules": "Charge $1,500 CAD; shall increase by 3% on each renewal.",
  "shipments": []
}

Output:

{
  "code": 200,
  "message": "Successfully generated invoice parameters",
  "invoice_params": {
    "shipments_to_update": {},
    "returns_to_update": {},
    "line_items": [
      { "unit_price": 159000, "quantity": 1, "description": "subscription renewal on AI Demo Plan", "plan_id": 422144 }
    ],
    "subtotal": 159000, "total": 159000, "tax": 0, "currency": "cad",
    "subscription_current_period_start": "2025-12-17 16:48:55",
    "subscription_current_period_end": "2026-01-17 16:48:55",
    "metadata": {}
  }
}

Accuracy

The AI Billing Agent has been tested across a broad range of billing scenarios including step-up pricing, shipment-based billing, carrier/dealer routing, and cycle synchronization.

Overall accuracy rate: 95%

Limitations

Tips for Best Results

• Be specific in your pricing rules — include currency, rate type, and trigger condition (e.g., "increase by 5% every anniversary")
• Define shipment day rates explicitly — e.g., "Thursday at $3 CAD, Friday at $1 CAD" rather than generic descriptions
• Use standard date formats — ensure all dates passed to the agent follow YYYY-MM-DD HH:MM:SS UTC to avoid calculation errors
• Review your plan config live — as you chat with the AI Plan Assistant, watch the left panel update in real time to catch any mismatches before saving
• Always specify Carrier vs. Dealer — for commission-based plans, use those exact keywords so the agent routes correctly

FAQ

Can I edit an AI Plan after creating it?
Yes. You can update the plan's pricing rules and configuration. Changes take effect on the next billing cycle for active subscribers.

What happens if the agent can't parse my pricing rules?
If the rules are ambiguous or missing required keywords, the agent defaults the unit price to 0 cents. Always review your plan configuration before activating it for subscribers.

Can the agent upgrade or downgrade a subscriber's plan?
No. The agent manages billing within the current plan. Plan changes must be handled separately through the standard subscription management flow.

Are shipments billed automatically?
Only shipments with an approved_at timestamp are included in billing. Pending shipments are ignored until they are approved.

Is the AI Billing Agent available on all plans?
The AI Billing Agent is available on Professional and Enterprise plans. Contact your account manager if you do not see the option in your dashboard or [email protected].

Support & Feedback

• Email Support: For questions, issues, or feedback, contact us at [email protected].