Billing & Subscription Management

Overview

Artifi provides a complete billing engine that handles everything from simple customer-specific pricing to complex subscription management with usage-based billing, tiered pricing, and prepaid wallets.

Two complementary systems work together:

• Customer Special Pricing — A pricing lookup table for negotiated rates and discounts
• Recurring Contracts — Full subscription lifecycle management with automated invoicing

---

Choosing the Right Approach

Key Differences

Combining Both

You can use both systems together. For example, a SaaS customer with a volume discount:

1. Customer Pricing gives ACME Corp 20% off — standard API Access is $1,000/month, ACME pays $800
2. Recurring Contract manages the monthly subscription — auto-bills using ACME's special price, tracks usage for overage

The contract system looks up customer-specific pricing first, then falls back to the standard item price.

---

Customer Special Pricing

Customer Special Pricing stores negotiated prices and discounts for specific customers. It answers the question: "What price does this customer pay for this item?"

Use Cases

• Volume Discounts — Key accounts get better rates
• Negotiated Pricing — Contract-based price agreements
• Promotional Rates — Time-limited special pricing with start and end dates
• Price Stability — Lock in prices for specific customers

Pricing Options

Each pricing record can use one of two approaches:

If both are set, the fixed price takes precedence.

Pricing Lookup Hierarchy

When generating invoices, the system looks up prices in this order:

1. Customer-specific pricing (if a record exists for this customer + item)
2. Standard item prices (date-range-based pricing tiers)
3. Default item price (the base price set on the item)

Examples

Fixed Price Override: Widget Pro normally costs $100. ACME Corp has a negotiated price of $80. When ACME orders Widget Pro, the invoice line shows $80.

Percentage Discount: Consulting costs $200/hour. Beta Inc gets 25% off. Their effective price is $150/hour ($200 x 0.75).

Time-Limited Promotion: Enterprise License is $10,000/year. Gamma LLC gets a promotional price of $7,500 from January through June. After the promotion ends, invoicing automatically reverts to the standard $10,000 rate.

Best Practices

• Use effective dates — Set start and end dates for time-limited pricing
• Document agreements — Reference contracts or agreements in the notes field
• Choose one approach — Use either fixed price or percentage discount, not both
• Review periodically — Audit expired pricing agreements regularly
• Entity-specific — Pricing is set per legal entity

---

Recurring Contracts

Recurring contracts automate subscription invoicing on regular billing cycles. They eliminate manual invoice creation and ensure accurate, consistent billing.

Why Recurring Billing Matters

• Automation — Generate hundreds of invoices with a single billing run
• Accuracy — Eliminate invoice errors and missed billings
• Predictable Revenue — Forecast recurring revenue accurately
• Scalability — Handle growing customer base without additional manual work

Key Concepts

How Billing Works

The billing process follows four steps:

1. Contract Setup — Define terms, billing frequency, line items, and pricing
2. Billing Run — Scheduler finds all contracts due for billing on a given date and generates invoices in batch
3. Invoice Generation — For each contract: calculate amounts, apply usage, deduct from wallet if applicable, create the invoice
4. GL Posting — Invoices are posted to the general ledger with proper revenue recognition entries

Contract Lifecycle

Contracts move through these states:

• Draft — Being configured, not yet billing
• Active — Currently billing on schedule
• Suspended — Temporarily paused (no billing occurs)
• Terminated — Cancelled early
• Completed — Ended naturally at the contract end date
• Renewed — Replaced by a new contract

A contract starts as a draft, gets activated when the customer signs, and can be suspended, terminated, or completed from the active state. Suspended contracts can be reactivated.

Contract Lines

Each contract contains one or more line items. Line types include:

---

Billing Runs

A billing run is a batch process that generates invoices for all contracts due on a specific date.

Features

Preview Before Billing

You can preview a billing run before executing it. The preview shows which contracts would be billed and the estimated total amount, without generating any invoices.

Duplicate Protection

If a billing run is accidentally triggered twice for the same date, the system detects existing invoices for each contract/period combination and skips them with a warning. No duplicate invoices are created.

Proration Strategies

Example: A contract starting on January 15 with a $1,000 monthly fee would be prorated to $548.39 for January (17 active days / 31 total days).

---

Usage-Based Billing

For consumption-based pricing, Artifi supports multiple pricing models:

Per-Unit Pricing

A simple rate per unit consumed.

Example: $0.10 per API call. 10,000 calls in a month = $1,000.

Tiered Pricing

Different rates at different volume levels, calculated incrementally.

Example:

• First 5,000 calls: $0.10 each = $500
• Next 5,000 calls: $0.08 each = $400
• Remaining 2,000 calls: $0.06 each = $120
• Total for 12,000 calls: $1,020

Block Pricing

Flat fee based on which usage block the customer falls into.

Example:

• 0–10,000 calls: $500 flat
• 10,001–25,000 calls: $1,000 flat
• 25,001–50,000 calls: $1,800 flat

22,000 calls = $1,000 (falls in the 10,001–25,000 block).

Volume Pricing

A single rate applies to all units based on the total volume.

Example:

• 0–10,000 calls: $0.10 each
• 10,001–50,000 calls: $0.08 each (applies to all units)

15,000 calls = $0.08 x 15,000 = $1,200 (volume discount applies to every unit).

Multi-Dimensional Tier Pricing

For SaaS products where pricing tiers can be triggered by multiple independent metrics (entities, storage, API calls), Artifi supports multi-dimensional tier conditions.

Match Modes:

Example: SaaS Subscription Tiers

A customer with 4 entities and 2.5 GB storage would match the Growth tier at $499/month (since "4 entities" falls in the 3–5 range).

---

Prepaid Wallets

Customers can maintain prepaid credit balances that are automatically deducted during billing.

How Wallets Work

1. Create a wallet for the customer with a currency
2. Credit the wallet (customer pays upfront, e.g., $5,000)
3. Billing runs deduct from the wallet balance before generating an invoice for any remainder
4. Close the wallet when no longer needed (with optional refund)

Use Cases

• Prepaid Credits — Customer buys $10,000 in credits, consumed over months
• Usage Deposits — Ensure payment for usage-based services
• Promotional Credits — Grant free credits for onboarding or promotions

---

Contract Amendments

Contracts can be amended mid-term for upgrades, downgrades, or other changes. The amendment system handles:

• Price changes — Adjust unit prices on existing lines
• Line additions — Add new services to an active contract
• Line removals — Remove services with proration
• Frequency changes — Switch from monthly to quarterly billing
• Proration — Automatically calculate prorated charges or credits for the remaining period

All amendments are tracked with full history, including who made the change, when, and what was modified.

---

Common Use Cases

Simple Monthly Subscription

A customer subscribing to a $1,000/month SaaS platform:

• Create contract with monthly billing frequency
• Add a fixed line for the platform fee
• Activate the contract
• Billing runs generate invoices automatically on the first of each month

Usage + Fixed Hybrid

A SaaS customer paying a base platform fee plus API usage:

• Fixed line: $500/month base fee
• Usage line: API calls at tiered pricing
• Both are included in the same monthly billing run

Prepaid with Usage Deduction

A customer prepays $5,000 and consumes services monthly:

• Create a prepaid wallet with $5,000
• Each billing run calculates the invoice amount and deducts from the wallet
• When the wallet balance is low, the customer can top up

Mid-Term Upgrade

A customer upgrading from the Growth to Scale tier mid-month:

• Amend the contract with the new tier pricing
• System prorates: credits the remaining Growth amount, charges the remaining Scale amount
• Next full billing cycle uses the new tier pricing