---
name: hyperline
description: Use when building billing integrations, managing subscriptions,
  creating invoices, tracking usage-based billing, handling payments, or
  automating revenue workflows. Reach for this skill when working with the
  Hyperline API, CLI, or MCP server to query billing data, create subscriptions,
  manage customers, or configure complex pricing models.
metadata:
  mintlify-proj: hyperline
  version: "1.0"
---

# Hyperline Skill

## Product summary

Hyperline is a comprehensive billing platform for B2B SaaS companies that manages subscriptions, invoicing, payments, usage-based billing, quotes (CPQ), customer intelligence, and accounting. Agents use Hyperline to automate billing workflows through the REST API (base URL: `https://api.hyperline.co` for production, `https://sandbox.api.hyperline.co` for sandbox), the Hyperline CLI for terminal-based operations, or the MCP server for AI assistant integration. Key files and endpoints: API authentication via Bearer tokens (API keys prefixed `prod_` or `test_`), webhook endpoints for event-driven workflows, subscription and invoice creation endpoints, usage event ingestion at `https://ingest.hyperline.co`, and the OpenAPI specification at `https://api.hyperline.co/openapi`. Primary documentation: [docs.hyperline.co](https://docs.hyperline.co).

## When to use

Use this skill when:
- **Building API integrations**: Creating customers, subscriptions, invoices, or quotes programmatically
- **Managing subscriptions**: Activating, updating, canceling, or pausing subscriptions; handling subscription phases and transitions
- **Handling usage-based billing**: Sending usage events, creating aggregators, configuring metered products, or tracking consumption
- **Processing payments**: Orchestrating payment collection, handling payment errors, allocating transactions, or managing payment methods
- **Generating invoices**: Creating one-time or recurring invoices, managing invoice status, or handling credit notes
- **Querying billing data**: Retrieving customer details, subscription history, invoice status, or revenue metrics
- **Setting up webhooks**: Listening to billing events (subscription.created, invoice.ready, payment_method.activated, etc.)
- **Working with AI**: Using the MCP server or CLI to let AI assistants query and manage billing data
- **Testing workflows**: Using sandbox mode to validate billing flows before production

## Quick reference

### API endpoints (v2 preferred over v1)

| Task | Endpoint | Method |
|------|----------|--------|
| List customers | `POST /v2/customers` | GET |
| Create customer | `POST /v2/customers` | POST |
| Get customer | `GET /v2/customers/{id}` | GET |
| List subscriptions | `GET /v2/subscriptions` | GET |
| Create subscription | `POST /v2/subscriptions` | POST |
| Get subscription | `GET /v2/subscriptions/{id}` | GET |
| Cancel subscription | `POST /v2/subscriptions/{id}/cancel` | POST |
| List invoices | `GET /v2/invoices` | GET |
| Create invoice | `POST /v2/invoices` | POST |
| Create invoices (batch) | `POST /v2/invoices/batch` | POST |
| Send invoice emails | `POST /v1/invoices/send-email` | POST |
| Ingest usage events | `POST /v1/events` or `/v1/events/batch` | POST |
| Create webhook | `POST /v1/webhooks/endpoints` | POST |
| List webhook messages | `GET /v1/webhooks/messages` | GET |

### Authentication

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

# Generate API key in Settings > API, prefix indicates environment
# prod_* for production, test_* for sandbox
```

### Key configuration files and concepts

| Concept | Purpose |
|---------|---------|
| **Invoicing entity** | Legal entity issuing invoices; configure in Settings > Account |
| **Payment method** | How customers pay (card, direct debit, bank transfer); configure per entity |
| **Aggregator** | Transforms raw usage events into billable metrics (count, sum, SQL formula) |
| **Usage product** | Product type that bills based on aggregator consumption |
| **Subscription** | Contract linking customer, products, pricing, and billing terms |
| **Quote template** | Pre-configured quote with products, terms, and attachments for CPQ |
| **Webhook endpoint** | URL receiving billing events; filter by event type |

### Common CLI commands (Hyperline CLI)

```bash
hyperline customers list                    # List all customers
hyperline customers get <id>                # Get customer details
hyperline subscriptions list                # List subscriptions
hyperline subscriptions create              # Create subscription
hyperline invoices list                     # List invoices
hyperline invoices create                   # Create invoice
```

### Sandbox vs. production

- **Sandbox**: Use `test_` API keys and `https://sandbox.api.hyperline.co`
- **Production**: Use `prod_` API keys and `https://api.hyperline.co`
- Test mode available in UI for safe experimentation before production billing

## Decision guidance

| Scenario | Use this approach | Why |
|----------|------------------|-----|
| **One-time charge** | Create invoice directly via API | Faster than subscription; no recurring billing |
| **Recurring billing** | Create subscription with products | Handles automatic invoicing, renewal, and phases |
| **Usage-based charge** | Send events → aggregator → usage product → subscription | Captures consumption; bills only for actual usage |
| **Fixed + usage hybrid** | Add both fixed and usage products to same subscription | Keeps recurring and metered charges on one invoice |
| **Immediate payment** | Set `payment_method_strategy: "current"` on invoice | Uses customer's default payment method |
| **External payment** | Set `payment_method_strategy: "external"` | Manage payment outside Hyperline; record manually |
| **Retry failed payment** | Hyperline retries automatically (2h, 12h, 24h) | No manual action needed; configure fallback methods |
| **Webhook vs. polling** | Set up webhook endpoint for events | Real-time notification; more efficient than polling |
| **Idempotent operation** | Include `Idempotency-Key` header | Safe retries; prevents duplicate charges |

## Workflow

### Create a subscription with usage-based billing

1. **Prepare the customer**: Ensure customer exists via `GET /v2/customers/{id}` or create via `POST /v2/customers`
2. **Send usage events**: Post events to `POST /v1/events/batch` with `customer_id`, `event_type`, `timestamp`, and `record.id`
3. **Create aggregator**: Define how events become billable (count, sum, or SQL formula) in the UI or via API
4. **Create usage product**: Link aggregator to product in catalog; configure pricing tiers
5. **Create subscription**: Call `POST /v2/subscriptions` with `customer_id`, products array, and `activation_strategy`
6. **Activate subscription**: Set `activation_strategy: "start_date"` with future date, or activate manually
7. **Monitor usage**: Query `GET /v2/customers/{id}/usage` to see consumption; check open invoice preview
8. **Verify invoice**: At billing period end, invoice enters grace period, then finalizes for payment

### Create and send a quote

1. **Create quote template** (optional): Pre-configure terms, attachments, and subscription defaults
2. **Create quote**: Call `POST /v1/quotes` with customer, products, and pricing
3. **Add signers**: Call `POST /v1/quotes/{id}/signers` with signer email and role
4. **Send quote**: Call `POST /v1/quotes/{id}/send` to email customer
5. **Track signature**: Listen for `quote.signed` webhook or poll `GET /v1/quotes/{id}`
6. **Activate subscription**: Quote signature auto-activates linked subscription (if configured)

### Handle payment errors

1. **Monitor invoice status**: Listen for `invoice.errored` webhook or poll invoice status
2. **Check error reason**: Hyperline retries automatically on retryable errors (insufficient funds, declined)
3. **Enable fallback**: Configure secondary payment method; Hyperline tries it automatically
4. **Record offline payment**: Call `POST /v1/invoices/{id}/add-payment` with offline payment details
5. **Update payment method**: Customer updates method in portal or via API; Hyperline retries

### Set up webhooks for real-time events

1. **Create endpoint**: Call `POST /v1/webhooks/endpoints` with URL and optional event type filter
2. **Verify signature**: Check `X-Hyperline-Signature` header using webhook secret
3. **Handle idempotency**: Log processed event IDs; skip duplicates
4. **Test endpoint**: Use Testing tab in UI to send example events
5. **Monitor delivery**: Check Logs section for failed attempts; Hyperline retries automatically

## Common gotchas

- **API key leaks**: Treat API keys like passwords; never commit to version control. Revoke immediately if exposed.
- **Sandbox vs. production confusion**: Verify API key prefix (`test_` vs `prod_`) and base URL match intended environment.
- **Missing idempotency key**: Retrying without `Idempotency-Key` header can create duplicate invoices or subscriptions. Always include it for critical operations.
- **Event timestamp in wrong timezone**: Usage events must have UTC timestamps in ISO 8601 format; local times cause events to miss billing periods.
- **Aggregator filters excluding events**: Double-check aggregator filter rules; events matching the filter type but failing filter conditions won't be counted.
- **Subscription not invoicing**: Verify subscription status is `active` (not `pending`, `paused`, or `errored`); check that products have recurring prices; confirm billing interval is set.
- **Invoice stuck in draft**: Invoices created with `status: "draft"` require manual finalization or `issuing_method: "scheduled"` to auto-finalize on issue date.
- **Payment method not available**: Ensure payment provider is connected in Settings > Payments; verify payment method type is enabled for customer's country/currency.
- **Webhook not receiving events**: Verify endpoint URL is publicly accessible and returns 2xx status; check event type filter matches event being sent; review Logs for delivery attempts.
- **Rate limit exceeded**: Hyperline API is rate-limited; implement exponential backoff and monitor `X-RateLimit-Remaining` header. Events ingestion API limited to 1,000 requests per 10 seconds.
- **Deprecated endpoints**: Use `/v2/` endpoints instead of `/v1/` where available (e.g., subscriptions, invoices). Check changelog for deprecation notices.
- **Custom properties not appearing**: Ensure custom property is created before assigning values; use correct slug in API requests.

## Verification checklist

Before submitting work with Hyperline:

- [ ] API key is valid and matches environment (test_ for sandbox, prod_ for production)
- [ ] All required fields are present in request body (e.g., `customer_id`, `activation_strategy` for subscriptions)
- [ ] Idempotency key is included for critical operations (subscriptions, invoices, payments)
- [ ] Timestamps are in UTC ISO 8601 format (e.g., `2025-01-15T10:30:00Z`)
- [ ] Customer exists before creating subscription or invoice
- [ ] Products have prices configured before adding to subscription
- [ ] Subscription status is `active` before expecting invoices
- [ ] Usage events have matching `event_type` and `customer_id` as aggregator and subscription
- [ ] Webhook endpoint URL is publicly accessible and returns 2xx on success
- [ ] Payment method is configured and enabled for customer's country/currency
- [ ] Invoice status is appropriate for action (e.g., `to_pay` before charging, `paid` before marking settled)
- [ ] Batch operations (invoices, events) don't exceed size limits (50 invoices, 5,000 events per request)
- [ ] Error responses are checked; 4xx errors indicate request issues (don't retry); 5xx errors are server issues (retry with backoff)

## Resources

- **Comprehensive documentation**: [docs.hyperline.co/llms.txt](https://docs.hyperline.co/llms.txt) — Full page listing for agent navigation
- **API reference**: [docs.hyperline.co/api-reference](https://docs.hyperline.co/api-reference) — Complete endpoint documentation with request/response schemas
- **Getting started**: [docs.hyperline.co/docs/getting-started/quick-start](https://docs.hyperline.co/docs/getting-started/quick-start) — Setup path from empty account to first invoice
- **Developer guide**: [docs.hyperline.co/developers/getting-started](https://docs.hyperline.co/developers/getting-started) — API fundamentals, authentication, and service endpoints
- **Usage-based billing**: [docs.hyperline.co/docs/usage/getting-started](https://docs.hyperline.co/docs/usage/getting-started) — Events, aggregators, products, and metering
- **Subscriptions**: [docs.hyperline.co/docs/subscriptions/overview](https://docs.hyperline.co/docs/subscriptions/overview) — Subscription model, lifecycle, and billing
- **Webhooks**: [docs.hyperline.co/developers/webhooks](https://docs.hyperline.co/developers/webhooks) — Event types, delivery, retries, and signature verification
- **AI integration**: [docs.hyperline.co/developers/ai/overview](https://docs.hyperline.co/developers/ai/overview) — MCP server, CLI, and LLM documentation access
- **OpenAPI spec**: [api.hyperline.co/openapi](https://api.hyperline.co/openapi) — Machine-readable API specification for code generation

---

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