# Khách trả tiền theo kết quả thì bộ đếm của bạn chính là hoá đơn

> Billing đối soát vào cuối kỳ, còn hạn mức phải được kiểm ngay trên từng sự kiện, nên đây là hai hệ thống chạy theo hai nhịp khác nhau.

Bản gốc: https://fdetimes.net/vi/bach-khoa/billing-metering-entitlement-cho-san-pham-ai/

Thử hình dung tuần cuối kỳ thanh toán. Khách hàng gửi ảnh chụp dashboard của họ: agent hỗ trợ khách hàng mà bạn deploy đã "giải quyết" ít cuộc hội thoại hơn nhiều so với con số trên hoá đơn. Họ không hỏi về model hay prompt, mà chỉ hỏi vì sao hoá đơn ghi nhiều resolution hơn số họ tự đếm được.

Với một FDE, đây là lúc billing không còn là việc của phòng tài chính nữa. Khi khách trả theo token hoặc theo kết quả, mỗi sự kiện mà code của bạn phát ra đều là một dòng tiền. Bộ đếm sai thì hoá đơn sai, và niềm tin của khách mất nhanh hơn bất kỳ lỗi kỹ thuật nào.

Việc của bạn là nối hệ thống của khách vào billing sao cho số đếm đúng và hạn mức được giữ. Thêm nữa, khi khách chất vấn, bạn phải chỉ ra được từng con số đến từ đâu.

## Billing và entitlement trả lời hai câu hỏi khác nhau

Billing trả lời câu hỏi "tính bao nhiêu tiền". Entitlement trả lời câu hỏi "khách này còn được dùng tiếp không". Hai câu hỏi nghe giống nhau, nhưng chúng chạy theo hai nhịp hoàn toàn khác.

Tài liệu của Stripe nói rõ rằng usage-based billing cơ bản chỉ đối soát mức dùng vào lúc xuất hoá đơn. Trong suốt kỳ, cả khách lẫn đội của bạn đều không thấy được số dư credit hay tổng mức dùng đang chạy.

Stripe cũng cảnh báo rằng với credit trả trước ở chế độ cơ bản, khách có thể dùng vượt số dư giữa kỳ. Với những integration mới cần số dư theo thời gian thực và trừ dần credit, Stripe hướng người dùng sang Metronome.

Hệ quả rất cụ thể. Nếu hợp đồng ghi "10 triệu token mỗi tháng", ví dụ mà OpenMeter dùng để mô tả một metered entitlement, thì bạn không thể chờ hoá đơn mới biết khách đã vượt mức. Bạn cần một lớp kiểm tra ngay trên đường đi của request, giữ số dư riêng cho từng khách.

**Điểm mấu chốt:** Billing tính tiền sau, còn entitlement phải quyết định ngay trên từng sự kiện.

OpenMeter nối sự kiện usage với entitlement qua một "subject key", tức là khoá trong sự kiện cho biết ai đã dùng tính năng. Chi tiết này nghe vụn vặt nhưng là nơi nhiều integration hỏng. Nếu subject key là user ID trong khi hạn mức đặt theo workspace, số dư sẽ không bao giờ khớp.

## Một cuộc hội thoại, ba hành động, một lần tính tiền

Lấy một ví dụ cụ thể. Giả sử khách trả tiền cho mỗi cuộc hội thoại được agent giải quyết, theo mô hình kiểu Intercom Fin. Intercom định nghĩa một resolution tính tiền theo hai cách: khách xác nhận vấn đề đã xong, hoặc khách rời cuộc hội thoại mà không yêu cầu hỗ trợ thêm. Trường hợp thứ hai được gọi là "assumed resolution".

Intercom còn có một quy tắc nữa: mỗi cuộc hội thoại chỉ tính một kết quả, kể cả khi agent thực hiện nhiều hành động. Giả sử trong một cuộc hội thoại, agent tra đơn hàng, đổi địa chỉ giao hàng rồi gửi mã giảm giá. Nếu code phát một sự kiện cho mỗi hành động, khách bị tính ba lần cho một việc lẽ ra chỉ tính một lần.

Vì thế, đơn vị tính tiền phải là cuộc hội thoại chứ không phải hành động. Bản phác thảo dưới đây cho thấy cách dựng sự kiện:

```python
def build_resolution_event(conv):
    # Chỉ tính khi cuộc hội thoại đã đóng và khớp định nghĩa trong hợp đồng
    if conv.status != "closed":
        return None
    confirmed = conv.customer_confirmed
    assumed = conv.customer_left and not conv.asked_for_more_help
    if not (confirmed or assumed):
        return None
    return {
        "event_name": "resolution",           # trùng tên đã cấu hình trên meter
        "customer_id": conv.billing_customer_id,
        "value": 1,                           # một kết quả cho mỗi hội thoại
        "identifier": f"resolution:{conv.id}",  # idempotency key ổn định
        "timestamp": conv.closed_at,
        "trace": {"conversation_id": conv.id, "rule": "confirmed" if confirmed else "assumed"},
    }
```

Mỗi trường ở đây đều có lý do. Stripe yêu cầu một meter đã được cấu hình, sau đó các meter event phải mang tên sự kiện, customer ID, một giá trị số và timestamp (không bắt buộc). Identifier được dựng từ ID cuộc hội thoại chứ không phải từ thời điểm gửi, nên dù gửi lại bao nhiêu lần thì vẫn chỉ là một kết quả.

Trường `trace` là phần nhiều người bỏ qua. Stigg, một nhà cung cấp hạ tầng pricing, cho rằng mọi sự kiện kết quả phải truy ngược được từ sản phẩm tới hoá đơn. Khi khách gửi ảnh chụp dashboard như ở đầu bài, `trace` cho bạn biết từng resolution được tính theo quy tắc nào.

Một chỗ nên soi trước là nhóm "assumed": kết quả này được suy ra từ việc khách rời đi, nên dashboard của khách có thể không ghi nhận nó như một lần giải quyết.

## Bộ đếm phải chịu được retry, sự kiện đến trễ và đỉnh tải

Stigg viết rằng pipeline usage được thiết kế để giao mỗi sự kiện ít nhất một lần (at-least-once). Nghĩa là trùng lặp chắc chắn sẽ xảy ra, chỉ không biết lúc nào.

Stripe cũng khuyên dùng idempotency key để một sự kiện không bị báo hai lần vì độ trễ mạng hay lỗi khác. Bạn khử trùng lặp ở cả hai đầu: trong bảng outbox của mình và qua identifier gửi lên nhà cung cấp.

Rủi ro thứ hai là thời gian. Stripe xử lý meter event bất đồng bộ, nên tổng mức dùng trên hoá đơn sắp tới có thể chưa phản ánh ngay những sự kiện vừa gửi.

Timestamp cũng phải đủ gần hiện tại. Quan trọng nhất, mức dùng phải được báo trước khi hoá đơn của kỳ đó chốt, nếu không sự kiện có thể vẫn được nhận nhưng không bao giờ được tính tiền.

Rủi ro thứ ba là tốc độ. Endpoint meter event v1 của Stripe giới hạn 1000 lời gọi mỗi giây cho mỗi tài khoản Stripe. Thử hình dung khách chạy agent cho hàng nghìn cuộc hội thoại song song và bạn gửi một sự kiện cho mỗi lần gọi LLM.

Bạn sẽ chạm trần rất nhanh. Có hai cách xử lý: gộp trước theo khách và theo khoảng thời gian rồi gửi tổng, hoặc dùng stream của API v2.

Cuối cùng là sự kiện hỏng. Stripe đưa sự kiện không hợp lệ ra qua webhook báo lỗi và yêu cầu bạn sửa rồi gửi lại. Nếu không ai nghe webhook này, sự kiện hỏng sẽ âm thầm biến mất. Doanh thu bị hụt, và bạn chỉ phát hiện khi đối soát cuối kỳ.

## Làm ở site khách theo thứ tự nào

Bước đầu tiên không phải là viết code. Bạn ngồi với khách và với người làm pricing, rồi viết định nghĩa "một đơn vị tính tiền" thành câu có thể kiểm thử.

Ví dụ: "đóng hội thoại, khách xác nhận hoặc rời đi không hỏi thêm, tối đa một lần cho mỗi hội thoại". Định nghĩa của Intercom cho thấy quy tắc ghi nhận kết quả nằm ngay trong định nghĩa, và mỗi quy tắc như vậy sẽ thành một nhánh `if` trong code.

Tiếp theo, bạn chọn subject key khớp với cấp đặt hạn mức trong hợp đồng, chẳng hạn workspace, tổ chức hay khách hàng. Sau đó dựng một outbox: sự kiện được ghi vào database của bạn trước, kèm idempotency key, rồi một worker đẩy lên billing. Worker này cần biết ngày chốt hoá đơn để báo động khi hàng đợi bị trễ gần mốc đó.

Lớp entitlement đi song song. Stigg mô tả entitlement theo kết quả như một số dư credit bị trừ dần sau mỗi kết quả được xác nhận, và được kiểm lại ở mọi sự kiện. Bạn đặt phần kiểm tra này trên đường đi của request, đọc từ một nguồn số dư theo thời gian thực, thay vì hỏi hệ thống billing chỉ đối soát cuối kỳ.

Cuối cùng là một job đối soát hằng ngày: đếm theo `trace` trong hệ thống của bạn rồi so với tổng phía billing. Chênh lệch nhỏ và ổn định thường là do sự kiện đến trễ. Chênh lệch tăng dần thường là do retry không có idempotency key.

## Những lỗi khiến hoá đơn sai

Lỗi phổ biến nhất là dựng identifier từ thời điểm gửi hoặc từ một UUID sinh mới mỗi lần retry. Khi đó idempotency key chỉ có tên mà không có tác dụng. Lỗi thứ hai là dùng hoá đơn sắp tới làm nguồn số dư để chặn khách. Như Stripe đã cảnh báo, con số đó trễ và khách có thể vượt mức giữa kỳ.

Lỗi thứ ba là phát sự kiện theo hành động trong khi hợp đồng tính theo kết quả. Lỗi thứ tư là không ai nghe webhook báo lỗi. Lỗi thứ năm khó thấy hơn: không lưu quy tắc đã khiến một sự kiện được tính tiền. Đến lúc khách phản đối, bạn không có gì để chỉ ra cho họ.

Về sự nghiệp, đây là kỹ năng nên thể hiện thật cụ thể. Khi đọc tin tuyển dụng FDE ở các công ty AI bán theo mức dùng, hãy để ý các cụm "usage-based billing", "metering" hay "entitlements".

Trong CV, một dòng như "thiết kế pipeline usage idempotent, đối soát hằng ngày với hoá đơn, chặn hạn mức theo thời gian thực" có sức nặng hơn nhiều so với "tích hợp Stripe".

## Bài tập cho tuần này

Lấy một luồng sản phẩm bất kỳ mà bạn đang làm và viết định nghĩa "một đơn vị tính tiền" của nó trong đúng một câu. Sau đó viết một test mô phỏng một cuộc hội thoại có ba hành động và hai lần retry. Test chỉ đạt khi hệ thống ghi đúng một sự kiện, kèm một `trace` mà người ngoài đọc vẫn hiểu.

Nếu bạn làm được việc đó trước khi khách hỏi thì cuộc gọi cuối kỳ sẽ ngắn hơn nhiều: bạn chỉ cần mở bảng đối soát ra cho khách xem.

**Thử ngay tuần này:**

- Chọn một tính năng đang tính tiền theo mức dùng trong hệ thống của bạn và viết ra idempotency key của nó. Nếu bạn không viết được key ổn định qua các lần retry thì đó là lỗi đầu tiên cần sửa.
- Tìm ngày hoá đơn chốt trong kỳ thanh toán của một khách hàng và đo xem sự kiện chậm nhất của pipeline đến muộn bao lâu so với ngày đó.
- Đọc lại tin tuyển dụng FDE bạn đang nhắm tới và gạch chân các cụm 'usage-based billing', 'metering' và 'entitlements'. Sau đó viết một gạch đầu dòng CV mô tả một lần bạn đã làm việc tương tự.

## Nguồn

- [Record usage for billing with the API](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage-api)

- [How usage-based billing works](https://docs.stripe.com/billing/subscriptions/usage-based/how-it-works)

- [Overview | OpenMeter by Kong (Entitlements & Limits)](https://openmeter.io/docs/billing/entitlements/overview)

- [Outcome-Based Pricing: How It Works](https://www.stigg.io/blog-posts/outcome-based-pricing)

- [Fin AI Agent outcomes | Intercom Help](https://www.intercom.com/help/en/articles/8205718-fin-ai-agent-pricing)
