Enterprise billing

Enterprise billing comes with unique challenges: negotiated contracts, volume discounts, custom pricing terms, multi-year commitments, and complex approval workflows. Lark provides the flexibility to handle all of these scenarios while keeping your billing logic maintainable.

What makes enterprise billing different

Enterprise customers typically expect:

• Custom pricing: Negotiated rates that differ from your standard plans
• Volume discounts: Tiered pricing or percentage-based discounts based on commitment levels
• Contract terms: Annual or multi-year contracts with scheduled price changes
• Seat-based licensing: Per-user pricing with quantity commitments
• Usage commitments: Minimum spend or usage guarantees with overage billing
• Hybrid models: Combining flat fees with usage-based charges

Lark’s concepts of rate cards, discounts, and scheduled changes makes it straightforward to implement all of these patterns.

Custom pricing with price multipliers

Rather than creating a separate rate card for each enterprise customer, you can use a standard Enterprise rate card and apply rate_price_multipliers to give each customer their negotiated discounts. This keeps your rate card catalog manageable while supporting custom pricing.

First, create a standard Enterprise rate card with your list prices:

SDK

Create a standard enterprise rate card

enterprise_rate_card = lark_client.rate_cards.create(
    name="Enterprise",
    description="Enterprise plan with annual billing.",
    billing_interval="yearly",
    fixed_rates=[
        {
            "name": "Platform fee",
            "code": "platform_fee",
            "price": {
                "type": "flat",
                "amount": "500000",  # $5,000/year list price
                "currency_code": "usd"
            }
        },
        {
            "name": "Seats",
            "code": "seats",
            "price": {
                "type": "flat",
                "amount": "12000",  # $120/year per seat list price
                "currency_code": "usd"
            }
        }
    ],
    usage_based_rates=[
        {
            "name": "API requests",
            "code": "api_requests",
            "included_units": 1000000,  # 1M requests included
            "price": {
                "type": "flat",
                "amount": "1",  # $0.01 per request list price
                "currency_code": "usd"
            },
            "pricing_metric_id": api_requests_metric.id
        }
    ],
)

Dashboard

1. Go to the rate cards page and click “New Rate Card”.
2. Fill in the details:
   • Name: Enterprise
   • Description: Enterprise plan with annual billing.
   • Billing Interval: Yearly
3. Add a fixed rate for the platform fee:
   • Name: Platform fee
   • Code: platform_fee
   • Price: $5,000.00
4. Add a fixed rate for seats:
   • Name: Seats
   • Code: seats
   • Price: $120.00
5. Add a usage-based rate for API requests:
   • Name: API requests
   • Code: api_requests
   • Included Units: 1000000
   • Price: $0.01
6. Click “Save”.

Then, when subscribing an enterprise customer, apply their negotiated discounts using rate_price_multipliers:

SDK

Subscribe with negotiated enterprise pricing

subscription = lark_client.subscriptions.create(
    subject_id="acme_corp",
    rate_card_id=enterprise_rate_card.id,
    fixed_rate_quantities={
        "seats": 250,  # 250 seats
    },
    rate_price_multipliers=[
        {"platform_fee": 0.85},  # 15% discount on platform fee
        {"seats": 0.80},         # 20% discount on seats
        {"api_requests": 0.70},  # 30% discount on API usage
    ],
)

Dashboard

1. Go to the subjects page and click on the enterprise customer.
2. Click on the “Subscriptions” tab.
3. Click “New Subscription”.
4. Select the Enterprise rate card from the dropdown.
5. Set the seat quantity to 250.
6. Add price multipliers for each rate:
   • platform_fee: 0.85 (15% discount)
   • seats: 0.80 (20% discount)
   • api_requests: 0.70 (30% discount)
7. Click “Save”.

This approach lets you maintain a single Enterprise rate card while applying customer-specific discounts. Each customer gets their negotiated rates, and discounts are preserved when they upgrade seats or modify their subscription.

Seat-Based Enterprise Licensing

Many enterprise contracts include a committed number of seats with the ability to add more as needed.

Setting initial seat quantities

Subscribe with committed seats

subscription = lark_client.subscriptions.create(
    subject_id="enterprise_customer",
    rate_card_id=enterprise_rate_card.id,
    fixed_rate_quantities={
        "seats": 100,  # Committed to 100 seats
    },
)

Usage commitments with overage billing

Enterprise contracts often include usage commitments, a minimum amount of usage included in the base price, with additional charges for overages.

The included_units field on usage-based rates makes this straightforward:

Rate card with usage commitment

enterprise_rate_card = lark_client.rate_cards.create(
    name="Enterprise with API Commitment",
    billing_interval="monthly",
    fixed_rates=[
        {
            "name": "Platform access",
            "code": "platform_access",
            "price": {
                "type": "flat",
                "amount": "1000000",  # $10,000/month includes usage commitment
                "currency_code": "usd"
            }
        }
    ],
    usage_based_rates=[
        {
            "name": "API calls",
            "code": "api_calls",
            "included_units": 5000000,  # 5M calls included in platform fee
            "price": {
                "type": "flat",
                "amount": "2",  # $0.02 per call for overages
                "currency_code": "usd"
            },
            "pricing_metric_id": api_calls_metric.id
        }
    ],
)

The customer pays $10,000/month and gets 5 million API calls included. Any usage beyond that is billed at $0.02 per call.

Dynamic included units

For enterprise contracts where included usage scales with other quantities (like seats), you can use included_units_function to define a formula.

Dynamic included units are currently in private beta. Contact us at team@uselark.ai to get early access.

For example, to include 100 AI chat requests per seat:

Rate card with dynamic included units

enterprise_rate_card = lark_client.rate_cards.create(
    name="Enterprise per-seat",
    billing_interval="monthly",
    fixed_rates=[
        {
            "name": "Seats",
            "code": "seats",
            "price": {
                "type": "flat",
                "amount": "10000",  # $100/month per seat
                "currency_code": "usd"
            }
        }
    ],
    usage_based_rates=[
        {
            "name": "AI chat requests",
            "code": "ai_chat_requests",
            "included_units_function": "{{fixed_rate_quantities.seats}} * 100" # 100 AI chat requests per seat
            "price": {
                "type": "flat",
                "amount": "50",  # $0.50 per AI chat request for overages
                "currency_code": "usd"
            },
            "pricing_metric_id": ai_chat_requests_metric.id,
        }
    ],
)

With this configuration, a customer with 10 seats gets 10 million API calls included. If they add more seats mid-cycle, their included usage automatically increases.

You can also override included_units_function at the subscription or contract phase level for customer-specific terms:

Override included units on a subscription

subscription = lark_client.subscriptions.create(
    subject_id="enterprise_customer",
    rate_card_id=enterprise_rate_card.id,
    fixed_rate_quantities={"seats": 50},
    included_units_function={
        "api_calls": "{{seats.quantity}} * 2000000"  # 2M per seat for this customer
    }
)

Multi-year contracts with scheduled changes

Enterprise contracts often span multiple years with pricing that changes over time. The contracts API allows you to define multiple phases with different rate cards and price multipliers for each phase.

The contracts API is currently in private beta. Contact us at team@uselark.ai to get early access.

Multi-year contract with ramped pricing

contract = lark_client.contracts.create(
    subject_id="subj_VyX6Q96h5avMho8O7QWlKeXE",
    phases=[
        {
            # Phase 1: 50% discount during onboarding
            "period": {
                "start": "2025-01-01",
                "end": "2025-07-01"
            },
            "rate_card_id": "rc_AJWMxR81jxoRlli6p13uf3JB",
            "rate_price_multipliers": {
                "base_fee": 0.5
            }
        },
        {
            # Phase 2: 25% discount
            "period": {
                "start": "2025-07-01",
                "end": "2025-10-01"
            },
            "rate_card_id": "rc_AJWMxR81jxoRlli6p13uf3JB",
            "rate_price_multipliers": {
                "base_fee": 0.75
            }
        },
        {
            # Phase 3: Full price
            "period": {
                "start": "2025-10-01",
                "end": "2026-01-01"
            },
            "rate_card_id": "rc_AJWMxR81jxoRlli6p13uf3JB",
            "rate_price_multipliers": {
                "base_fee": 1
            }
        }
    ],
    metadata={
        "salesforce_id": "1234567890"
    }
)

Use contract phases to model ramped pricing, free trial periods, annual price increases, or mid-contract upgrades that have been negotiated in advance.

Dimensional pricing for enterprise

Enterprise customers with diverse workloads may need pricing that varies by dimension—such as region, environment, or service tier.

First, create a dimensional pricing metric:

Create a dimensional pricing metric for compute

compute_metric = lark_client.pricing_metrics.create(
    name="Compute hours",
    event_name="compute_usage",
    aggregation={"aggregation_type": "sum", "field": "hours"},
    dimensions=["region", "instance_tier"],
)

Then, when reporting usage, include the dimension values:

Report dimensional usage

lark_client.usage_events.create(
    event_name="compute_usage",
    subject_id="enterprise_customer",
    timestamp=datetime.now(timezone.utc),
    idempotency_key="compute_job_12345",
    data={
        "hours": "24.5",
        "region": "us-east-1",
        "instance_tier": "high-memory",
    },
)

This allows you to bill at different rates for different regions or instance types, which is common in infrastructure and cloud services.

Managing enterprise customers at scale

Organizing with subjects

Create a subject for each enterprise customer with relevant metadata:

Create an enterprise subject

subject = lark_client.subjects.create(
    external_id="acme_corp_salesforce_id",
    name="Acme Corporation",
    email="billing@acme.com",
)

Subject hierarchies for teams and departments

For large enterprises, you often need to track usage and pool credits at different organizational levels—such as by team, department, or cost center.

Subject relationships are currently in private beta. Contact us at team@uselark.ai to get early access.

Use parent_subject_id to create a hierarchy of subjects:

Create a subject hierarchy

# Create the parent enterprise account
enterprise = lark_client.subjects.create(
    external_id="acme_corp",
    name="Acme Corporation",
)

# Create departments under the enterprise
engineering = lark_client.subjects.create(
    external_id="engineering_dept",
    name="Engineering",
    parent_subject_id=enterprise.id,
)

# Create teams under departments
backend_team = lark_client.subjects.create(
    external_id="team_123",
    name="Backend Team",
    parent_subject_id=engineering.id,
)

This hierarchy allows you to:

• Pool credits at different levels (enterprise, department, or team)
• Track spend/usage at each level
• Report usage rolled up by organizational structure

Customer portal for enterprise

Enterprise customers can manage their subscriptions, view invoices, and analyze usage through the hosted customer portal:

Generate customer portal link

portal_session = lark_client.customer_portal.create_session(
    subject_id="acme_corp_salesforce_id",
    return_url="https://yourapp.com/billing",
)

# Redirect customer to portal_session.url

Tracking usage across the enterprise

For use-cases beyond the scope of the standard customer portal, you can use pricing metric summaries to provide enterprise customers with detailed usage reports:

Generate usage report for enterprise customer

usage_summary = lark_client.pricing_metrics.create_summary(
    pricing_metric_id=api_calls_metric.id,
    subject_id="enterprise_customer",
    period_granularity="day",
    dimensions=["region", "instance_tier"],
    period={
        "start": "2025-01-01",
        "end": "2025-02-01",
    },
)

Best practices

• Use consistent rate codes: When creating custom enterprise rate cards, use the same code values across rate cards. This ensures quantities and discounts carry over when customers upgrade or change plans.

• Version your rate cards: Create new rate card versions for price changes. Lark automatically migrates customers to the latest version.