מסלולים ומסחר
הארכיטקטורה המסחרית
הפרדת מנוי, עמלת שירות, ספק טעינה, מסמכים והנהלת חשבונות.
בעמוד הזה
The owner confirmed on 2026-11-08: monthly or annual subscription, plus a percentage commission on each charging transaction. The customer pays the commission on top of the charging price. On 2026-11-21, the owner approved a uniform 99 basis points (0.99%) before VAT for Personal, Family, Business and Enterprise, recorded in catalog 1.4.0. The approved 20% prepaid annual subscription discount remains limited to Personal, Family and Business. B2B Enterprise retains custom subscription pricing without an automatic annual discount. External collection remains inactive until HYP credentials, terminal verification and provider activation are complete.
The commercial source is lib/commercial-system/spec.json; Product System decision D13 records the confirmation. Open decisions D03/D04/D05/D09 remain applicable to suppliers, activation terms, taxes and lifecycle rules. The approved tiers are now Personal, Family, Business and Enterprise. These replace the earlier proposed Fleet/Scale packaging. Vehicle limits are approved and implemented; launch prices are published, while paid commercial entitlements remain inactive; there is no mandatory per-active-vehicle pricing assumption.
Subscription tiers and payer model — version 2#
The public catalog lives in lib/commercial-system/plans.json. It contains the published monthly prices and explicit annual totals for Personal, Family and Business: 12 monthly subscription prices less the approved 20%, paid in advance. Personal and Family prices include VAT; Business prices exclude VAT. The discount does not apply to charging commission. All four plans have commissionRateBps: 99, before VAT on the service fee. Enterprise annual subscription pricing remains null, to be agreed in a private, tenant-scoped revision; its charging commission is no longer a negotiated override. Publishing a marketing card does not activate a purchasable subscription or grant entitlements; pricingActivation remains not_active. A missing subscription price must never become zero, a free trial or unlimited capacity.
| Plan | Proposed workspace kind | Subscription / payer scope | Capability direction, still subject to approval |
|---|---|---|---|
| Personal | personal | One personal workspace and its billing account | Personal vehicles, provider preferences and spending |
| Family | personal with plan_code=family | One owner account, up to three non-retired vehicles; no additional member logins | |
| Business | business | One business workspace and its legal billing account | Fleet, drivers, charging policy, cost centers and analytics |
| Enterprise | business | One contracted business workspace and its scoped billing account | Explicit commercial terms, reviewed capabilities and service commitments |
Vehicle capacity is explicit: Personal 1, Family 3, Business 10, Enterprise unlimited. This does not promise unlimited API throughput, an SLA or cross-company data access. Catalog prices and fee rates are published, with collection inactive.
Family, identity and privacy#
Family is implemented as kind=personal, plan_code=family: one owner login and up to three non-retired vehicles. Personal has the same ownership boundary with one vehicle. Additional family memberships and invitations are not supported. Business and Enterprise retain role-based multi-user membership. The SQL migration guards vehicle, membership and invitation writes, serializing capacity changes on the tenant row.
Membership invitations must verify the recipient, be single-use and expire. The inviter and accepted invitation must have the same tenant. Membership removal blocks future authorizations immediately; it does not erase the legal payer's existing obligations or abruptly terminate an authorized charging session. Payer transfer needs acceptance of liabilities and a new effective agreement/payment mandate. Additional member sharing, payer eligibility, minors and consent rules remain outside the current single-owner Family scope.
A person may own a Personal or Family account and belong to separate business accounts. The selected workspace scopes vehicles, providers, policy and history. Account plan changes preserve the tenant and all records; they require the owner, enforce capacity and reject personal/family conversion while additional active members or pending invitations exist. No plan selection activates a paid agreement or moves records between accounts.
Versioned contract and activation boundary#
commercialAgreementV2 in pricing.ts validates the approved plan IDs, matching proposed workspace kind, billing account, entitlement revision, explicit period price, commission basis/rate, tax and rounding policy, collection terms and effective dates. V1 remains readable for historical draft evidence; V2 rejects fleet and scale. No active customers are migrated, and old drafts are never silently mapped to new prices or single-owner family account permissions. A data migration would require an inventory of accepted contracts and explicit compatibility rules.
Passing this pure schema is only the first validation step. A future activation service must load the tenant, payer, approved price revision, entitlement revision and consent from the server; enforce composite tenant FKs and immutable scope; reject missing, private-to-another-tenant, expired or unpublished terms; and establish payment or expressly approved invoice credit. Customer owners may accept an offer, but cannot publish rates, invent a zero price, grant themselves credit or activate an unimplemented feature. The contract helper is not wired to an API that activates subscriptions.
Commission resolution and billing lifecycle#
Resolve commission from the accepted effective price/agreement revision of the selected workspace. Catalog 1.4.0 sets 99 basis points before VAT for every plan, including Enterprise. Enterprise subscription pricing and enrollment remain contract-specific; they do not override this charging rate. Do not select another workspace's terms, accept client-supplied rates or fall back to zero. The annual subscription discount leaves the commission unchanged. Historical accepted revisions, attempts and refunds retain their original snapshots.
The current charging-fee implementation uses the frozen canonical provider gross amount from an eligible completed ev1_fleet_sessions record. The additive migration registers only newly inserted sessions after the catalog revision's cutoff in ev1_private.charging_fee_queue; any supplied start/end timestamps must also meet that cutoff. A completion becomes pending only with a provider, provider session ID, start/end timestamps at or after the cutoff, and an explicit provider_amount_finalized_at at or after its end. The trusted service writer must confirm the supplier's final amount; completion with an omitted price or default zero keeps waiting for that confirmation. Updating old sessions or importing historical usage does not enroll them. Missing subscription/payment setup leaves a completion waiting for payment setup. A confirmed genuine zero amount or a fee that rounds to zero is recorded as no_charge, with no minimum fee or payment obligation. The live supplier completion adapter and verified HYP configuration remain prerequisites for real collection. See HYP payments for the queue and worker boundary.
- Generate an expiring quote from a verified provider tariff and effective accepted agreement. Show provider price, percentage, fee base, fee tax, total estimate and approved overrun terms. Actual energy/time can make the final CDR differ from the estimate; unexplained excess requires reconciliation or additional consent under the approved policy.
- Persist the accepted quote and payer/price/entitlement snapshots atomically with the charging intent and durable outbox event. Any future combined authorization for provider energy and service fees requires an explicit supplier settlement integration. The current HYP charging-fee rail collects only the LinkNodes fee and its VAT; it does not settle the provider's gross charging amount.
- Validate and deduplicate final CDRs by provider account, environment, session, revision and payload hash. Build one charging obligation and separate fee/tax lines from the accepted snapshot; tariff corrections produce explicit adjustments.
- Each subscription service period generates its own uniquely keyed obligation, even if no charging occurred. Monthly/annual calendars use explicit anchors, time zone and month-end rules; annual collection is not twelve invented charging sessions. One base-subscription range per workspace must be enforced atomically.
- A verified payment event or approved credit terms governs activation. Renewal jobs, repeated callbacks and unknown capture outcomes use stable keys, transactional event inbox/outbox, row locks/leases and reconciliation. Callback order cannot roll back a later state. Failed payment, invoice issuance and accounting export have independent retries.
- Upgrades/downgrades, proration, renewal consent, cancellation and grace use an approved lifecycle policy and effective revision. Do not issue a paid trial or auto-renew by default. A downgrade that would exceed allowances schedules a resolution; it does not delete family members, vehicles, documents or an active session.
Proposed delivery sequence#
- Approve activation terms for the published monthly/annual offer and fee rates, including tax/rounding/refunds, single-owner family account sharing rules, entitlements, billing cadence and lifecycle policy.
- Install versioned catalog/pricing/agreement/billing-account tables with isolation tests. Account capacity and owner-only changes are implemented in the account plan migration.
- Implement accepted offers and server entitlements; build generic financial events, recurring-period obligations and charging rating. The existing session-only payment/outbox schema must evolve before this step.
- Integrate the chosen PSP, charging operator and invoice provider in their sandboxes; prove duplicate renewal/capture prevention, out-of-order callbacks, unknown outcomes, refunds, credit notes, ledger balancing and reconciliation.
- Roll out paid plans only after accepted terms and tested provider integrations. Account plan selection and capacity are already implemented; paid entitlements remain independently gated.
Financial service boundaries#
flowchart TD
Contract[Price revision and accepted customer agreement] --> Sub[Subscription and service periods]
Contract --> Rating[Charging price and commission calculation]
CDR[Authenticated charging provider CDR] --> Rating
Sub --> Bill[Billing obligations and lines]
Rating --> Bill
Bill --> PSP[Payment attempts and allocations]
PSP --> Invoice[Document provider]
Bill --> Reconcile[Reconciliation]
PSP --> Reconcile
Invoice --> Reconcile
Settlement[Provider settlement facts] --> Reconcile
Reconcile --> Books[Company accounting books and journal]
Books --> Export[Accounting integration and period close]
Sub --> Entitlement[Customer entitlements]
Entitlement --> Eligibility[Role + active membership + selected provider + readiness + policy]
These are ownership boundaries inside the existing Next.js/Supabase application and future durable workers, not an instruction to create seven separately deployed microservices. Production Clerk authenticates a person, database membership scopes the workspace, and the billing account identifies the legal payer. A driver, the employer and the platform legal entity are distinct parties.
- Pricing/contracts: publish immutable revisions and record which tenant accepted them. Private Enterprise revisions are never included in the public price catalog. Changing an agreement creates a new effective revision; historical bills use the original snapshot. Staff pricing authority is separate from customer owner/admin roles.
- Subscriptions: track service period and entitlement independently of a PSP payment attempt. Monthly and annual are explicit billing intervals. An annual price is separately configured; multiplying a monthly price by twelve is not an approved annual offer. Grace, cancellation, renewal and proration remain configurable decisions, not inferred defaults.
- Billing/rating: create a uniquely identified obligation from a subscription period or finalized charging fact. Store separate lines for energy/provider price, LinkNodes commission and applicable taxes, linking each to agreement, tariff/CDR and calculation policy versions. A single payment can settle several obligations; splitting retries must not create new debt.
- Payments: hosted collection/tokenization, authorization, capture, failure, refund and dispute. Verified, scoped provider events establish payment facts. Unknown outcomes enter reconciliation; never retry a possible capture under a new idempotency key. A redirect or successful frontend request does not activate a paid subscription.
- Invoicing: an adapter for the chosen document provider and legal issuer. Document creation has its own idempotency key and external reference. Invoice, receipt and credit note are distinct records; historical issued documents are not silently edited. Do not manufacture legal document numbers in the application.
- Bookkeeping: append-only, balanced company journal by legal entity/book and currency, with customer and provider dimensions. Reversals and corrections link back to originals. Raw company books, clearing accounts and other customers' liabilities are server/staff-only. Tenant owners only read their authorized projections and documents.
- Accounting: reconcile billing obligations, PSP transactions, documents and provider settlements; track exceptions, ownership and age. Export to the selected accounting system with export receipts and idempotency, period locking and controlled correction workflows. Accountant-approved recognition and account mappings are release prerequisites.
Charge calculation and snapshots#
calculateChargePricing is a pure, tested contract helper, with no payment or database side effects. It requires an explicit commission basis (charging_net or charging_gross), commission percentage in basis points, tax on the commission and rounding policy. One hundred basis points is one percent. The current catalog uses charging_gross as the base and 99 basis points before VAT on the service fee. The generic helper retains both basis options and arbitrary historical/synthetic rates; its tests are not a source of current catalog pricing.
The customer total is the original charging net amount + its tax + the commission + commission tax. Subscription fees are not silently added to each session. The helper never deducts the customer commission from the operator's charging amount, but the actual provider payable remains a separate settlement fact under the provider agreement. Do not assume that the whole retail charging amount is payable to a particular counterparty.
All money is integer minor units. Intermediate multiplication uses BigInt; unsafe totals, fractions, negative inputs and unknown fields are rejected. The engineering calculator uses an explicitly labeled proposed half-up-per-line policy. Its test values, including tax rates, are synthetic and are not approved prices or tax advice. A future authoritative quote endpoint must fetch accepted terms from the database; it must never accept an arbitrary price, commission or tax policy from a browser.
The proposed proportional refund helper allocates commission and tax against cumulative refunded charging amounts. Splitting a full refund into several parts cannot increase the refund through repeated rounding. Replaying the same cumulative position produces zero additional refund. This does not establish commercial refund eligibility and is not a substitute for transaction locks, persisted positions, source validation and idempotency in a future refund worker.
Data evolution#
The entities in spec.json are proposed, not installed tables. The existing deployed schema is still the source of truth in lib/systems/dictionary.json (31 tables / 256 columns after the workspace-profile release). No cloud schema is changed by this commercial-model release.
Existing ev1_payments.session_id is mandatory. It cannot represent a subscription payment and must not be populated with a fake charging session. Introduce a scoped billing-obligation and payment-allocation model, then migrate through compatible projections; preserve historical charging payment FKs and reconciliation references. Existing ev1_invoices is a minimal masked/read-only document list, not a legal invoice engine or bookkeeping ledger.
Existing ev1_private.outbox also requires a session. Subscription/invoice/accounting events need a generic financial outbox or a compatible, explicitly versioned aggregate discriminator. Do not reuse a fictitious session to schedule renewals. The relay must claim rows atomically, lease work, retry safely and quarantine exhausted/conflicting events. RabbitMQ transports work; database obligations and posted facts remain authoritative. The relay/worker are not implemented in this release.
Required key scopes include:
| Entity/action | Uniqueness and scope |
|---|---|
| Agreement revision | tenant + agreement + revision/effective range; accepted terms immutable |
| Subscription obligation | tenant + subscription + service period + charge type |
| Charging obligation | tenant + provider + provider session/CDR version + billing adjustment identity |
| Payment attempt | tenant + obligation/allocation + logical action idempotency key |
| Provider callback | provider account/environment + event ID + payload hash |
| Document | issuer + document provider + logical document key; original/credit linkage |
| Refund | tenant + original payment + refund request; cumulative amounts bounded by original |
| Journal posting | company book + source event + posting version; balanced atomically |
| Accounting export | target system/account + journal posting + export version |
Before installation, every proposed customer financial table needs RLS, explicit grants, composite tenant FKs, immutable scope, audited privileged mutations and two-tenant adversarial tests. Financial facts are not editable by a tenant owner. Company ledger and settlement tables default to server/staff access; membership in a customer tenant never grants staff rights. No service-role key or provider secret belongs in a client bundle.
Failure handling and operational controls#
- Price approval without PSP configuration creates no charge. A draft or expired Enterprise offer creates no entitlement.
- Authorization limits include commission/tax and the approved overrun policy. Late CDRs, final amounts above authorization and disputed readings create explicit cases, not silent extra captures.
- A subscription change does not interrupt a charging session already authorized under its price snapshot. Cancellation and downgrade preserve documents and required access to historical records.
- Failed capture, failed document generation and failed accounting export are separate states; retry only the failed step with stable identity. No rollback can undo money already captured at a PSP.
- A correction after period close follows approved reversal/adjustment rules; it cannot rewrite closed books. Reporting includes open discrepancies and unexported postings.
- Annual collection, recognized revenue and MRR/ARR are separate.
normalizedMrrreturns an exact numerator/denominator; it does not create a recognition schedule or ledger entries. Commission revenue is tracked separately from recurring subscription revenue; charging GMV is not automatically platform revenue.
Required decisions before real money#
- Accepted effective monthly/annual subscription revisions and Enterprise subscription terms. The uniform 99-bps charging commission before VAT is approved; subscription terms do not create a different Enterprise charging rate.
- Commission tax basis, tax policies by legal entity, rounding and fee/refund treatment.
- PSP, charging/provider agreements, merchant of record, document issuer/provider and accounting system; principal-versus-agent treatment must be agreed with finance/accounting.
- Renewal, grace, proration, cancellation, net terms, credit limits and dispute workflow.
- Sandbox evidence: repeated and reordered events, failed/unknown captures, duplicate renewal, partial/full refund, documents and credit notes, balanced posting, export retry and reconciliation/close.
No live subscriptions, payment collection, invoice issuance, company ledger, accounting export or automated renewal is enabled by this release. Public product, architecture and data libraries expose this distinction, and the customer billing screen shows the approved model without invented prices or a purchase action.
Packaging and subscription policy revision — 2026-11-09#
The 40-feature catalog in lib/commercial-system/packaging.json separates inclusion by tier from implementation readiness. The full lifecycle proposal lives in lib/commercial-system/subscription-policy.json, with rationale in packaging-strategy.md and generated tables in packaging.md. SSO, SCIM, Premium Support, API and dedicated account success are included in the proposed Enterprise package but remain unimplemented dependencies. Account capacity changes remain distinct from financial subscription changes.
Recommended paid-plan behavior: quoted, verified upgrades; scheduled downgrades and interval changes at the paid period end; revalidated capacity and SSO exit checks; explicit cancellation, renewal, retries, refunds, payer transfers and pilot terms. Amounts, rates, precise proration/refund policy, retry/grace durations and SLA targets still require approval before activation. No billing or entitlement service is installed by publishing these documents.