---
name: hyperline
description: Use when building billing systems, managing subscriptions, creating invoices, handling payments, tracking usage, managing customer data, or automating revenue workflows. Agents should reach for this skill when working with B2B SaaS billing, CPQ (Configure-Price-Quote), usage-based pricing, accounting integrations, or customer intelligence tasks.
metadata:
    mintlify-proj: hyperline
    version: "1.0"
---

# Hyperline Skill

## Product summary

Hyperline is a comprehensive billing and revenue management platform for B2B SaaS companies. It handles subscriptions, invoicing, payments, usage tracking, customer management, accounting, and CPQ workflows. Agents use Hyperline to automate billing operations, manage complex pricing models, track revenue, and integrate with payment providers and accounting software.

**Key entry points:**
- **API**: `https://api.hyperline.co/v1/` (production) or `https://sandbox.api.hyperline.co/v1/` (test)
- **MCP server**: `https://api.hyperline.co/mcp` for AI assistants
- **CLI**: `npm install -g @hyperline/cli` for terminal-based agents
- **Web app**: `https://app.hyperline.co`
- **OpenAPI spec**: `https://api.hyperline.co/openapi`

**Core concepts:**
- **Customers**: Individual accounts with subscriptions, invoices, and payment methods
- **Products**: Catalog items (fee, seat, usage, credit, bundle) with pricing models
- **Subscriptions**: Contracts between you and a customer with products, terms, and billing schedules
- **Invoices**: Generated automatically from subscriptions or created manually
- **Transactions**: Payments, refunds, and chargebacks tracked against invoices
- **Aggregators**: Metrics that transform usage events into billable quantities
- **Ledgers**: Accounting records with chart of accounts and revenue recognition rules

## When to use

Reach for this skill when:
- Creating or updating subscriptions, quotes, or invoices via API
- Querying customer data, usage, or payment status
- Setting up usage-based billing with aggregators and metering
- Managing payment methods, transactions, or reconciliation
- Configuring products, pricing, or price books
- Building accounting integrations or revenue recognition workflows
- Automating customer intelligence tasks (monitoring, segmentation, health analysis)
- Connecting payment providers (Stripe, Mollie, GoCardless, Adyen, Airwallex)
- Exporting data or generating reports
- Testing billing flows in sandbox before production

## Quick reference

### API authentication

```bash
# Bearer token (recommended)
curl -H "Authorization: Bearer <API_KEY>" https://api.hyperline.co/v1/customers

# Generate API key in workspace Settings > API
# Prefix: prod_ (production) or test_ (sandbox)
```

### Core endpoints

| Task | Endpoint | Method |
|------|----------|--------|
| List customers | `/v1/customers` | GET |
| Create customer | `/v1/customers` | POST |
| Get customer | `/v1/customers/{id}` | GET |
| List subscriptions | `/v1/subscriptions` | GET |
| Create subscription | `/v1/subscriptions` | POST |
| List invoices | `/v1/invoices` | GET |
| Create invoice | `/v1/invoices` | POST |
| List products | `/v1/products` | GET |
| Create product | `/v1/products` | POST |
| List transactions | `/v1/transactions` | GET |
| Send usage events | `https://ingest.hyperline.co/v1/events` | POST |

### Subscription statuses

| Status | Meaning |
|--------|---------|
| `pending` | Created but not yet active; won't be charged |
| `active` | Running and will be invoiced at next payment date |
| `paused` | Invoicing paused; can be reactivated |
| `cancelled` | Cancelled from active state |
| `voided` | Cancelled from pending state without activation |
| `errored` | Failed to charge after 4 attempts; manually reactivate |

### Product types

| Type | Use case | Pricing models |
|------|----------|-----------------|
| **Fee** | Fixed charges, platform access, onboarding | Flat fee |
| **Seat** | Per-user licensing | Volume, bulk, bundle |
| **Usage** | Pay-per-use (API calls, data transfer) | Volume, bulk, basis points |
| **Credit** | Prepaid balance (AI tokens, compute hours) | Volume, bulk, bundle |
| **Bundle** | Grouped products sold as one unit | Volume, bulk, packaged, bundle |

### Pricing models

| Model | Description |
|-------|-------------|
| **Flat fee** | Fixed, unchanging price |
| **Volume** | Price per unit decreases with quantity (progressive tiers) |
| **Bulk** | Total quantity determines tier; all units at that tier price |
| **Packaged** | Volume pricing with defined package sizes |
| **Bundle** | Predefined quantity/price combinations |
| **Basis points (BPS)** | Percentage-based pricing with tiers |

### Invoice statuses

| Status | Meaning |
|--------|---------|
| `draft` | Not yet emitted; can be edited |
| `to_pay` | Emitted and awaiting payment |
| `partially_paid` | Partially settled |
| `paid` | Fully settled |
| `uncollectible` | Marked as uncollectible |
| `voided` | Cancelled |

## Decision guidance

### When to use subscriptions vs. one-off invoices

| Scenario | Use subscriptions | Use one-off invoices |
|----------|-------------------|----------------------|
| Recurring billing (monthly, annual) | ✓ | |
| Fixed contract with terms | ✓ | |
| Usage-based metering | ✓ | |
| One-time charges | | ✓ |
| Ad-hoc billing | | ✓ |
| Quotes that auto-activate | ✓ | |

### When to use different product types

| Scenario | Product type |
|----------|--------------|
| Monthly SaaS platform fee | Fee |
| Per-user licensing | Seat |
| API calls, data transfer, compute | Usage |
| Prepaid AI tokens or credits | Credit |
| Bundled platform + seats + usage | Bundle |

### When to use MCP vs. CLI vs. API

| Scenario | Use MCP | Use CLI | Use API |
|----------|---------|---------|---------|
| Conversational AI (Claude, ChatGPT) | ✓ | | |
| Terminal-based agents (Cursor, Windsurf) | | ✓ | |
| Server-side integrations | | | ✓ |
| Webhooks and real-time events | | | ✓ |
| Lightweight, token-efficient queries | | ✓ | |

### When to use aggregators vs. metering filters

| Scenario | Use aggregators | Use metering filters |
|----------|-----------------|----------------------|
| Define billable metric (count, sum) | ✓ | |
| Filter events by custom fields | ✓ | |
| Apply different prices per filter | | ✓ |
| Complex pricing matrices | | ✓ |

## Workflow

### 1. Set up account and catalog

1. Configure account: business info, invoicing entities, payment methods
2. Create products in catalog with pricing models and currencies
3. Optionally create price books to group products
4. Set up payment providers (Stripe, Mollie, etc.) in Payments section
5. Test in sandbox mode before production

### 2. Create and manage customers

1. Create customer via API or UI with name, email, country, currency
2. Optionally add custom properties for segmentation
3. Add payment methods (card, direct debit, bank transfer)
4. Assign to segments for analytics and targeting
5. Monitor customer health via Customer Intelligence

### 3. Set up usage-based billing (if applicable)

1. Create aggregator to define billable metric (count or sum)
2. Configure filters on aggregator for custom fields
3. Create usage product linked to aggregator
4. Set pricing tiers (volume, bulk, or basis points)
5. Send usage events to `https://ingest.hyperline.co/v1/events`
6. Verify usage appears in customer usage tab

### 4. Create subscriptions or quotes

**For subscriptions:**
1. Open customer page or go to Subscriptions
2. Click "New subscription" or "Assign new subscription"
3. Select products and pricing
4. Configure billing interval and commitment period
5. Set payment method (immediate, checkout, or manual)
6. Activate subscription (automatic or manual)

**For quotes (CPQ):**
1. Create quote from template or from scratch
2. Add products and customize pricing
3. Set terms, expiration, and attachments
4. Send to customer for signature
5. Quote auto-activates subscription on signature

### 5. Manage invoices and payments

1. Invoices auto-generate from subscriptions on schedule
2. Review invoice in Invoices section
3. Send invoice to customer via email
4. Record payment: allocate transaction or record offline payment
5. Reconcile transactions with invoices
6. Export invoices for accounting sync

### 6. Monitor and analyze

1. Check dashboard for MRR, ARR, churn, and growth metrics
2. Run reports on customers, subscriptions, invoices, usage
3. Export data for external analysis
4. Set up webhooks for real-time event notifications
5. Use Customer Intelligence agent for health analysis

## Common gotchas

- **API key prefix matters**: `prod_` keys only work in production; `test_` keys only in sandbox. Mixing them causes authentication failures.
- **Amounts in smallest currency unit**: All monetary amounts in API are in the currency's smallest unit (cents for USD, pence for GBP). Divide by 100 for display.
- **Subscription must be activated**: Creating a subscription sets status to `pending`. It won't invoice until activated (manually, via quote signature, or at scheduled date).
- **Usage events are asynchronous**: Events sent to ingest API may take seconds to appear in usage reports. Don't assume immediate consistency.
- **Invoices are immutable once emitted**: Draft invoices can be edited; emitted invoices cannot. Create credit notes for adjustments.
- **Metering period resets**: Usage resets at the start of each metering period (billing cycle). Committed amounts are minimum charges regardless of actual usage.
- **Payment method required for auto-charge**: Subscriptions with immediate payment need a valid payment method on file. Manual payment subscriptions don't.
- **Tax calculation is automatic**: Tax is computed based on customer country and product tax category. Ensure customer country is set correctly.
- **Sandbox emails are real**: Sandbox doesn't block outbound emails. Use test email addresses to avoid sending to real customers.
- **Ledger type is immutable**: Accounting ledger type (IFRS, US_GAAP, etc.) cannot be changed after creation. Choose carefully.
- **Revenue recognition is automatic**: Journal entries post automatically based on accounting rules. Manual adjustments are tracked in audit trail.
- **Webhook signatures must be verified**: Always verify webhook signatures using the shared secret to prevent spoofing.

## Verification checklist

Before submitting work with Hyperline:

- [ ] API key is correct and has appropriate scopes (read/write)
- [ ] Using correct environment (sandbox for testing, production for live)
- [ ] All monetary amounts are in smallest currency unit (e.g., cents)
- [ ] Customer has required fields: name, email, country, currency
- [ ] Subscription has at least one product assigned
- [ ] Subscription is activated (status is `active`, not `pending`)
- [ ] Payment method is configured if subscription requires auto-charge
- [ ] Usage events are sent to correct ingest endpoint
- [ ] Aggregator is linked to usage product
- [ ] Invoice is emitted before attempting payment (not in draft)
- [ ] Webhook endpoint is HTTPS and responds with 2xx status
- [ ] Accounting ledger type matches reporting requirements
- [ ] Tax rates are configured for customer countries
- [ ] Payment provider is connected and credentials are valid
- [ ] Sandbox flow tested end-to-end before production

## Resources

**Comprehensive navigation:**
- [docs.hyperline.co/llms.txt](https://docs.hyperline.co/llms.txt) — Full page index for LLM navigation

**Critical documentation:**
1. [API Getting Started](https://docs.hyperline.co/api-reference/docs/getting-started) — Authentication, endpoints, sandbox setup
2. [Subscriptions Overview](https://docs.hyperline.co/docs/subscriptions/overview) — Subscription model, lifecycle, billing logic
3. [Products and Pricing](https://docs.hyperline.co/docs/products/overview) — Product types, pricing models, catalog management
4. [Usage-Based Billing Guide](https://docs.hyperline.co/guides/configure-usage-based-billing) — Aggregators, metering, event ingestion
5. [Invoices Overview](https://docs.hyperline.co/docs/invoices/overview) — Invoice generation, reconciliation, payment allocation
6. [Accounting Getting Started](https://docs.hyperline.co/docs/accounting/getting-started) — Ledgers, revenue recognition, journal entries
7. [Build with LLMs](https://docs.hyperline.co/api-reference/docs/ai/overview) — MCP, CLI, and AI integration options

---

> For additional documentation and navigation, see: https://docs.hyperline.co/llms.txt