# אסטרטגיית החבילות

> תיעוד מקור. מקור: docs/commercial-system/packaging-strategy.md · 6a466bf.

Proposal prepared on 2026-11-09. The approved vehicle capacities remain Personal 1, Family 3, Business 10 and Enterprise unlimited. Subscription prices, percentage rates, tax basis and service commitments require commercial approval. No paid subscription, SSO, payment provider or new entitlement is activated by this release.

## Value and buying decisions

- **Personal — convenience for one driver.** Keep discovery, provider selection, registration lookup, vehicle history, spending and savings estimates together. Basic security and useful exports belong in the core experience.
- **Family — one household budget.** One owner account bundles up to three vehicles. The differentiator is household visibility and planned shared spending alerts, rather than separate member logins. Recommend a bundle that costs less than three separate Personal subscriptions; validate the economics before publishing any price.
- **Business — operating control.** Bundle up to ten vehicles, driver roles, cost centers, policy configuration and business analytics. Recommend including the necessary management/driver roles without a separate seat fee. Planned priority support, recurring reports and employee reimbursement increase operational value. Active charging-policy enforcement remains dependent on provider integration.
- **Enterprise — organizational integration and service.** Unlimited vehicle capacity, with SSO/SAML/OIDC, SCIM, API/webhooks, BI/accounting connectors, audit export, Premium Support and a named success contact in the proposed package. SSO and premium support are part of Enterprise packaging, not undisclosed mandatory add-ons. Define supported IdPs, API quotas, connector scope, SLA targets, critical-incident coverage and onboarding deliverables in the contract. Custom development and complex migrations may be separate one-time line items.

Upgrade triggers are deliberately broader than vehicle count: a small fleet needing corporate SSO or API access can choose Enterprise. A fourth household vehicle or business role requirements lead to Business; an eleventh business vehicle leads to Enterprise. No automatic overage purchases or hidden per-vehicle charges are proposed.

## Pricing mechanics to evaluate

Use a base monthly or annual account subscription plus the customer-paid percentage commission on each charging session. Recommend progressively stronger bundled value and potentially lower commission percentages for larger plans, subject to actual supplier margins, payment costs and support costs. Do not publish a decreasing fee promise until each price revision is approved.

An annual plan should have its own explicitly approved total price and may offer a discount. Display any monthly equivalent as informational, with the actual annual collection amount and cadence equally visible. Do not assume a percentage discount, a free month, or a refundable balance.

For a purely illustrative economic comparison, the pre-tax monthly charging spend at which an upgrade pays for its higher subscription is `(new subscription - old subscription) / (old commission fraction - new commission fraction)`, only when the denominator is positive and the tariff/basis/period are comparable. Include taxes and eligibility before using this in a customer quote. The current site cannot calculate savings because no prices or fee rates are approved.

Enterprise quotes should separate recurring platform subscription, the agreed percentage fee, any expressly approved usage commitments and scoped one-time implementation work. “Unlimited vehicles” does not imply unlimited API throughput, arbitrary integrations, no fair-use limits or unlimited custom development. Never charge per-vehicle overage against the advertised unlimited capacity.

Suggested future commercial experiments: compare Family take-up with two or three separate Personal subscriptions, evaluate annual conversion without masking renewal dates, and evaluate Business willingness to pay for controls. Measure activation, conversion, retained accounts, net recurring revenue, charging spend, effective commission yield and contribution margin after PSP/support costs. Do not optimize solely for vehicle count or gross charging volume.

## Subscription contract and edge cases

The machine-readable proposal is `lib/commercial-system/subscription-policy.json`; the generated [full handbook](/packaging-handbook) covers all twelve lifecycle scenarios. Policy proposals are distinct from the current owner-only account-type selector, which is unpaid and takes effect immediately subject to database capacity checks.

For future paid subscriptions:

1. Store immutable plan, price, entitlement and legal-policy revisions. A request from the browser is an intent, not authority to publish prices or grant access.
2. A change quote records old/new plan, interval, effective time, current subscription revision, payer, tax/rounding policy and credit/debit lines. Expire and reissue stale quotes. A quote must state whether existing credit is refundable or only applies to future service.
3. For an immediate upgrade, credit the unused portion of the already paid service and charge the new unused portion only under an approved proration rule. Calculate in integer minor units with documented rounding and explicit period boundaries. Preserve the original session's commission snapshot. Net-zero changes still require accepted terms; they cannot infer an undocumented free price.
4. Schedule a downgrade or billing-interval change at the end of the paid period. Keep a single pending change with explicit replacement/cancellation semantics. Recheck limits and roles under the same tenant lock at activation. If the customer added more vehicles after scheduling, block the downgrade, notify the owner and seek a decision. Do not silently renew a more expensive plan or silently delete vehicles.
5. Enterprise exit requires tested alternate administrator login before disabling enforced SSO, appropriate SCIM deprovisioning behavior and review of API/service-account dependencies. Preserve audit and financial history. Customer access to mandated billing records must survive plan changes.
6. Payer changes, legal-entity transfers and moves between customer and employer are separate workflows. Obtain new acceptance and payment mandates without relabeling old invoices or exposing private history to a new team.
7. Distinguish subscription status from scheduled cancellation: an active paid service can have `cancel_at_period_end=true`. At the effective end it expires/cancels according to the agreed state model. Trial, grace, retry, renewal-notice and retention durations are explicit configuration, not hidden code defaults.
8. Payment failure does not terminate an already authorized charging session. An unknown payment outcome requires reconciliation before retry. Signed events must be deduplicated and ordered against server state; a late success cannot revive a superseded subscription or apply a canceled change.
9. A refund uses cumulative original-charge limits and separate subscription, energy, commission and tax allocations. Issued documents remain immutable; issue corrective documents through the selected legal document provider. A ledger credit and a PSP cash refund are different events.

## Delivery and authorization

`packaging.json` is the source of proposed commercial inclusion and readiness labels. The website comparison, plan-card highlights and downloaded handbook read the same catalog. Its statuses are:

- `available`: existing product capability; operational data appears only where records exist.
- `integration`: live behavior depends on a provider or financial integration.
- `planned`: not yet implemented or operated, even if included in a package proposal.

An effective entitlement must combine the signed agreement, active membership/role, implementation readiness, required integration and tenant scope. The catalog must never be imported as an authorization shortcut that unlocks every feature marked “included.” Existing owner account-plan changes remain separate from future paid activation. Do not sell an unimplemented feature as immediately available.

Before financial activation, choose providers, approve terms/prices, implement idempotent server workflows, test cross-tenant access and replay/concurrency cases, complete reconciliation and document issuance, and run an agreed pilot. Before Enterprise SSO launch, verify tenant/domain binding, JIT/SCIM roles, administrator fallback, offboarding and the identity-provider integration. Before Premium Support launch, establish staffing, escalation, incident severity definitions and measurable contract commitments.
