Skip to main content

​
Introduction

Licenses allow you to model generic entitlements in Orb, where usage can be attributed to a unique license for a billing period. The most common application of licenses is to model seat-based pricing in Orb, but can be extended to represent anything from bots, agents, workflows, machines. etc. With licenses, you can:
  • Track per-seat activation rates
  • Report and display individual usage on your customer dashboards
  • Represent seat charges with a dedicated and more full featured billing abstraction
Licenses4

​
Key components

​
License type

A license type is a named pricing component that tells Orb how to attribute usage events to a licensed entity (such as a seat, bot, agent, workflow, machine, etc.). Each license type is defined by a license grouping key – this is a unique event property that identifies which license a usage event belongs to. Example: If your plans have multiple seat types (Pro, Developer, or Free), create one license type per seat type in Orb. Usage events with a key value pair of pro_seat = john_doe will attribute those events to John’s Pro license. License types are configured in Settings, and can be globally used across all plans and subscriptions.
Licenses1

​
License price

A license price is a fixed-fee price that represents the cost of a single entitlement on a subscription. It is explicitly tied to a license type. It defines how much to charge per license per billing period, and the quantity of licenses to provision. Add a license price when creating a new plan to provision licenses on subscriptions. Currently, you can have one license price per plan (and per subscription). License prices can only be configured on plans with fixed fees and unit-based usage prices.
Licenses3
Custom invoice groupings of usage line items is not available for plans with a license price at this time.

​
Usage

To attribute usage to a specific license, your usage events must include both the license grouping key defined by the license type, and the license value for the individual license as a defined property of the event. Orb uses this key value pair to determine which license a usage event should draw down from. Example: If your license type references user_id, a usage event for user John Doe should include:
  • license grouping key: user_id
  • license value: john_doe
Sample payload: 
{
  "idempotency_key": "<key>",
  "event_name": "usage_event",
  "external_customer_id": "<external_customer_id>",
  "customer_id": "<customer_id>",
  "timestamp": "2026-01-01T00:00:00.000000Z",
  "properties": {
    "user_id": "john_doe"
  }
}
Orb will then attribute that usage to the license associated with user_id = john_doe, upon license activation. For help getting started with event ingestion, check out our docs.

​
License lifecycle management

​
License management

When a customer subscribes to a plan that includes licenses, the subscription automatically gains a Licenses tab. This tab is your command center for managing licenses. You can activate, deactivate, and track licenses across the subscription. It also serves as a reporting surface, showing all provisioned licenses and their current status in one place.
Licenses4

​
License activation

Activating a license in Orb is the mechanism by which usage will start being attributed to that license, given a unique license grouping key to register that license. Actual activation time is date aligned – any usage events ingested will be attributed to that license starting at 00:00 of the activation date in your timezone. Example: For a license type that references user_id, activate a license for John Doe by inputting john_doe as the license value. Orb will then attribute that usage to the license associated with user_id = john_doe. This can be done in-app, or programmatically via APIs. Licenses activated immediately become status “Active. Licenses with a scheduled activation date in the future become status “Inactive”, but will become “Active” on the activation date.
License8

​
License deactivation

Deactivating a license in Orb is the mechanism by which usage will stop being attributed to that license at the end of the current day in the customer’s timezone.
Licenses9

​
Operator’s guide

To configure and manage licenses:
  1. Ensure that usage ingested into Orb to includes a license grouping key property.
  2. Create a global License Type in Settings.
  3. Create a new plan, and add a License Price.
  4. Subscribe a customer to a plan with licenses.
  5. Activate and manage licenses for that subscription.