Domain Model

A high-level overview of the relationship between core Kable concepts

In the sections that follow you will learn more about the following entities on Kable:

  • Dimensions are metrics that are meaningful to your business.
  • Aggregations define how a given dimension metric is evaluated.
  • Usage Events capture information about things that happen in your API.
  • Plans determine how customers are billed.
  • Price Tiers define how a given plan is priced.
  • Bundles are collections of plans that facilitate management of plans across customers.
  • Credits are an abstraction over currency that allow for flexible pricing models.
  • Customers are the consumers of your API.
  • Customer Plans are the plans to which a given customer is subscribed.
  • Invoices are statements of products or services sold to a customer.
  • Alerts are triggered when a customer's usage exceeds a given usage threshold.

Entity Relationships

Kable takes a fine-grained approach to designing metrics, plans, and invoices. This allows you to re-use plans across customers while still having granular control to define one-off rules for new enterprise contracts.

Plans and Pricing

  • Each Plan corresponds to a single Dimension
  • Each Plan can have multiple Price Tiers
  • Each Plan corresponds to a single Invoice Line Item
  • Each Bundle can contain many Plans

Customers and Invoices

  • Each Customer can be subscribed to multiple Plans as Customer Plans, which may or may not be part of a Bundle
  • Each Invoice is generated for a single Customer
  • Each Invoice contains multiple Invoice Line Items, each corresponding to a Customer Plan


An in-depth example

To put things into context, let's consider the sample use case of Mailman, a messaging API company, that we'll refer to throughout this documentation.

Let's assume for the purposes of this example that Mailman wants to charge its customers $100/month as a base plan that includes up to 10,000 text messages and up to 5,000 distinct contacts. After 10,000 text messages, Mailman will charge $0.10 per additional text message, and if a customer goes over their 5,000 contact limit, Mailman will charge an additional $30.

Here's a breakdown of what Mailman might configure on Kable:

  • Mailman might create a dimension called "Text Message" with a key of messageId to track the number of text messages a customer sends. They might also create a dimension called "User" with a key of userId to track the distinct users or contacts to which text messages are sent.
  • Mailman would create the following Plans:
    • a Base Plan that costs $100/month
    • a Plan based on the COUNT of Text Messages with two Price Tiers:
      • Flat $0 for 0 to 10,000 messages
      • Unit $0.10 for 10,001 to ∞ messages
    • a Plan based on the DISTINCT COUNT of Users with two Price Tiers:
      • Flat $0 for 0 to 5,000 users
      • Flat $30 for 5,001 to ∞ users
  • Mailman might also create threshold alerts to help notify customers as they approach their plan quotas. They might set up an alert to fire when a customer sends their 9,000th text message or when a customer reaches their 4,000th distinct user. They might handle these usage.exceeded webhooks to message their customers or to notify their sales team that it might be time to upsell a given customer.

You can learn a lot more about each of the core Kable domain entities in the sections that follow. If you have any questions please don't hesitate to reach out.