CRM

Scope

How to create and manage customers, contacts, activities and deals, and how to read the pipeline and forecast.

Customer management, the subscription-backed account book, contacts, communication log, deals, and the CRM dashboard.

Use Sales Pipeline (the relevant workflow) for Opportunities, Prospects, Forecast, and Sales activities. Use Accounts (the relevant workflow) for commercial agreements, subscriptions, bindings, provisioning, account health, and billing summary. A trial-only prospect appears in both destinations for different jobs. The legacy CRM ?tab=billing entry redirects to the selected Account Terms section and does not render a commercial workspace.

Sales Pipeline has exactly four views: Opportunities, Prospects, Forecast, and Sales activities. It is not an account workspace and does not contain Customers, Contacts, Products & plans, Billing, or Risk & Health tabs. Use the dedicated Communications route for capture-review work and Accounts for commercial and account-health context.

a second CRM workspace. A prospect or trial-only relationship can open that context. A paid or former account redirects to Accounts unless the link carries an exact deal focus, in which case Sales Pipeline shows that deal context and does not expose commercial controls.

CRM: Customers and Pipeline

Customer Records, Account Status, and Deal Stage

When a customer accepts an issued quote, Keystone activates the quoted product agreement through the quote lifecycle. A trial-only agreement remains Prospect; the first immutable standard agreement is what permits a derived Customer status when its current standard agreement is active. The health score (0-100) tracks customer satisfaction; scores below 30 flag churn risk.

Account status is commercial truth, not a manual shortcut. Use the opportunity quote lifecycle or the product-agreement workflow so status, plan, contract, and billing state stay aligned.

Create a Customer

From Sales Pipeline → Prospects, choose New prospect, enter the customer and optional billing details, and choose Create Customer. Open the new prospect before adding relationship records: Add contact creates the named billing, primary, technical, executive, champion, or general contact, and New opportunity creates the product-scoped deal. These are the supported operator actions; API-created customers or deals do not prove that a seller can complete the workflow in the product.

When the selected prospect has an eligible commercial product, New opportunity presents it in the accessible Product selector and safely defaults the first eligible option. Keep that visible default or search and select a different eligible product before creating the opportunity. The visible option list narrows with each keystroke, so Arrow Down then Enter selects from the current search rather than the prior default; a search placeholder is not shown while a product is already selected.

Opening the relevant workflow starts on Opportunities. Select the visible Prospects tab (Enter works when it is keyboard-focused) before choosing New prospect; adding view=prospects to the URL does not select that tab.

The Sales Pipeline tabs also support Left Arrow, Right Arrow, Home, and End. These keys select and focus the destination tab, including when moving out of an open Prospect detail.

Fields:

• name (required) – company/customer name
• lead_source – where the lead came from
• billing_email – for invoicing

Health fields such as health_score are maintained after creation through customer updates and integrations rather than the initial create payload.

Account owner: Customer create and edit now use a searchable assignee lookup backed by active portal users in your tenant. If you do not pick a different owner, the customer defaults to you. Pipeline relationship context and permitted Account context show the current account owner so managers can see who owns follow-up.

Manual duplicate review endpoint:

List Customers

Filters:

• health_min, health_max – filter by health score range
• search – search by customer name, CRM website, or exact numeric customer ID; billing email is not searched
• include_inactive – include archived customers
• limit, offset – pagination (default limit: 50, max: 200)

Total count is returned in the X-Total-Count response header. Keystone’s API exposes this header through its global CORS policy, so the deployed browser UI can distinguish an empty result from a page within a larger customer set. A missing count is treated as an API contract failure and shown as an actionable load error rather than as “no customers.”

The Accounts directory uses the corresponding Accounts projection for commercial work. CRM’s Prospects view uses its own paged relationship/pipeline query, so neither route is a hidden customer-commercial workspace.

Compatibility customer API responses use the customer name as their display label and never include billing email. Open the permission-gated Account context when authorized commercial contact information is needed.

Review Accounts

Permission: keystone.crm.view or keystone.billing.view

Navigation: Customer to cash → Accounts (the relevant workflow)

URL: the relevant workflow

The Accounts directory includes customers with trial or standard agreement history. Account status is derived from immutable agreement classification and current subscription state rather than maintained as a separate editable label:

• Prospect — no standard agreement, including a current or historical trial-only agreement
• Customer — a current active standard agreement
• At risk — no active standard agreement and a current standard agreement is past due, paused, suspended, or pending settlement
• Former customer — standard agreement history exists but no current standard agreement remains

Use Search accounts, Account status, and Subscription status to narrow the full server-side population. Select the Account, Account status, or Last activity heading to change server-side ordering. The visible range and total at the bottom come from the same filtered server query; changing the page size is remembered on this browser.

Exact subscription status is billing-domain information. The Subscription status filter requires keystone.billing.view; Accounts hides and omits that filter for CRM-only operators, and the server rejects an unauthorized filter rather than allowing it to disclose which accounts match a hidden billing state.

Each desktop row and mobile card shows:

• account name, linking to the Account workspace; archived customer records carry an explicit Archived account badge;
• every provisioned tenant binding, including archived bindings shown with muted styling;
• products used and plan history, including cancelled and expired assignments;
• derived account status and the recorded subscription statuses; and
• the latest authoritative account activity timestamp, or No recorded activity when no activity exists.

The Accounts and Billing & AR tab sets remain operable at desktop, tablet, and mobile widths. Keyboard users can focus Billing, press Enter, then focus and activate Open invoices without a pointer. In Billing & AR, Tab moves between the ordered workspace tabs and Enter activates the focused tab; the customer scope from the Account link remains visible in the destination.

keystone.billing.view controls the provisioning and commercial columns. Without it, the account name, derived status, and activity remain available, while Provisioned tenant, Products used, Current plan, and Subscription status show Restricted. Restricted data is not presented as an empty list. If a billing viewer receives incomplete commercial details, the affected field shows Unavailable instead of inferring that no plan or tenant exists.

Accounts distinguishes three outcomes that require different action:

• No accounts yet means the tenant has no customer with subscription history.
• No accounts match these filters means the account book exists but the current server filters matched nothing; use Clear filters to return to the full book.
• Accounts are unavailable means the directory request failed; use Try again. If a refresh fails after a successful load, Keystone marks the retained rows as results from the last successful request rather than claiming they are current.

The accepted immutable dev release verified this route with five distinct actors: trial-only and historical relationships remained prospects, the active standard relationship was a customer, and one reversible sales activity was created and completed. Account list/detail accessibility had zero violations and cleanup removed all disposable actor/private-state authority. The first browser attempt that returned 401 and the corrected cleanup-interpreter invocation remain diagnostics, not successful journey evidence.

The supported browser harness creates the active trial, active standard, and historical Account fixtures inside the same disposable customer tenant as the prepared Accounts actors. The trial lookup must use that dedicated accounts_trial authority; the control-tenant keystone entitlement fixture only establishes workspace access and is not valid Account-search evidence.

Open Relationship Context or an Account

For a prospect/trial-only relationship or specific deal context, open the CRM relationship entry. For agreements, bindings, provisioning, or billing summary, open the Account workspace:

Open it from the customer directory, pipeline customer links, tenant contacts, or the churn-risk panel.

Sales Pipeline view URLs

The Sales Pipeline tab and every list filter live in the URL, so a refresh, a browser Back, or a link you paste to a colleague reproduces exactly the view you were looking at. The parameters are:

Parameter	View	Meaning
forecast_days, forecast_owner	Forecast	window and owner filter

A parameter is omitted when it holds its default, so a clean view has a clean URL. An unrecognized value is ignored rather than applied. Changing a filter sends its list back to page one in the same step, and filter changes replace the current history entry, so Back returns to where you actually navigated from rather than stepping through one entry per keystroke.

Account workspace URLs

Account routes carry the selected company entity in the URL. Once the entity the relevant workflow) land on the same section; only redirect. When you automate or assert on these URLs, match the path and the on section=terms being the last parameter.

Open Products & terms in Accounts for agreement, plan, provider, and next commercial-action context. Trial-only remains Prospect. The first immutable standard agreement, not a trial agreement, controls the subsequent commercial classification.

The Accounts directory exposes current agreement and downstream binding summaries when the operator has keystone.billing.view. Open Products & terms for the customer-local agreement workflow. Keystone does not add a Billing item to the CRM tab bar after customer selection.

Account health shows the score, tier, churn risk, and when it was last scored, followed by the breakdown behind that score: one row per weighted signal (payment behaviour, engagement, support load, contract trajectory, billing health) with its own score, its weight, and the evidence Keystone used. A low score is therefore explainable rather than a bare number. An account that has never been scored says so; it is not shown as a healthy zero.

The workspace replaces the old modal detail pattern and keeps the main CRM actions close to the account:

• edit or archive the customer
• add a contact
• create or advance a deal
• log communication
• review the explicit account owner alongside the rest of the account posture

Create a Deal

The stage list offers only the stages Keystone will accept from the deal’s current stage: on a new deal that is the open pipeline stages, and on an existing deal it is the current stage plus the transitions forward from it. Closing a deal is not a stage change; use the close workflow. If the stage rules cannot be loaded the control is disabled with a retry rather than offering stages the save would reject.

Use New Deal to select an existing customer, product, and optional plan. If the customer is not in the directory, select Create new customer under the customer field; complete the normal customer and duplicate-review workflow, then continue the unchanged deal or contact form with that customer selected.

The expected close date is prefilled with the policy date Keystone would apply anyway: 30 days from today, computed in your company entity’s operating time zone rather than in UTC. Change it to the date you actually expect. The field is required: Create Deal stays disabled while it is empty, because a deal with no expected close date can never appear in an overdue figure. If the stage rules failed to load, there is no policy window to prefill from, so the date arrives blank and you must enter one before creating the deal. The rest of the form still works, so a failed stage-rules fetch costs you one date entry rather than the whole deal.

An API client that omits the field altogether still gets the policy date, and Keystone computes it in the owning entity’s operating time zone, so it matches the date the form would have shown you. Enter the available pipeline context. Record negotiated billing cadence, payment terms, and final commercial terms in the quote so approval, issue evidence, acceptance, and activation share one versioned source of truth.

The workspace shows customer posture plus recent finance-native context in one place:

• deals
• contacts
• communications
• product-scoped subscription states and contract snapshots
• invoice health and outstanding AR
• payment activity
• billing events

Recent sections are intentionally capped for responsiveness, but each section also shows truthful totals so you can tell when you are looking at a recent slice instead of the full account history.

Owner labels are hydrated through a tenant-scoped secondary directory read. If that read fails, Keystone keeps the CRM records and already known labels visible, shows a persistent owner-directory warning, and offers Try again using the same referenced owner IDs and inactive-owner setting. A successful read that cannot resolve a deleted or inaccessible owner continues to show the explicit unavailable owner label; that is different from a transport failure. Use the Account provider recovery state and its returned recovery code before taking a provider-specific action.

Account agreement context carries product identity so mixed-product history stays legible without a second lookup. The Account workspace renders bounded billing posture per permitted product contract rather than collapsing commercial truth into a singleton subscription tile.

Customer click-through is purpose-limited too. A CRM-only viewer sees the account identity, owner, sales posture, health, archive state, and derived account status, but the response omits billing addresses and Stripe customer identity, tax and W-9 identifiers, and QuickBooks identity. Billing view/manage reveals billing customer fields, tax view/manage reveals tax and W-9 fields, and integration view/manage reveals QuickBooks identity. Entity-scoped permissions reveal these fields only for customers assigned to the same company entity. Omission means restricted, not that the customer has no provider or tax record.

Export Customers to CSV

Returns a purpose-limited CRM CSV with ID, name, active state, derived account status, health score, lead source, industry, company size, website, and creation timestamp. It supports account_status, search, and include_inactive filters. The export never includes billing email/address data, Stripe or other provider identifiers, tax/W-9 identifiers, or QuickBooks identity. Use an appropriately permissioned per-customer billing, tax, or integration surface when that domain detail is needed; CRM export does not become a provider-data export when a user has additional permissions.

Update a Customer

Partial update – only send fields you want to change.

account_status is not an editable customer field. It changes only when authoritative subscription state changes.

Archived customers cannot be edited through PUT.

Archive a Customer

Requires keystone.crm.delete permission and a reason in the request body.

Archive is the normal operator path. It hides the customer from active CRM views but preserves the full audit and finance history. The API blocks archive if the customer still has open deals or an active subscription.

Delete a Customer

Requires keystone.crm.delete permission.

Hard delete is now a cleanup-only path. The customer must already be archived, and the API blocks deletion when linked CRM or finance history still exists.

Contacts

Contacts are people associated with a customer.

Tenant-wide contact search:

Account Relationship and permitted prospect/deal context use the paged, search-backed contact contract. Its total is for the full tenant query while rows remain a current-page slice.

List contacts:

Create contact:

Fields:

• name (required)
• is_decision_maker – boolean
• notes

Archived customers cannot accept new contacts.

Update contact:

Delete contact:

Activities & Next Actions

CRM now has a first-class activity queue for forward-looking work. This is separate from the communication log.

Activity workspace endpoints:

Use the Activities tab for the full tenant workspace:

• your next-action queue
• your overdue queue
• a paged activity table with customer and optional deal context

The queue cards still call out that overdue rows are the exception queue, but the next-action queue is no longer due-date sorted only. Keystone now ranks that queue with a finance-native priority overlay:

• fit reflects whether the account and opportunity are worth serious seller time
• intent reflects whether the account is showing current buying or follow-up momentum
• billing context only participates when your role can already view the relevant billing or finance data

Each queue row now shows:

• the combined priority score plus fit and intent inputs
• operator-readable positive or negative signals that explain the strongest ranking drivers
• a next-best-action recommendation tied to current CRM and finance context
• sequence eligibility with explicit blockers when the account should not enter the bounded follow-up path

This is still CRM guidance, not a new outbound engine. The sequence recommendation is read-only and intentionally refuses accounts that are already contracted, stuck in billing trouble, or missing enough opportunity context to justify templated follow-up. Any actual reply or send step still happens in Communications.

Use Sales activities for the tenant activity queue. An exact-deal or prospect/trial relationship context may show the related activity handoff, but can hand off into Communications for that customer. If Communications has no live thread yet, the inbox opens in a truthful empty state instead of dropping you into a hidden compose flow.

Activity fields:

• title (required)
• description (optional)
• due_date (required)

Owner defaults: If you link a deal, the activity owner defaults from the deal owner. Otherwise it defaults from the customer owner, and if neither exists it falls back to you.

Safety rules:

• Archived customers cannot accept new activities.
• Archived deals cannot accept linked activities.
• Priority scoring and sequence guidance are computed from existing records only. Working the queue does not create hidden activity rows, outbound campaigns, or comms-engine sends.
• The CRM handoff still does not bypass communications permissions. Opening the inbox from CRM is allowed for viewers, but any actual reply still requires keystone.comms.send inside Communications.

Communication Log

Track all interactions with customers.

List communications:

Log a communication:

Fields:

• subject, summary

Logging a communication automatically updates the customer’s last_contacted_at timestamp.

Archived customers cannot accept new manual CRM communication entries.

Automatic capture provenance: CRM timelines now distinguish manually logged items from comms-engine capture. Auto-captured rows show provenance such as capture source/mode, linkage basis, and optional linked deal/activity ids. Messages that cannot be linked safely do not guess silently; they stay in a review queue until an operator resolves them.

Capture review queue:

When the comms engine receives an inbound message that cannot be automatically linked to a CRM customer with high confidence, the message enters the capture review queue instead of being silently discarded or guessed. This is the exception-handling path for automatic communication capture.

Where to find it: Use the Communications review tab (the relevant workflow), the dedicated writable review surface.

What each queue item shows:

• Sender and recipient addresses (from_address, to_address)
• Message subject and body preview
• The reason the message needs review (e.g., ambiguous recipient, no customer match, low confidence)
• The number of candidate customer/contact matches the engine found
• The candidate matches themselves, each with customer name, contact name, and the basis for the match (e.g., email_domain, exact_email)

How to resolve a capture review item:

1. Open the review modal from the Communications review tab
2. Select the correct customer from the searchable customer dropdown (the first candidate is pre-selected when available)
3. Optionally select a contact, deal, or activity to provide additional CRM context
4. Optionally override the communication summary
5. Submit the resolution

Customer Conversations (threaded view):

The permitted relationship context can link to the customer’s Conversations record; the canonical communications work remains in Communications rather than a CRM account workspace.

What conversations show:

• Thread subject line
• Status badge (open, closed, archived)
• Message count and last message direction (inbound/outbound)
• Last message timestamp (relative, e.g., “3 hours ago”)
• Assigned rep and group when set
• Thread creation date

Filtering and pagination:

• Conversations are ordered by most recent message first
• Use the “Load more” button at the bottom to progressively load additional conversation threads when the customer has more than 20

Relationship to the communication timeline: The communication timeline (the Communications card in the workspace) shows individual communication events – both manually logged and auto-captured. Conversations are the comms engine’s threaded grouping of related messages. A customer with 50 individual communications might have 5 conversation threads. The two views are complementary: the timeline gives a chronological event log, while conversations give a thread-level overview of ongoing communication flows.

Deals (Sales Pipeline)

Deals track sales opportunities through the pipeline.

New deals must begin in an open pipeline stage. Use Close lost with a reason for lost outcomes. For a potential win, use Create or open quote; quote approval, issue, customer acceptance, and activation are the only operator-facing paid handoff.

List deals (pipeline view):

The CRM pipeline tab now uses this endpoint as a paged workspace instead of a hidden all-deals preload. Dashboard pipeline cards remain tenant-wide, while the table rows below show only the current stage/search/page slice.

Customer and deal owners stay visible in the pipeline and customer views. You do not need to reopen an edit form to see who currently owns follow-up on an account or opportunity.

Create a deal:

Fields:

• name (required) – deal title
• value_cents – non-negative deal value in cents
• expected_close_date
• notes

Creating a deal does not change customer account status. Account status changes only as subscription truth changes; sales progress stays on the deal stage.

Archived customers cannot accept new deals. The backend rejects mismatched product/plan combinations, so a Meridian opportunity cannot quietly quote a Relay plan. The shared CRM UI now requires product selection during deal creation, keeps the optional plan picker scoped to that same product, and shows the product as a locked field during edit so operators do not accidentally mutate the commercial boundary.

Deal owner stays visible after creation. The pipeline table and permitted relationship/Account context show the current owner so managers can spot ownership gaps without reopening the edit form.

Edit a deal:

Open deals can update core pipeline fields. Closed deals only allow updates to notes and closed_reason. Archived deals cannot be edited. The product itself is a commercial boundary and cannot be changed after create; open a new deal if the sold product changes.

Archive a deal:

Requires keystone.crm.delete permission and a reason. Archive removes the deal from the active pipeline while keeping history. Activated or closed_won deals cannot be archived.

Delete a deal:

Hard delete is only allowed after archive, and activated or won deals remain protected.

Advance deal stage:

• qualified: 20%
• demo: 40%
• proposal: 60%
• negotiation: 80%

Stage advancement is now backend-driven workflow automation, not just a stage label change. The transition queues a durable automation run that can create seller follow-up and finance handoff activities, retries safely through the scheduler when side effects fail, and records the automation run id/status in the audit trail. Retries of the same persisted deal transition reuse the original automation run, including concurrent submissions, while a later legitimate transition receives a new run. The CRM activity queue refreshes so the generated work becomes visible in the normal next-action surfaces.

Close a deal:

Body: { "outcome": "lost", "reason": "required reason" }

Create or open the opportunity quote:

1. Select Create or open quote from the opportunity row. Keystone preserves the opportunity and exact company entity in the route.
2. Review or create a product-compatible quote. The quote workspace owns revision, approval, issue, delivery evidence, customer decision, and activation recovery.
3. Treat queued delivery and accepted-but-pending activation as incomplete states. Use the quote workspace recovery action; do not recreate the commercial result through CRM.

The retired CRM conversion modal and its plan/billing-cycle mutation are not operator surfaces. This prevents CRM and Quotes from independently writing the paid won result. Trial and provider-managed outcomes still follow the activation rules shown by the quote workspace; the final account status remains subscription-derived.

CRM Dashboard

Returns:

• total_customers – all active CRM customer records, including prospects; the UI labels this population CRM records
• by_account_status – derived customer-record breakdown by account status
• by_deal_stage – deal pipeline breakdown from Deal.stage
• at_churn_risk – customers with health_score < 30
• pipeline_value_cents – total value of open deals
• weighted_pipeline_value_cents – value weighted by close probability
• active_deals – count of non-closed deals
• recent_communications – communication count in last 7 days

Archived customers are excluded from dashboard customer totals, and archived deals are excluded from pipeline metrics.

If the dashboard endpoint fails, Keystone replaces the summary cards with CRM dashboard unavailable and the specific safe detail returned by the backend. Missing cards in this state mean the tenant-wide totals are unavailable; do not interpret them as zero.

Select Try again to retry explicitly. While the error remains visible, changing CRM tabs or filters or returning focus to the browser tab can also retry the dashboard read. A successful recovery removes the alert and restores the current tenant-wide totals. Keystone does not refresh an already healthy dashboard merely because the browser regains focus.

If repeated attempts fail, preserve the displayed detail and follow the normal support or escalation procedure. Do not manually reconstruct tenant-wide totals from the visible paged customer or deal rows; those tables are not a substitute for the dashboard aggregate.

The “Customers at Churn Risk” panel is a highlight list of up to 20 currently critical accounts, not a full tenant export. Use the Accounts directory when you need the complete filtered account set.

Creating a customer record

Use New Customer to create the CRM identity for a prospect or account. There is no account-status or sales-stage picker: new records derive as Prospect until a standard commercial agreement establishes a non-prospect status. A trial-only agreement remains Prospect. Put sales position on the deal, and use the quote lifecycle or the product-agreement workflow to establish the billing relationship.

Validation and API failures remain visible in the creation dialog. Correct the highlighted field or use the displayed backend reason; a failed request does not create a partial customer.

Forecasting & Pipeline Intelligence

The Forecast view is the manager surface that sits above the dashboard cards:

Use it when you need server-side, assignment-aware answers to questions like:

• what is each rep’s open and weighted forecast?
• which open deals are overdue against expected close date?
• how old is the current pipeline?
• what is the won/lost trend over the last 30, 90, 180, or 365 days?

The owner filter changes the server-side report itself, not just the visible rows in the browser. The view shows:

• summary forecast metrics
• accountability by owner
• pipeline aging buckets
• day-level win/loss trend

Customer edits accept only supported CRM and billing-profile fields. Tenant ownership, record identity, audit timestamps, and archive state are protected; use the dedicated archive workflow to deactivate a customer.