> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperline.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Automated seat-based billing

> Track seats, licenses, users, or any other quantity in real time as part of your subscriptions

## Concept

Connected seats are an improvement over the existing [seat](docs/products/overview#seat) product. Instead of manually entering the number of units when initiating a subscription, this data is fetched directly from your database. This is especially useful if:

* You want your billing system to reflect any changes made to your product (e.g. a user adds a new license)
* You want to keep track of which seat was added or removed, and when
* You want to bill prorated amounts (e.g. a customer starts with 5 licenses but adds another one mid-year)

## Practical Application

### How to create an automated seat-based product?

<Steps>
  <Step title="Create a seat-based product">
    Navigate to the Products Section for this.

    <Frame>
      <img src="https://mintcdn.com/hyperline/n-I64WmSUBhZI20V/images/usage/usage5.png?fit=max&auto=format&n=n-I64WmSUBhZI20V&q=85&s=6ae617447cffb50c4198ed5bcf149039" width="2378" height="1210" data-path="images/usage/usage5.png" />
    </Frame>
  </Step>

  <Step title="Link an aggregator">
    Select an existing **count** [aggregator](/docs/usage/aggregators) to track your seats. The aggregator determines which events are counted and how incoming data is factored into billing calculations.

    If you haven't created one yet, head to **Usage > Aggregators** to set one up first.

    <Frame>
      <img src="https://mintcdn.com/hyperline/n-I64WmSUBhZI20V/images/usage/connected_seat_metering_configuration.png?fit=max&auto=format&n=n-I64WmSUBhZI20V&q=85&s=efddc109c3f90746acded0c6087a0214" width="2254" height="1922" data-path="images/usage/connected_seat_metering_configuration.png" />
    </Frame>
  </Step>

  <Step title="Click on Create Product">
    That's it! Your seat-based product should now be marked as "**Connected seat**".

    <Frame>
      <img src="https://mintcdn.com/hyperline/n-I64WmSUBhZI20V/images/usage/connected_seat_product_catalog.png?fit=max&auto=format&n=n-I64WmSUBhZI20V&q=85&s=898da2234def241e0054c32f0d1c463a" width="1002" height="924" data-path="images/usage/connected_seat_product_catalog.png" />
    </Frame>
  </Step>
</Steps>

### How to configure connected seats product in subscriptions?

There are four configuration parameters: **Refresh schedule**, **Charging method**, **Invoicing schedule**, and **Seat change policy.**

#### Refresh schedule

* **Realtime**: The `count` updates immediately when a change is detected, instantly if you're using the API, or based on the dataloader interval if you're using loaders.
* **Periodic**: The `count` refreshes based on the interval entered by the user in the Refresh interval field. It's independent of the subscription billing interval but can be matched to it.
* **Manual**: Users must trigger the refresh using the endpoint for a more customized experience.

#### Charging method

Determines how seat changes are billed when detected during the period.

* **Do not charge**: Track seat counts without generating charges.
* **Prorata**: Charge proportionally based on when the change occurred in the period.
* **Full amount**: Charge the full period price regardless of when the change occurred.

#### Invoicing schedule

Controls when invoices are generated after seat changes are detected.

<Note>
  This setting is only available when the charging method is not set to “Do not charge”.
</Note>

* **Immediately**: Hyperline charges (or refunds) the update as soon as it detects it, even in the middle of the period. If selected alongside the “periodic” option, it will simply invoice the customer at every “end” of period.
* **With next invoice**: Hyperline adds the update amounts to the next invoice as additional lines (so if the update is realtime but invoicing is at the end of the month, we'll update the subscription count in realtime but will then add the charge to the next invoice).
* **Custom**: Allows the user to set an invoicing period, for instance, if they have an annual subscription they want to update in realtime but want to charge the update every month.

#### Seat change policy

Determines how increases or decreases in seat count affect billing during the period.

<Note>
  This setting is only available when the charging method is not set to “Do not charge”.
</Note>

* **Standard**: No special handling for seat changes during the period.
* **Charge highest**: Always bill based on the highest seat count detected during the period. Useful to always commit the maximum number of seats.
* **Refund decrease**: Issue a refund when the seat count decreases. Instructs Hyperline to count negative updates as refunds if they've already been paid.

### Managing seat decreases

When a seat is removed (e.g., a user is deleted or a license is revoked), you need to signal this change to Hyperline. Since the API is append-only, you don't delete events directly—instead, you update them with a flag and configure the aggregator to filter them out.

**Using an `active` or `archived` (or what you want) boolean:**

Use a boolean flag to mark the seat as inactive:

```json theme={null}
{
  "customer_id": "<customer_id>",
  "timestamp": "2024-03-15T10:00:00.000Z",
  "event_type": "users",
  "record": {
    "id": 258,
    "email": "user@company.com",
    "created_at": "2024-01-01T00:00:00.000Z",
    "archived": true
  }
}
```

Then, configure the product's [aggregator](/docs/usage/aggregators) to filter out archived seats:

* For a boolean field: add a filter where `archived` **equals** `false`

## Billing calculation examples

Understanding how Hyperline calculates billing adjustments when seat counts change is essential for predicting your invoices. This section walks through concrete examples using a base price of **10€ per seat** with a monthly subscription running from the 1st to the 30th. Those examples do not take into account the settings: `Refund when a decrease in unit count is detected` and `Charge the highest detected value for the period`

### End of period billing

When your subscription is configured to bill at the end of the period, Hyperline calculates the final seat count and applies adjustments for any mid-period changes.

<AccordionGroup>
  <Accordion title="Pro-rata calculation">
    With pro-rata billing, adjustments are calculated proportionally based on when the change occurred during the billing period.

    **Adding seats (60 → 100 seats)**

    You start the month with 60 seats and add 40 seats on the 15th.

    | Item                         | Calculation         | Amount   |
    | ---------------------------- | ------------------- | -------- |
    | Base charge                  | 10€ × 100 seats     | 1,000€   |
    | Update adjustment (Jan 1–15) | -40 × 10€ × 15d/30d | -200€    |
    | **Total**                    |                     | **800€** |

    <Note>
      The adjustment credits back the 40 seats for the first half of the month when they weren't in use.
    </Note>

    **Removing seats (100 → 60 seats)**

    You start the month with 100 seats and remove 40 seats on the 15th.

    | Item                         | Calculation        | Amount   |
    | ---------------------------- | ------------------ | -------- |
    | Base charge                  | 10€ × 60 seats     | 600€     |
    | Update adjustment (Jan 1–15) | 40 × 10€ × 15d/30d | +200€    |
    | **Total**                    |                    | **800€** |

    <Note>
      The adjustment charges for the 40 seats that were used during the first half of the month.
    </Note>
  </Accordion>

  <Accordion title="Pay in full calculation">
    With pay in full billing, seat additions are charged at full price regardless of when they were added, while removals still account for usage during the period.

    **Adding seats (60 → 100 seats)**

    You start the month with 60 seats and add 40 seats on the 15th.

    | Item              | Calculation     | Amount     |
    | ----------------- | --------------- | ---------- |
    | Base charge       | 10€ × 100 seats | 1,000€     |
    | Update adjustment | —               | 0€         |
    | **Total**         |                 | **1,000€** |

    <Note>
      New seats are charged at full price for the entire period, regardless of when they were added.
    </Note>

    **Removing seats (100 → 60 seats)**

    You start the month with 100 seats and remove 40 seats on the 15th.

    | Item              | Calculation    | Amount     |
    | ----------------- | -------------- | ---------- |
    | Base charge       | 10€ × 60 seats | 600€       |
    | Update adjustment | 40 × 10€       | +400€      |
    | **Total**         |                | **1,000€** |

    <Note>
      Removed seats are still charged at full price for the period they were active.
    </Note>
  </Accordion>

  <Accordion title="Do not charge">
    When configured to not charge for updates, no adjustment line items are generated.

    * **Adding seats:** No additional charge (0€)
    * **Removing seats:** No refund or adjustment (0€)
  </Accordion>
</AccordionGroup>

### Start of period billing

When your subscription is configured to bill at the start of the period, you pay upfront based on your current seat count. Adjustments for mid-period changes are applied on the following invoice.

<AccordionGroup>
  <Accordion title="Pro-rata calculation">
    With pro-rata billing, adjustments are calculated proportionally and applied to the next invoice.

    **Adding seats (60 → 100 seats)**

    You start January with 60 seats and add 40 seats on the 15th.

    *Invoice on 1st January (for January period):*

    | Item        | Calculation    | Amount   |
    | ----------- | -------------- | -------- |
    | Base charge | 10€ × 60 seats | 600€     |
    | **Total**   |                | **600€** |

    *Invoice on 1st February (for February period):*

    | Item                          | Calculation        | Amount     |
    | ----------------------------- | ------------------ | ---------- |
    | Base charge                   | 10€ × 100 seats    | 1,000€     |
    | Update adjustment (Jan 15–30) | 40 × 10€ × 15d/30d | +200€      |
    | **Total**                     |                    | **1,200€** |

    <Note>
      **Total for January + February: 1,800€**\
      The February invoice includes the pro-rated charge for the 40 seats added mid-January.
    </Note>

    **Removing seats (100 → 60 seats)**

    You start January with 100 seats and remove 40 seats on the 15th.

    *Invoice on 1st January (for January period):*

    | Item        | Calculation     | Amount     |
    | ----------- | --------------- | ---------- |
    | Base charge | 10€ × 100 seats | 1,000€     |
    | **Total**   |                 | **1,000€** |

    *Invoice on 1st February (for February period):*

    | Item                          | Calculation         | Amount   |
    | ----------------------------- | ------------------- | -------- |
    | Base charge                   | 10€ × 60 seats      | 600€     |
    | Update adjustment (Jan 15–30) | -40 × 10€ × 15d/30d | -200€    |
    | **Total**                     |                     | **400€** |

    <Note>
      **Total for January + February: 1,400€**
      The February invoice includes a credit for the 40 seats removed mid-January.
    </Note>
  </Accordion>

  <Accordion title="Pay in full calculation">
    With pay in full billing, seat changes trigger full-price adjustments on the next invoice.

    **Adding seats (60 → 100 seats)**

    You start January with 60 seats and add 40 seats on the 15th.

    *Invoice on 1st January (for January period):*

    | Item        | Calculation    | Amount   |
    | ----------- | -------------- | -------- |
    | Base charge | 10€ × 60 seats | 600€     |
    | **Total**   |                | **600€** |

    *Invoice on 1st February (for February period):*

    | Item                         | Calculation     | Amount     |
    | ---------------------------- | --------------- | ---------- |
    | Base charge                  | 10€ × 100 seats | 1,000€     |
    | Update adjustment (full Jan) | 40 × 10€        | +400€      |
    | **Total**                    |                 | **1,400€** |

    <Note>
      **Total for January + February: 2,000€**
      The added seats are charged at full price for the previous period.
    </Note>

    **Removing seats (100 → 60 seats)**

    You start January with 100 seats and remove 40 seats on the 15th.

    *Invoice on 1st January (for January period):*

    | Item        | Calculation     | Amount     |
    | ----------- | --------------- | ---------- |
    | Base charge | 10€ × 100 seats | 1,000€     |
    | **Total**   |                 | **1,000€** |

    *Invoice on 1st February (for February period):*

    | Item        | Calculation    | Amount   |
    | ----------- | -------------- | -------- |
    | Base charge | 10€ × 60 seats | 600€     |
    | **Total**   |                | **600€** |

    <Note>
      **Total for January + February: 1,600€**
      A refund is applied for the removed seats from the previous period.
    </Note>
  </Accordion>

  <Accordion title="Do not charge">
    When configured to not charge for updates, no adjustment line items are generated.

    * **Adding seats:** No additional charge (0€)
    * **Removing seats:** No refund or adjustment (0€)
  </Accordion>
</AccordionGroup>

## Explore consumption

In the context of connected seats, consumption refers to the usage of the seat-based product.

You can review this consumption in the dedicated section within the Hyperline platform.

This view provides a comprehensive look at the usage of each seat-based product, allowing for better understanding and management of your billing process.

You can as well review the consumption of a subscription in the subscription timeline.

<Frame>
  <img src="https://mintcdn.com/hyperline/n-I64WmSUBhZI20V/images/usage/usage23.png?fit=max&auto=format&n=n-I64WmSUBhZI20V&q=85&s=79cde7f5de69fcc1079d809a3aa5caed" width="5092" height="2578" data-path="images/usage/usage23.png" />
</Frame>

More detailed information can be found in the [Explore usage consumption section](/docs/usage/explore-usage-consumption).