External Costs

External costs bill third-party spend that Paygent doesn’t track automatically — telephony minutes, SMS, shipping, human review, proprietary APIs, or any pass-through expense. You define cost categories and pricing rules in the dashboard, then report usage from your application with send_external_cost.

How external billing works

Dashboard: External Cost → cost category + billing configs
        │
        ▼
Your app: send_external_cost(agent, customer, cost_data)
        │
        ▼
Paygent: match config → calculate amount → invoice line item

Step 1 — Create an external cost category

Sidebar → External Cost → Add Cost

The externalCostId must match ExternalCostData.external_cost_id in your integration.

Step 2 — Add billing configurations

Expand a cost category → Add Config

FLAT example

• Config name: inbound_call
• Billing type: FLAT
• Price: $0.05 per call

Every matching event bills $0.05 regardless of properties.

PER_UNIT example

• Config name: inbound_call
• Billing type: PER_UNIT
• Price: $0.02
• Unit field: duration_minutes

Event with properties: {"duration_minutes": 2.5} → $0.02 × 2.5 = $0.05

Multiple property rates

Set property rates when each key has its own rate:

propertyRates: { "minutes": 0.02, "sms_segments": 0.01 }
properties:    { "minutes": 3, "sms_segments": 2 }
→ $0.02×3 + $0.01×2 = $0.08

Step 3 — Send usage from your application

1
import paygent_sdk
2
from paygent_sdk.models import ExternalCostData
3
4
paygent_sdk.init(api_key="your-paygent-api-key")
5
6
paygent_sdk.send_external_cost(
7
    agent_id="voice-agent",
8
    customer_id="customer-123",
9
    indicator="call-completed",  # optional — links to agent indicator
10
    cost_data=ExternalCostData(
11
        name="inbound_call",           # must match config name
12
        external_cost_id="telephony",  # must match cost category ID
13
        properties={"duration_minutes": 2.5},
14
        meta_tags={"region": "us-east"},
15
    ),
16
)

Required fields

Missing or unknown configs: the event is stored but may not generate revenue until a matching config exists.

Error handling

The SDK validates required fields synchronously and raises ValueError if agent_id, customer_id, name, or external_cost_id is blank.

Network and API errors are logged asynchronously — send_external_cost is fire-and-forget and does not block your application. Wrap init calls in your own retry/monitoring if external costs are business-critical.

Invalid meta_tags are omitted with a warning; the cost event is still sent.

External costs on invoices

When billing runs for an active order:

1. External cost events in the period are aggregated per config
2. Amounts appear as invoice line items alongside platform fees and usage
3. Taxes apply to the subtotal if configured on the order

View usage summaries in the dashboard under External Cost (date range + optional customer filter).

Example: voice agent telephony pass-through

1. External Cost → category telephony / ID telephony
2. Config inbound_call: PER_UNIT, $0.018/min, unit field duration_minutes
3. Config outbound_call: PER_UNIT, $0.025/min, unit field duration_minutes
4. After each call, your telephony webhook calls send_external_cost
5. Monthly invoice includes telephony line items + AI usage from the same agent

Checklist

• ✓ External cost category created with stable externalCostId
• ✓ Billing config(s) created with matching name and active status
• ✓ PER_UNIT: property keys in SDK match unit fields / property rates
• ✓ Active order exists for the customer
• ✓ SDK sends events with correct agent and customer IDs

Related: Meta Tags · Orders & Invoicing · Error Handling