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