Skip to content

Describe security subscription as purchase #487

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
maximelb wants to merge 2 commits into from
Closed

Describe security subscription as purchase #487

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9bd9164
Describe Email and Code Security subscription billing
maximelb Oct 5, 2026
09d4036
Clarify when trial coverage becomes billable
maximelb Oct 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
191 changes: 82 additions & 109 deletions docs/7-administration/billing/security-products.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,35 +1,42 @@
# Email Security and Code Security billing

Email Security and Code Security have separate paid coverage. Paying for endpoint
security or another product does not automatically buy either one. Enabling an
extension starts setup; paid coverage requires explicit price acceptance and
confirmation from the protection service.

| Product | Paid rate | New organization trial |
Subscribing to the extension purchases coverage, just like other LimaCharlie
extensions. Email Security uses `ext-email-security`; Code Security is included
in `ext-cloud-security`. On a paid plan, coverage starts automatically when the
organization is subscribed and has a payment method or authorized invoicing.
A paid organization is one that is off the free tier. Review the extension's
pricing when subscribing.

| Product | Paid rate | Free-tier trial |
|---|---|---|
| Email Security | $1 per protected mailbox-month | 14 days, up to 25 mailboxes |
| Code Security | $0.80 per protected repository-month, plus the existing Cloud Security base fee | 14 days, up to 10 repositories |
| Code Security | $0.80 per protected repository-month, plus the Cloud Security base fee | 14 days, up to 10 repositories |

Trials cover the organization across its connections. Shared mailboxes and repeated
references to the same repository count once when they have the same stable identity.
Code includes hosted repositories and external scanner imports; container images do
not contribute to this repository meter. Telemetry and other services remain separately
priced. The console shows the organization's actual Cloud base fee; it is not included
in the $0.80 rate.
priced. Review the Cloud Security base fee in the extension listing before subscribing;
it is not included in the $0.80 rate.

## Trial and coverage

A new trial starts at the first protected resource. Unsubscribing, resubscribing or
restarting a connection does not restart it. Use the server's trial deadline and
A new free-tier trial starts at the first protected resource. Unsubscribing,
resubscribing or restarting a connection does not restart it. Use the server's trial deadline and
coverage status instead of calculating entitlement from a browser clock.

Organizations enabled before billing enforcement receive a fresh 14-day trial from
the enforcement instant. Their existing protected set stays free for those 14 days,
including sets above 25 mailboxes or 10 repositories. This exception preserves the
the enforcement instant. While trial coverage is active, their existing protected
set stays free, including sets above 25 mailboxes or 10 repositories. This exception preserves the
existing set; it does not allow unlimited expansion or swapping in an unlimited number
of new resources. New organizations and growth beyond that baseline follow the normal
limits. Existing paid protection is not silently converted into a new charge without
price acceptance.
limits. Usage while trial coverage is active is free.

Paid coverage starts billing after the protection service acknowledges it. It can
start before the original trial deadline when the subscribed organization is on a
paid plan with a payment method or authorized invoicing. Paid coverage does not
reset the trial history. Returning to the free tier while subscribed can resume
any remaining original trial under its limits; it does not create another trial.

Use Email Security mailbox scope and exclusions to choose coverage. Code's scanning
settings select repository coverage. Review resources that are discovered but not
Expand All @@ -39,83 +46,46 @@ data follow the product's retention policy and scheduled-deletion notices. Revie
those notices before the deadline; paying does not retroactively analyze work missed
while coverage was paused.

## Purchase and check acknowledgement

In **Billing & Usage**, or the product's overview, review trial status, protected
count, limits and the current rates. Add a payment method through the billing page
(or use authorized invoicing), then select the price-acceptance checkbox and
**Activate paid coverage**.

Billing status requires `org.get` and `billing.ctrl`. Changing paid coverage also
requires `user.ctrl`. Analysts without billing permission can still inspect product
coverage and trial information through the product's read surface without access to
payer or financial details.

A request can remain **Pending** while billing or protection reconciles. Do not treat
an HTTP success or a saved configuration as paid coverage. Refresh until the server
reports acknowledged paid protection. A failed or unavailable response does not
establish coverage; correct the payment method or contact support as indicated.
An HTTP 200 mutation with `acknowledged: false` is committed but pending; poll GET
until its control settles and protection matches the requested change. HTTP 503
is retryable after refreshing status and does not confirm paid coverage. Activation
may be temporarily unavailable during rollout while reads and stop remain available.

The billing API uses the same routes for both products:

| Operation | Route |
|---|---|
| Status and cost | `GET /v1/orgs/{oid}/billing/security/{product}` |
| Accept pricing and request activation | `POST /v1/orgs/{oid}/billing/security/{product}` with `{"accept_pricing":true,"accepted_quote":<complete status.pricing_quote>}` |
| Request paid stop | `DELETE /v1/orgs/{oid}/billing/security/{product}` |

`product` is `mail_security` or `code_security`. Optional GET parameters `from` and
`until` must be supplied together as UTC dates `YYYY-MM-DD`. The beginning is
inclusive, the end exclusive, and the maximum range is 366 days. Without a custom
range, use the returned billing period; an invoice interval can differ from a calendar
month. The normalized `status` contains phase, acknowledged protection, trial limits,
pending control, rates and costs. Fields whose authority is unavailable are omitted
or null; do not interpret missing fields as paid or as zero cost.

### Accept the exact quoted price

GET returns `status.quote_guard_version: 1` and `status.pricing_quote`. All nine
quote fields are required: `version`, `quote_id`, `product`, `currency`,
`monthly_cents`, `days_per_month`, `cloud_base_monthly_cents`, `meter_price_id`,
and `cloud_price_id`. Email's Cloud amount is `0` and price ID is an empty string;
these fields are still required. Review the rates and send the entire quote unchanged
in `accepted_quote`. Its opaque ID binds organization, payer and billing mode as
well as prices. It accepts rates, not a fixed future population or monthly total.

If pricing changed, POST returns HTTP 409 `reason: security_quote_changed` before
recording consent or performing purchase effects. Refetch GET, review the new quote,
and obtain fresh consent. The console clears its checkbox. Do not silently accept
a freshly fetched replacement quote. Missing pricing or an unsupported quote guard
pauses purchasing.

With a CLI version supporting quoted purchases, save the quote you will review:

```sh
limacharlie billing security get mail_security --oid <organization-uuid> --output json > security-status.json
python3 -c 'import json; s=json.load(open("security-status.json")); assert s["status"]["quote_guard_version"] == 1; print(json.dumps(s["status"]["pricing_quote"], indent=2))' > accepted-quote.json
cat accepted-quote.json
# After reviewing the quote:
limacharlie billing security activate mail_security --accepted-quote accepted-quote.json --accept-pricing --oid <organization-uuid> --output yaml
limacharlie billing security get mail_security --oid <organization-uuid> --output yaml
# Explicit manual stop; then poll GET for acknowledgement:
limacharlie billing security stop mail_security --confirm --oid <organization-uuid> --output yaml
```

Use `code_security` for Code; its quote also discloses the separate Cloud fee.
The SDK class `limacharlie.sdk.billing.Billing` accepts `Billing(org).activate_security("mail_security", accept_pricing=True,
accepted_quote=reviewed_quote)`, with the complete quote from
`Billing(org).get_security("mail_security")`. Both surfaces preserve pending
responses and API errors instead of claiming that purchase has completed.
## Subscribe and check coverage

In **Extensions**, review pricing and subscribe to Email Security or Cloud
Security. Subscribing on a paid organization with a payment method or authorized
invoicing automatically enables paid coverage. Moving a subscribed organization
from the free tier to a paid plan, or adding a payment method to a subscribed paid
organization, also enables it automatically. Billing begins after paid coverage
is acknowledged; usage while trial coverage is active is free.

A free-tier organization receives the trial and pauses when it expires. To keep
protecting resources after the trial, move the organization to a paid plan and
keep the extension subscribed with a payment method or authorized invoicing.

Billing status requires `org.get` and `billing.ctrl`. Analysts without billing
permission can inspect product coverage and trial information through the
product's read surface without access to payer or financial details.

Coverage can remain **Pending** while billing or protection reconciles. Refresh
status until the protection service acknowledges the transition. A saved
configuration or subscription alone does not prove that protection has started.
If coverage is suspended or unavailable, correct the payment method or contact
support as indicated.

Read billing status and costs with
`GET /v1/orgs/{oid}/billing/security/{product}`, where `product` is
`mail_security` or `code_security`. Optional GET parameters `from` and `until`
must be supplied together as UTC dates `YYYY-MM-DD`. The beginning is inclusive,
the end exclusive, and the maximum range is 366 days. Without a custom range,
use the returned billing period; an invoice interval can differ from a calendar
month. The normalized `status` contains phase, acknowledged protection, trial
limits, pending control, rates and costs. Fields whose authority is unavailable
are omitted or null; do not interpret missing fields as paid or as zero cost.

## How cost is calculated

Each UTC day uses the **highest paid protected resource count** reached that day.
Removing resources later that day does not erase the day's peak. Trials are free;
trial observed counts do not become billable resource-days.
Removing resources later that day does not erase the day's peak. Usage observed
only under trial coverage is free. Once paid coverage begins, the paid protected
count contributes to that UTC day's peak, even if the original trial deadline is
still in the future. Earlier trial-only days are not billed retroactively.

The monthly resource rate is divided by a fixed **30** to price each resource-day.
The billing period sums daily peaks and rounds the resulting period amount; it does
Expand All @@ -132,24 +102,27 @@ still increase. Closed days are settled separately. Accrued cost is an estimate,
a finalized invoice or the total across telemetry, Cloud fees, tax, discounts and
other products. See the invoice for the final amount.

## Stop, payment failure and recovery

**Stop paid coverage** requests an end to future paid eligibility. Check the returned
pending control and refresh until the protection service acknowledges the stop.
Already accrued usage remains payable; the final day's peak is preserved. Stopping
does not reset the trial or immediately erase configuration and data. Any remaining
valid trial or grant can still permit unpaid coverage under its limits.

Stopping Code paid coverage **keeps the separate Cloud Security subscription and
base fee**. Stopping that subscription is a separate operation and also affects Code
eligibility. Do not assume the repository stop removes every Cloud charge.

A first failed payment does not immediately remove existing paid protection. Owners
are notified while Stripe retries, with a maximum seven-day grace. Protection stops
at terminal unpaid/canceled status or the grace deadline. Scheduled cancellation
keeps coverage until its effective end. Payment recovery can resume previously
consented, payment-suspended coverage; it does not undo a voluntary product stop.

Keep the billing contact and payment method current, and inspect pending or suspended
status promptly. Neither a payment-method update nor a callback alone proves that
protection has resumed: verify the authoritative product acknowledgement.
## Unsubscribe, payment failure and recovery

Unsubscribe from the extension to stop future billing. Moving the organization
back to the free tier also stops paid coverage. Refresh billing and product status
until the protection service acknowledges the change. Already accrued usage
remains payable; the final day's peak is preserved. Neither change resets the
trial or immediately erases configuration and data. Any remaining valid trial or
grant can still permit unpaid coverage under its limits while subscribed.

Unsubscribing from Cloud Security stops Code Security coverage and the Cloud
Security base fee. It also affects the other features of that extension. Review
that impact before unsubscribing.

A first failed payment does not immediately remove existing paid protection.
Owners are notified while Stripe retries, with a maximum seven-day grace.
Protection stops at terminal unpaid/canceled status or the grace deadline.
Scheduled cancellation keeps coverage until its effective end. Payment recovery
can resume coverage when the organization remains subscribed and on a paid plan;
it cannot resume an unsubscribed extension or make a free-tier organization paid.

Keep the billing contact and payment method current, and inspect pending or
suspended status promptly. Neither a payment-method update nor a callback alone
proves that protection has resumed: verify the authoritative product
acknowledgement.
16 changes: 10 additions & 6 deletions docs/cloud-security/code-security/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -236,15 +236,19 @@ If a repository stays unscanned, see [Troubleshooting](troubleshooting.md).

## Trial, coverage and billing

Code Security has independent paid repository coverage: $0.80 per protected
repository-month plus the existing Cloud Security base fee. A new organization
Subscribing to Cloud Security purchases Code Security coverage: $0.80 per protected
repository-month plus the Cloud Security base fee. A new free-tier organization
receives a 14-day trial for up to 10 repositories across hosted connections and
external imports. Container images do not contribute to the repository meter.
Existing enabled organizations receive the fresh trial and preserved-set grant
at enforcement; their deadline is not backdated to an old Cloud trial.

In Billing & Usage or Code Security, inspect the canonical trial limit and
acknowledged protection, choose coverage in scanning settings, and explicitly
accept pricing to activate paid coverage. The separate Cloud entitlement and
base fee remain distinct. See [Security product billing](../../7-administration/billing/security-products.md)
Review pricing in Extensions before subscribing. Paid coverage starts
automatically when the organization is off the free tier with a payment method
or authorized invoicing. Usage while trial coverage is active is free; billing
begins after paid coverage is acknowledged. A free-tier organization pauses at
trial expiry; move it to a paid plan to continue coverage. Inspect the
canonical trial limit and acknowledged protection, and choose coverage in scanning
settings. Unsubscribing from Cloud Security stops Code coverage and its Cloud
base fee. See [Security product billing](../../7-administration/billing/security-products.md)
for daily high-water marks, cost calculation, payment grace and stopping coverage.
15 changes: 8 additions & 7 deletions docs/email-security/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,18 +26,19 @@ A **credential** is the key the product uses to access your mail provider. A
**secret** is the securely stored copy of that credential in LimaCharlie. A
**connection** combines that secret with your provider and mailbox choices.

!!! info "Trial and independent paid coverage"
New organizations receive **14 days** for up to **25 mailboxes**, starting
!!! info "Trial and subscription billing"
New free-tier organizations receive **14 days** for up to **25 mailboxes**, starting
at the first protected mailbox. Resubscribing does not restart the trial.
Existing enabled organizations receive a fresh 14-day trial at enforcement
with their current protected set preserved. See
[Security product billing](../7-administration/billing/security-products.md).

Paid Email Security requires explicit pricing acceptance and protection
acknowledgement; endpoint security quota does not buy it. At effective trial
expiry unpaid ingestion may pause and data follows the product's retention
and scheduled-deletion policy. Check actual trial and coverage status rather
than assuming a configuration save establishes protection.
Subscribing purchases Email Security at **$1 per protected mailbox-month**,
divided by 30 per UTC mailbox-day. Paid coverage starts automatically on an
organization off the free tier with a payment method or authorized invoicing.
Usage while trial coverage is active is free; billing begins after paid
coverage is acknowledged. On the free tier, ingestion pauses at trial expiry and data follows the retention and scheduled-deletion policy. Check
actual trial and coverage status to confirm protection has started.

## 1. Enable Email Security

Expand Down
Loading
Loading