Skip to content
Lark
Join our SlackContact usGet started
Getting started
Quickstart

Quickstart

Setup your billing infrastructure in minutes.

In this guide, we’ll create a hybrid (flat-fee + pay-as-you-go) pricing model, implement Lark’s customer portal and checkout, and start sending usage to Lark.

For this example, we’ll create a monthly pricing plan for an AI chat service that costs $29/month and includes 100 free AI chat requests (then $0.50 per AI chat request).

In Lark, we’ll design this pricing model with two components:

  • A rate card with a $29 fixed rate and a $0.50 usage-based rate with 100 included units
  • A pricing metric to track the number of AI chat requests

Prerequisite: Install and configure the Lark SDK

Section titled “Prerequisite: Install and configure the Lark SDK”

Install the Lark SDK: pip install lark-billing

Configure the SDK with your API key:

Configure the SDK
from lark import Lark


lark_client = Lark(
    api_key=LARK_API_KEY,
)

Step 1: Create a test subject

Section titled “Step 1: Create a test subject”

Subjects are how Lark represents your customers. Typically, you’ll create a subject for each customer when they sign up for your service.

Create a subject
subject = lark_client.subjects.create(
    external_id="1234567890", # optional
    name="John Doe",
    email="john.doe@example.com",
)

Step 2: Build the rate card and pricing metric

Section titled “Step 2: Build the rate card and pricing metric”

Create a pricing metric to track the number of AI chat requests. We’ll use a count aggregation type to track the total number of AI chat requests.

Create pricing metric
pricing_metric = lark_client.pricing_metrics.create(
    name="AI chat requests",
    event_name="ai_chat_request",
    aggregation={"aggregation_type": "count"},
    unit="AI chat request",
)

Test your pricing metric (optional) You can test your pricing metric by sending a usage event and then retrieving the pricing metric summary.

lark_client.usage_events.create(
    idempotency_key=uuid.uuid4().hex,
    timestamp=datetime.now(timezone.utc),
    subject_id="1234567890",
    event_name="ai_chat_request",
    data={"foo": "bar"},
)


summary = lark_client.pricing_metrics.create_summary(
    pricing_metric_id=pricing_metric.id,
    subject_id=subject.id,
    period=lark.Period(
        start=datetime.now(timezone.utc) - timedelta(days=30),
        end=datetime.now(timezone.utc),
    ),
)


print(summary.value) # will be 1 because we sent one usage event

You can create a rate card using the API or the dashboard.

Create a rate card
rate_card = lark_client.rate_cards.create(
    name="Starter plan",
    description="Perfect for small teams.",
    billing_interval="monthly",
    fixed_rates=[
        {
            "name": "Base rate",
            "price": {
                "type": "flat",
                "amount": "2900",
                "currency_code": "usd"
            }
        }
    ],
    usage_based_rates=[
        {
            "name": "AI chat requests",
            "usage_based_rate_type": "simple",
            "included_units": 100,
            "price": {
                "type": "flat",
                "amount": "50",
                "currency_code": "usd"
            },
            "pricing_metric_id": pricing_metric.id
        }
    ],
)

Step 3: Subscribe customer to the rate card

Section titled “Step 3: Subscribe customer to the rate card”

Create a subscription to the Starter Plan rate card. Because the subscription is for a paid plan and the subject does not have a payment method on file, the response will provide a checkout URL to redirect the customer to.

Create a subscription
subscription_response = lark_client.subscriptions.create(
    subject_id="1234567890",
    rate_card_id=rate_card.id,
    checkout_callback_urls={
        "success_url": "https://example.com/success",
        "cancelled_url": "https://example.com/cancelled",
    },
)


print(subscription_response.result.action.checkout_url) # Redirect the customer to this URL to complete the checkout process

Once the customer has completed the checkout, they’ll be redirected back to your platform and their new subscription will be reflected in the billing state.

billing_state = lark.customer_access.retrieve_billing_state(
    subject_id="1234567890",
)


print(billing_state.has_active_subscription) # -> True

Step 4: Send usage events

Section titled “Step 4: Send usage events”

As the customer uses your product, you can send usage events to Lark to track their usage.

lark_client.usage_events.create(
    timestamp=datetime.now(timezone.utc),
    idempotency_key="your-unique-idempotency-key",
    event_name="ai_chat_request",
    subject_id=subject.id,
    data={"value": "1"},
)

Now that your customer is subscribed to a rate card and you are reporting usage, invoices will be generated automatically at the end of each billing period.

(Optional) Expose the customer portal to your customers

Section titled “(Optional) Expose the customer portal to your customers”

Lark’s hosted customer portal lets your customers view their subscriptions, usage, and invoices and manage their billing information.

Create a customer portal session
customer_portal_session = lark_client.customer_portal.create_session(
    subject_id="1234567890",
    return_url="https://example.com/return",
)


print(customer_portal_session.url) # Redirect the customer to this URL to access their customer portal