> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpaygent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpaygent.com/_mcp/server.

# How It Works

Paygent connects your AI application to billing in six stages. This page is the **integration map** — follow it top to bottom when onboarding a new product or customer.

---

## Architecture overview

```
Your Application                    Paygent                           Customer
─────────────────                  ───────                           ────────
SDK: send_usage /                  Agents + Indicators               Invoice PDF
      send_indicator /             Plans + Pricing                   Payment link
      send_external_cost    →      Orders + Billing run       →      Wallet balance
                                   Invoices + Taxes
```

---

## Step 1 — Define your product (dashboard)

Before writing code, configure what you sell:

| Task                              | Where                                                              |
| --------------------------------- | ------------------------------------------------------------------ |
| Create **agent** + **indicators** | Agents → Create Agent                                              |
| Set **pricing** (fees + usage)    | Agent Step 3, or via [Plans](/documentation/introduction/plans)    |
| Optional: **credit currency**     | [Credit Currencies](/documentation/introduction/credit-currencies) |
| Optional: **billable metrics**    | [Billable Metrics](/documentation/introduction/billable-metrics)   |
| Optional: **external cost rules** | [External Costs](/documentation/introduction/external-costs)       |
| Optional: **custom model rates**  | [Custom Pricing](/documentation/introduction/custom-pricing)       |
| Optional: **tax rules**           | [Taxes](/documentation/introduction/taxes)                         |

---

## Step 2 — Integrate the SDK (your app)

Install the SDK and send events as your AI runs:

#### Python

```python
import paygent_sdk
paygent_sdk.init(api_key="your-api-key")

# Automatic LLM tracking
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    paygent_agent_id="support-bot",
    paygent_customer_id="cust_123",
    paygent_indicator="message-sent",
)

# Or explicit indicator / external cost
paygent_sdk.send_indicator("support-bot", "cust_123", "ticket-resolved")
```

#### Node.js

```typescript
const client = PaygentClient.newClient('your-api-key');
await client.sendUsage('support-bot', 'cust_123', 'message-sent', usageData);
```

#### Go

```go
client := paygent.NewClient("your-api-key")
client.SendUsage("support-bot", "cust_123", "message-sent", usageData)
```

Every event includes **agent ID**, **customer ID**, and **indicator**. Paygent resolves pricing, credits, and custom rates server-side.

[SDK Installation →](/documentation/sdks/installation)

---

## Step 3 — Register customers (dashboard or API)

Create customers with an **external ID** matching your database primary key:

```
externalId: "cust_123"  ← pass this as customer_id in SDK calls
```

Add billing address and tax defaults for invoice PDFs.

[Customers API →](/api-reference/customers-api)

---

## Step 4 — Create an order (contract)

An order ties a customer to agents, plans, seat counts, taxes, and billing schedule:

1. **Orders → Create Order**
2. Pick customer, billing day, payment terms
3. Add agent lines — select a [Plan](/documentation/introduction/plans) or default pricing
4. Configure wallet settings if the plan includes credit benefits
5. Attach [taxes](/documentation/introduction/taxes) if needed
6. **Activate** the order

Draft orders do not bill. Only **active** orders generate invoices.

[Orders & Invoicing →](/documentation/introduction/orders-and-invoicing)

---

## Step 5 — Usage accumulates (automatic)

As your app sends events:

* **Activity/outcome indicators** → metered for usage billing
* **Billable metrics** → aggregate meta\_tags into quantities
* **Credit indicators** → debit prepaid wallets or accrue postpaid usage
* **External costs** → match dashboard configs → invoice lines
* **Voice/video** → minutes, tokens, resolution tiers via custom pricing

Monitor real-time usage in **Dashboard → Agent Analytics**.

---

## Step 6 — Billing runs → invoices (automatic)

On each customer's **billing day**, Paygent:

1. Aggregates usage for the billing period
2. Adds setup, platform, and seat fees (see [Subscription Fees](/documentation/introduction/subscription-fees))
3. Applies external cost and wallet conversions
4. Calculates [taxes](/documentation/introduction/taxes)
5. Creates an invoice (PDF + line items)

You can **send email**, **generate a Stripe payment link**, or **mark as paid** to release pending wallet credits.

---

## Common integration paths

### Path A — Simple usage billing

Agent + indicator + FLAT price → SDK → order → invoice.\
Best for: MVP, single product, pay-per-call.

### Path B — SaaS subscription + usage

Plan with platform fee + seat fee + activity indicators.\
Best for: B2B AI tools with base subscription and overage.

### Path C — Prepaid credits

Credit currency → platform fee credit benefits → prepaid wallet → CREDITS indicators.\
Best for: API marketplaces, developer platforms.

### Path D — Voice agent

Voice SDK + custom per-minute pricing + external telephony costs.\
Best for: AI phone agents, speech-to-speech products.

---

## Why this works

* **Real-time tracking** — no lost billable events between billing cycles
* **Server-side pricing** — change rates in dashboard without redeploying
* **Automatic invoicing** — eliminates spreadsheet reconciliation
* **Flexible models** — combine fees, credits, taxes, and pass-through costs on one invoice

[Quick Start →](/documentation/getting-started/quick-start)