How to Safely Delete a Salesforce Custom Field: Restore Plan

Executive Summary

This report answers one narrow question: once an inventory has nominated a single Salesforce custom field for removal, what evidence justifies keeping it, deprecating it for an observation period, or approving deletion, and can the team really restore it? The worked example is a fictional field in a Winter ’27 sandbox on API version 68.0, the version Salesforce's developer blog says Winter ’27 ships ^[1], with production orgs upgrading across several weekends, so each org's date should be checked against the Salesforce maintenance calendar. Nothing here is a new Winter ’27 feature: deletion, the deleted-fields list and manual restoration are long-standing behavior.

The central finding is that an empty field is not an unused field. Practitioner guidance lists integrations that populate then clear a field as one reason ^[2], and a vendor post on AI agents warns about an agent that sees an empty field and assumes it is unused (Source: elements.cloud). Database semantics agree: PostgreSQL documents that the null value represents an unknown value ^[3]. The retirement record therefore uses three evidence lanes (population, metadata references, business and external dependencies), each with a timestamp, an access limit and an accountable owner.

Native discovery is useful but never exhaustive. Salesforce labels the Dependency API a Beta feature ^[4], and descriptions of the "Where is this used?" button disagree on reports while agreeing that external systems are a weak spot ^[5]. Salesforce Help is the authority on the button's current scope, so confirm it for your release; the worksheet records report coverage as "verify live".

Recovery is the second deliverable. Salesforce's managed-package developer documentation says that a deleted custom field can be undeleted for 15 days ^[6], that some properties are lost or changed ^[6], and that the Metadata API purge option can bypass the Recycle Bin ^[7]. The 15 days is therefore a ceiling, not a guarantee, and the sandbox rehearsal is where current behavior is confirmed. A sandbox rehearsal deletes and undeletes a candidate with the production method and compares restored attributes with a pre-delete baseline, in line with NIST's guidance that backups should be tested regularly ^[8]. The go/no-go record counts known blockers and unresolved owners separately and never turns "no findings" into a safety score. A checklist reduces uncertainty; it cannot certify the whole org ^[9].

Introduction and Background

The audience is the administrator, RevOps analyst or consulting partner holding a specific nomination and a decision to make.

Existing coverage is already strong on mechanics. A May 2026 vendor article explains why deletion fails, including that Salesforce names one blocking dependency at a time ^[10], and Gearset explains metadata search and the Dependency API, noting its Beta status ^[11]. This report does not present basic dependency inspection as novel. Its added assets are a retirement evidence worksheet and a restore verification table that are completed before production is touched.

Three scoping rules apply. First, every example is hypothetical unless a citation is attached, and sample counts are fictional, not benchmarks. Second, the example records the edition, release, API version and field type, because behavior depends on type and on the change made. Third, long-standing behavior is described as such. The Admin Blog lists the Winter ’27 production weekends as September 4, October 2 and October 9 ^[12]. Neither the developer blog nor that post mentions a change to field deletion, but absence from two blog posts is not proof, so confirm the current wording in Salesforce Help and the release notes for your release.

Confirming current Salesforce wording

Salesforce Help is the authority on the current scope of the "Where is this used?" button, on deletion blockers by field type, and on restore behavior in your release. Open the Help articles titled "Manage Deleted Custom Fields", "Manually Restore Attributes of Deleted Fields" and "Purge Deleted Custom Fields" as the checklist and compare them with the tables below. Where this report cites developer documentation, Trailhead or practitioner descriptions instead, the text says so, and the sandbox rehearsal is where behavior is confirmed.

Where the publisher fits

Cirra AI, the publisher of this article, describes its product as a hosted Salesforce admin Model Context Protocol (MCP) server that lets an AI client inspect and, with the user's approval, change metadata as the connected user, within that user's permissions. It is relevant here only as one way to run verified inspections. It is not a backup product, a dependency-completeness guarantee, a deployment platform or an automatic rollback system, and it does not replace the team's sandbox, review and promotion process.

Key Changes in How a Field Retirement Is Evidenced

From "Is It Empty?" to Three Evidence Lanes

The older shortcut was a population check: if no record holds a value, delete. Practitioner guidance rejects it, stating that a field without data may still be needed ^[2], and a field with no data might still be referenced in a validation rule ^[11]. The Elements.cloud post says a field can sit empty for 8 entirely legitimate reasons (Source: elements.cloud). A vendor post lists missing visibility into data volumes and usage as a gap for generic agents (Source: elements.cloud).

Salesforce's Trailhead guidance separates a field "never used or populated" ^[13] from one "abandoned" for a defined period such as 12 to 36 months ^[13], and groups empty fields by whether they have metadata dependencies to resolve ^[13]. A practitioner post adds that Salesforce has no single "last used" timestamp on a field ^[5], and another notes there is no built-in report of what percentage of records hold a given field ^[14]. Population is therefore a current snapshot, never activity telemetry.

The worksheet separates three lanes:

• Lane 1, populated data: counts in a documented record scope, with a stated denominator and query timestamp.
• Lane 2, references: results from supported native and metadata inspection, each with its access limits.
• Lane 3, business and external dependencies: statements from an integration owner and a process owner, including seasonal processes and dynamically composed queries.

Each lane needs a timestamp, a list of inaccessible areas and a named, accountable owner. A lane with no owner is unresolved, not clean.

From a Dependency List to a Coverage Report

A blank dependency list says only that the chosen tool found nothing within its coverage. One vendor post puts it plainly: a field missing from the Dependency API result has no tracked references, which makes it a cleanup candidate and not proof that it is unused ^[9]. The evidence record should therefore report coverage: which tools ran, as which user, over which component types, and what each is documented not to see. The next major section builds that table.

From a 15-Day Backstop to a Rehearsed Restore

One vendor writes that the 15-day restore window is a backstop, not a plan ^[10]. The same applies to a clean sandbox result. The restore is rehearsed before production deletion, with the production method, and with a baseline snapshot to compare against. NIST's contingency planning guidance supports the principle in general terms: a test is an evaluation using quantifiable metrics ^[8], and control CP-9(1) adds that organizations need assurance that backup information can be reliably retrieved ^[15]. These are generic standards, not Salesforce documentation, and they do not say that a field export alone is a backup.

AI Assistance Changes the Comparison Work, Not the Accountability

AI assistance is most useful for comparison: reconciling allowed metadata references from several tools, reporting coverage gaps, classifying evidence into the lanes, and diffing before and after configuration snapshots. It is least safe where it infers. Three rules follow.

• Null is not unused. A model must not treat a null count, a blank dependency list or a familiar-looking API name as proof of non-use ^[3].
• Visibility depends on the user. Describe returns only the fields the user can view ^[16], so a hidden field can look absent to an under-privileged session. Record the user and permission set behind every result.
• A human stays in the loop. The MCP specification says there should be a human in the loop who can deny tool invocations ^[17], and that hosts must obtain explicit user consent before invoking any tool ^[18].

What Winter ’27 Does and Does Not Change

The release matters mainly for recording context. The sources reviewed for this report do not identify a changed deletion model. A 2015 blog copy of older Salesforce help text, cited only as historical context, says deleted fields are kept until permanently deleted or 15 days pass, whichever comes first ^[19], which is consistent with the 15-day window in current developer documentation. The reader should check the current Help article for the live wording in their org's release.

Implementation Considerations: Candidate, Evidence and Native Discovery

Define the candidate precisely

Before gathering evidence, write down the identity of the field. Salesforce's Metadata API names a field as Object.Field, for example Account.MyAcctCustomField__c ^[20]. The Tooling API's FieldDefinition exposes a DurableId, but Salesforce says its value is not guaranteed to stay the same from one release to the next ^[21]. The DurableId therefore cannot serve as the only identifier, so the record stores org, object, namespace prefix, API name, data type, release, API version and the retrieval timestamp, and re-queries the DurableId each time.

A fictional example (Hypothetical Example): org "Sandbox-RT1", Enterprise Edition, Winter ’27, API 68.0, object Opportunity, field Legacy_Region__c, type Text(80), no namespace, business owner Regional Sales Operations, proposed reason "superseded by a standard picklist".

The decision options are three: retain; deprecate with an observation period; or remove after explicit approval. Trailhead's best practice is to deprecate, remove from user permissions, wait for feedback, then delete ^[13], and also to remove the field from page layouts and permissions, mark it deprecated, then delete after the dependency review ^[13]. A practitioner post suggests at least one full business cycle between deprecation and the next step ^[5].

Do not silently change field-level access or automation as a form of deprecation. Removing access can break an integration user or a scheduled job, which is itself a production change. Treat any restriction as a separately approved change with an owner, a notice and a rollback note, and treat a label or description change as the lowest-risk way to mark intent.

Lane 1: populated data

Measure population in the authorized query scope and state the denominator: records visible to the querying user, in the named object and filter. In SOQL (Salesforce Object Query Language), the numerator and denominator are two counts over the same scope. Run the counts through the query interface the organization has approved for read-only audits. Handle defaults and checkboxes separately: a field defaulted on create can look populated without any user action, and a checkbox is never null, so report its true and false counts, not a "population rate". Label the result as current population, not usage and not deletion eligibility.

A fictional example (Hypothetical Example): 12,480 Opportunity records visible to the authorized user, 1,872 with a non-null Legacy_Region__c, gives 15.0 percent current population (1,872 divided by 12,480). Because only Partial Copy and Full Copy sandboxes include production data ^[22], a Developer sandbox would show 0 of 0 records and prove nothing. Run the read-only count against the system of record, under the organization's data-access rules, and use the sandbox for the delete and undelete test.

Lane 2: native discovery and its blind spots

Table 1 below lists the inspection routes, what each is documented or described to cover, and the gaps the record must carry. It includes interfaces an AI client could drive, because the comparison across routes is where AI assistance helps.

Table 1. Native discovery routes, documented coverage and gaps to record

The table shows two patterns. Every route reports within a boundary, and the boundaries differ: reports and dashboards, flows, managed packages, runtime-composed queries. And the descriptions of the same button are not uniform. One older source says reports are not analyzed ^[2], while another says only joined reports are not covered ^[10]. Current Salesforce Help is the tiebreaker and should be read live; the worksheet's report row is marked "verify live, accessible reports only".

Dynamic references are the largest blind spot. A vendor post says Apex that builds a query as a string hides the field name from dependency parsing ^[9], and Salto's help center says it may not always detect references in Apex classes ^[29]. Retrieve code with proper permissions and a manifest scope, and search for the API name as text, but also ask the owner whether any code composes the name. Never claim a scan enumerates every consumer. If the Tooling API route is used, independently confirm the Beta label and row limits in the live documentation for the org's release.

Lane 3: business and external dependencies

External systems do not appear in dependency results at all ^[5]. An integration owner must state in writing which interfaces read or write the field, including middleware, business intelligence extracts and warehouse jobs, and a process owner must state which seasonal or periodic processes use it. Deleting a field can also change how assignment or escalation rules behave if they depend on it ^[30], and dependency data can be incomplete for some reference types ^[5]. Those owners are named in the record. "No reply" is recorded as unresolved.

Implementation Considerations: Test Plan, Rehearsal and Go/No-Go

Separate platform blockers from runtime dependencies

Platform blockers stop the deletion. Trailhead says a field cannot be deleted without removing field dependencies ^[13], and the Metadata API guide gives the Apex case: a referenced component cannot be deleted unless the class is modified first ^[7]. Gearset documents that deactivated older flow versions can still block a deployment-based delete ^[31]. Blockers vary by field type and by the change made, so they are recorded as "confirm in rehearsal".

Runtime and business dependencies might not block deletion at all: an external integration, a report that silently loses a column, a dashboard filter or a scheduled export. That is why a successful sandbox deletion is not a verdict. The test plan names a few representative items per category and an owner for anything untested:

• Reports and dashboards: open the reports found by native discovery plus those the process owner names, and record column and filter behavior before and after.
• Integrations: the integration owner runs a create and update cycle with sandbox credentials, reading and writing the field.
• Field-updating automation: trigger each flow, process or Apex path that references the field, including inactive flow versions.
• API consumers: compare describe output for a representative profile before and after, with the visibility caveat above.
• Code tests: run the org's Apex tests after removal.

All changes go through the organization's approved sandbox and change process. NIST control CM-3 describes reviewing proposed configuration-controlled changes and approving or disapproving them ^[15], CM-3(2) asks that changes be tested, validated and documented before finalizing ^[15], and CM-4(1) refers to analysis in a separate test environment before an operational one ^[15].

Rehearse recovery before production deletion

Start with the baseline. Preserve approved metadata and any necessary data exports through the organization's own retention and backup procedures. NIST CP-4 describes testing to determine the effectiveness of a plan and the readiness to execute it ^[15]. NIST CM-2 asks for a documented, current baseline configuration held under configuration control ^[15]. An export is a record of values, not a restore path for configuration. A Salesforce product page describes capturing copies of data and metadata and comparing metadata between two backups ^[32], but whether any such product restores a given field's attributes is a question the team must answer for its own tooling.

Then use the sandbox candidate. Salesforce's sandbox guide says sandboxes always include production metadata ^[22], and that refreshing means syncing with the latest production metadata ^[22]. Developer and Developer Pro sandboxes refresh once per day ^[22], while Full Copy sandboxes can only be refreshed every 29 days ^[22], so schedule the rehearsal to avoid a refresh that would reset the test. Populate a few records first so data restoration can be checked.

Choose the deletion method deliberately, because Setup, a destructive manifest and the CLI may not behave identically. By default Metadata API deletions go to the Recycle Bin, and setting the purge option bypasses it ^[7], and a deleted roll-up summary field is not saved in the Recycle Bin ^[33]. The developer documentation read did not state that a Metadata API field deletion lands in the Deleted Fields list, so that is a point to confirm in the rehearsal, with the same method planned for production.

Window facts: Salesforce's managed-package developer documentation says that a deleted custom field can be undeleted, restoring the component and all data stored in it, during a 15-day period ^[6], after which the field and its data are permanently deleted ^[6]. Salesforce Ben describes the Deleted Fields screen as offering erase (permanent hard delete) or undelete within those 15 days ^[34]. Early erase, purge options and roll-up behavior all mean that 15 days is a ceiling. A soft-deleted field also still counts against the maximum number of custom fields until erased, according to a 2015 blog copy of older Salesforce help text (historical; confirm in the current Help article) ^[19], which creates a real tension for orgs near their limit.

Verify restored attributes against the baseline

The Salesforce Help page "Manually Restore Attributes of Deleted Fields" is the checklist source and should be read live. Third-party descriptions give examples, and each is type- and change-dependent: the required setting ^[34], relationship fields converted to lookups ^[34] and layout placement ^[34]. A 2015 blog copy of older Help text (historical, to be confirmed in the rehearsal) says restored formula fields come back disabled until saved ^[19], and the restored name may carry a "_del" suffix on the field and API name ^[34]. Do not read these as a promise that every field loses every attribute; the rehearsal measures what happens for this type in this release. The restore verification table in the Data Analysis section below provides the layout, with extra rows for the unique flag, dependencies, history tracking and package membership as test prompts to confirm against the Help checklist.

NIST CP-9(1) describes a sample-based check that compares restored information with the primary source ^[15], a useful model for the compare step. Record who ran the restore, the time, and what each correction cost.

Produce the go/no-go record

The record collects the worksheet, the coverage table, the restore table, the remaining dependencies, the business approval, the tested recovery scope, the observation plan, the responsible owner and the promotion route. Two counts appear separately: known blockers (components that prevent deletion or must change first) and unresolved owners (lanes or dependencies with no accountable answer). They are never added, averaged or turned into a score, and "no findings" is recorded as "no findings within the listed coverage". If coverage is unresolved, the decision is retain or defer. After an approved production change, monitor the relevant workflows for a full business cycle and stop if new failures appear. Keep the field's API name and ID mapping in the record as well.

Data Analysis and Evidence

The tables below are templates filled with fictional values (Hypothetical Example). They are not performance benchmarks, and no customer org was accessed.

Table 2 below is the retirement worksheet. Each row is one evidence lane or sub-lane, with scope, timestamp, source or component identifier, result, inaccessible areas, owner and a lane-level decision.

Table 2. Retirement evidence worksheet (fictional values)

The interpretive reading is simple. A "0 literal hits" row does not offset an unanswered owner. In this fictional example the known blocker count is 2 (a flow and a validation rule) and unresolved owners are 1 (integration), reported separately. The decision is "deprecate and observe", not "approve retirement". This is the same logic a field usage audit follows: the population lane is one input, and tools that measure population, such as the sfdx-hardis object field usage command, measure how many records populate each non-required field ^[35], a separate check from dependency mapping.

Table 3 below provides the restore verification layout. The "pre-delete value" column comes from the baseline retrieve, "restored value" from the sandbox after undelete, and every row needs a test and an approver. The right-hand column marks which rows rest on a cited description and which are test prompts to confirm against the Help checklist.

Table 3. Restore verification layout (fictional pre-delete values)

The table's value is its blank cells. Any "Verify" that the sandbox rehearsal cannot fill means the restore claim for that attribute is unproven. Field-level security and permission set entries should be added as rows by the team when the Help checklist names them.

Implications and Future Directions

The practical implication is a shift from deletion as a one-off task to an evidence record that an auditor, a successor administrator or an AI assistant can re-run. NIST's guidance describes an exercise as a simulation designed to validate the viability of a plan ^[8], and a field retirement record is a small instance of the same discipline: it states what was tested, with which method and by whom, and what remained unknown.

AI-assisted administration raises the stakes in two directions. It speeds up inventory and comparison, and it makes the permissions boundary more important. Hosted and local MCP servers differ in status and scope, and product status changes, as the DX server's end-of-life notice shows ^[26], so any workflow built on a tool should re-check status at the time of use. The MCP specification describes tools as arbitrary code execution that must be treated with appropriate care ^[18], and describes MCP as an open-source standard for connecting AI applications to external systems ^[36]. Practically, an AI client should draft the worksheet and diffs, while the connected user approves each change.

Open questions remain. The Help articles should be re-read for their release-specific wording. Whether a Metadata API deletion always appears in the Deleted Fields list, how a sandbox refresh affects a rehearsal in progress, and what each backup product restores at field level are team-specific checks. Demand for this topic is small, and the relevance of AI is a hypothesis, not measured adoption. Teams that want help running verified, permission-bound inspections from an AI client can look at Cirra AI's Salesforce MCP server, the publisher's own product, keeping the sandbox, review and promotion process in charge.

Frequently Asked Questions (FAQs)

How do I safely delete a Salesforce custom field?

Nominate one field, record its identity, gather the three evidence lanes, run native discovery with its limits noted, test in a sandbox, rehearse undelete, obtain business approval, and promote through the normal change process. Salesforce's own training recommends deprecating, removing from user permissions, waiting for feedback and then deleting ^[13].

Where is a custom field used, and how complete is the answer?

The Setup button covers custom fields only (Table 1), and external systems never appear in dependency results. Report coverage is described differently by different sources, so read the live Help page.

What does field dependency analysis before deleting involve?

Reconcile the button, the Dependency API (Beta, with a 2000-row Tooling cap and reports excluded) and a text search of retrieved code ^[9], then ask owners about dynamic and external use.

Can I restore a deleted custom field, and is it really 15 days?

Salesforce documents undelete with data for 15 days and then permanent deletion, and some properties are lost or changed; an older blog copy of Salesforce's help text says deleted fields are kept until permanently deleted or 15 days pass, whichever comes first ^[19]. Early erase and purge options mean it can be shorter. A data-recovery vendor notes that deleted custom fields are restored from Deleted Fields in Object Manager, unlike records, which use the Recycle Bin ^[37].

How do I find references in Apex, flows and reports?

Use native results, the Dependency API with Bulk API 2.0 for reports, retrieved metadata with text search, and owner review for dynamic code.

How does the metadata dependencies API help with a custom field?

It returns rows that link a referencing component to the referenced field, which suits reconciliation against the Setup button. The sfdx-hardis field usage command, for example, lists dependencies by querying the Tooling API and the Metadata Component Dependency API ^[24]. See Table 1 for its Beta status, row limits and report exclusion.

What does a field usage audit before removal look like?

It is the worksheet in Table 2, with population labeled as current population and an owner for each lane.

Conclusion

Retiring a custom field is a decision about evidence and recovery, not about whether a field looks empty. The record proposed here has three lanes with timestamps, access limits and owners; a coverage table that reports what each tool cannot see; a rehearsal that deletes and undeletes a sandbox candidate with the production method; and a restore table that compares pre-delete and restored attributes. Known blockers and unresolved owners are counted separately, and "no findings" is never converted into a safety score.

Several limits stay in view. Salesforce documents a 15-day undelete window, but early erase or purge can shorten it, and some properties are lost or changed on restore. The Dependency API is Beta and excludes reports from Tooling queries. External systems and dynamically composed code are invisible to metadata inspection. The reader should treat the current Salesforce Help text as the final checklist. The safe default when coverage is unresolved is to retain or defer, and a reference checklist cannot certify the whole org.