Employee seat billing

Employees are billed through a per-seat add-on, not the plan's users limit — an employee never counts against that limit. The add-on is a dedicated monthly subscription (employee-seats), fully separate from your plan subscription: its quantity tracks the number of active employees, and contracting it activates the control_horario module. All endpoints live under https://api.factuarea.com/v1 and use employees:read (status, preview) or employees:write (subscribe, change quantity, cancel).

How seats are billed

A paid seat covers the whole billing period. The seat count follows your active roster automatically:

• Activating or hiring an employee whose seat is not covered charges a prorated seat for the rest of the period.
• Deactivating an employee releases the seat without a credit (the period is already paid) but keeps their coverage, so reactivating them within the same period is free.
• Each period renewal refreshes the coverage of the currently active employees.

The quantity is kept in sync with the real active count through employee events and an hourly reconciliation, so you rarely need to set it by hand.

Check the billing status

GET /v1/employee-seats returns the add-on status: whether the subscription is active (subscribed), how many seats are billed (quantity), how many employees are active, and the recurring per-seat cost including VAT. Amounts are in cents (minor units) and are null — never a misleading 0 — when the cost is not resolvable (not subscribed, no active plan, enterprise outside Stripe, sandbox).

curl https://api.factuarea.com/v1/employee-seats \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

Preview the charge

GET /v1/employee-seats/preview returns the prorated per-seat amount for activating or hiring, computed from the Stripe upcoming invoice, without charging. It never throws — it degrades to a neutral preview.

amount is the taxable base in cents; requires_payment_method is true when no payment method is on file.

curl -G https://api.factuarea.com/v1/employee-seats/preview \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "count=3"

Subscribe to the add-on

POST /v1/employee-seats/subscribe opts in: it creates the monthly employee-seats subscription with quantity set to your active employees and charges the first period with the payment method on file. The charge is atomic — if it does not go through, nothing is subscribed:

• No payment method → 402 employee_seat_payment_method_required; the error envelope carries error.details.payment_setup_url to complete card setup.
• A declined charge → 402 employee_seat_charge_failed.

curl -X POST https://api.factuarea.com/v1/employee-seats/subscribe \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

Sync the quantity and cancel

POST /v1/employee-seats/change-quantity reconciles the billed seat count to the real number of active employees (a SET with no proration and no invoice). It is idempotent — a no-op when the quantity already matches.

POST /v1/employee-seats/cancel cancels the add-on at period end: the current month is already paid, so subscribed stays true until the period ends, and the per-employee coverage is then purged. The plan subscription is never touched.

curl -X POST https://api.factuarea.com/v1/employee-seats/cancel \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

See the schemas in the API Reference.

Typical flow

1. Preview the charge for the seats you are about to activate.
2. Subscribe to the add-on (first period charged atomically).
3. Add or remove employees — the quantity auto-syncs; reconcile explicitly with change-quantity if needed.
4. Read status to show seats billed and per-seat cost.
5. Cancel at period end when you no longer need it.

Next steps

• Time tracking overview — the portal-only employee role and the whole system.
• Managed companies — per-seat billing for gestoría child companies.