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

# Usage & Billing

> Understand how platform usage is tracked and billed

## Active Merchant Model

SuperSeeded uses an **Active Merchant** billing model. A merchant is marked **Active** (incurring a \$15/month base fee) only upon processing their first **billable document** in a calendar month.

<Info>
  Merchants who don't process any billable documents in a month incur no charges for that month.
</Info>

## What Counts as Billable?

| Document Origin    | Billable | Notes                                                 |
| ------------------ | -------- | ----------------------------------------------------- |
| External upload    | ✅ Yes    | Standard plant schedules uploaded by merchants        |
| SuperSeeded Engine | ❌ No     | Files tagged with `producer: "SuperSeeded_Engine_v1"` |

### The SuperSeeded Origin Exemption

Documents generated by the SuperSeeded Engine are exempt from billing. This enables integrated workflows where your platform generates plant schedules programmatically without incurring processing charges.

<Card title="How It's Detected" icon="magnifying-glass">
  The exemption is detected via the `producer` metadata field in the uploaded file's metadata. Files with `producer: "SuperSeeded_Engine_v1"` are automatically marked as non-billable.
</Card>

## Row Counting

Usage is tracked at two levels: total rows and billable rows.

| Metric            | Description                                                                    |
| ----------------- | ------------------------------------------------------------------------------ |
| **Total Rows**    | All line items processed across all documents (both billable and non-billable) |
| **Billable Rows** | Only rows from billable documents count toward quota and overage               |

### Included Quota

<CardGroup cols={2}>
  <Card title="Base Fee" icon="dollar-sign">
    **\$15/month** per active merchant
  </Card>

  <Card title="Included Rows" icon="table-rows">
    **500 billable rows** per merchant per month
  </Card>
</CardGroup>

Rows beyond the 500 included are billed as overage, calculated in the monthly billing report.

## Usage Tracking Example

Consider a merchant who processes two files in January:

```json theme={"theme":"github-dark"}
// File 1: External plant schedule (billable)
{
  "file_origin": "external",
  "rows_processed": 350,
  "is_billable": true
}

// File 2: SuperSeeded Engine output (non-billable)
{
  "file_origin": "superseed_engine",
  "rows_processed": 200,
  "is_billable": false
}
```

**Result for January:**

| Metric        | Value                               |
| ------------- | ----------------------------------- |
| Is Active     | ✅ Yes (processed billable document) |
| Total Rows    | 550                                 |
| Billable Rows | 350                                 |
| Overage       | 0 (under 500 quota)                 |

## Monthly Reset

<Steps>
  <Step title="New Month Begins">
    All merchant ledgers reset at the start of each calendar month (YYYY-MM format).
  </Step>

  <Step title="Fresh State">
    Each merchant starts the new month with:

    * `is_active: false`
    * `row_count: 0`
    * `billable_row_count: 0`
  </Step>

  <Step title="First Billable Document">
    The first billable document processed in the month sets `is_active: true`, triggering the base fee.
  </Step>
</Steps>

## Monthly Usage Response

When processing a file, the API response includes current month totals:

```json theme={"theme":"github-dark"}
{
  "usage": {
    "is_billable": true,
    "rows_processed": 42,
    "file_origin": "external",
    "month_totals": {
      "month": "2024-01",
      "is_active": true,
      "row_count": 592,
      "billable_row_count": 392
    }
  }
}
```

<ResponseField name="month_totals.month" type="string">
  Current billing month in `YYYY-MM` format
</ResponseField>

<ResponseField name="month_totals.is_active" type="boolean">
  Whether the merchant has been activated this month
</ResponseField>

<ResponseField name="month_totals.row_count" type="integer">
  Total rows processed this month (all documents)
</ResponseField>

<ResponseField name="month_totals.billable_row_count" type="integer">
  Billable rows processed this month (counts toward quota)
</ResponseField>

## Billing FAQ

<AccordionGroup>
  <Accordion title="When is a merchant billed?">
    A merchant is billed when they process their first **billable** document in a calendar month. Non-billable documents (from SuperSeeded Engine) do not trigger activation.
  </Accordion>

  <Accordion title="What happens if a merchant is inactive?">
    Inactive merchants (no billable documents in a month) incur no charges. They can still process non-billable documents without being activated.
  </Accordion>

  <Accordion title="How is overage calculated?">
    Overage = `max(0, billable_row_count - 500)` per merchant per month. Overage rates are provided in your Platform agreement.
  </Accordion>

  <Accordion title="Can I check a merchant's usage mid-month?">
    Yes, every processing response (e.g., `verify-pot-sizes`) includes `month_totals` with current usage. You can also visit your <a href="https://superseeded.ai/account" target="_blank">account page</a> or query the billing API for aggregated reports.
  </Accordion>
</AccordionGroup>