AdvancedOracle NetSuiteSuiteCloud Development Framework (SDF)

Managing NetSuite sandbox refresh alongside SDF deployments

Question
how does NetSuite sandbox refresh affect SDF deployments

Also searched as

  • netsuite sdf deploy account customization project
  • suitecloud cli project deploy failed
  • netsuite sandbox refresh schedule and customizations
  • netsuite manifest.xml deploy.xml explained

Short answer

A NetSuite sandbox refresh clones production data and customization state into the sandbox account, which means any sandbox-only changes not captured in an SDF (SuiteCloud Development Framework) project are wiped, while changes that were already deployed to production survive because they come along with the refresh. Plan refreshes around your deployment calendar, and redeploy or validate your SDF project immediately after every refresh.

Applies to: NetSuite sandbox accounts, SuiteCloud Development Framework (SDF) projects, SuiteCloud CLI for Node.js

Coordinate sandbox refresh with an SDF workflow

  1. 1Check the account's sandbox refresh eligibility and schedule at Setup > Company > Sandbox Refresh Status; refresh frequency is tied to the account's contract (commonly limited to a certain number of refreshes per period, not on-demand daily).
  2. 2Before requesting or accepting a scheduled refresh, confirm the SDF project's current state is captured: run suitecloud project:validate and commit any pending custom object XML changes to source control so nothing sandbox-only is lost.
  3. 3Understand that refresh overwrites the sandbox with a copy of production, including data and the production customization state; anything deployed to sandbox but not yet deployed to production is replaced by whatever exists in production at refresh time.
  4. 4After refresh completes, re-run suitecloud account:setup (or reconfirm the saved authentication ID) since role IDs, internal IDs and some environment-specific references can differ or need re-validation post-refresh.
  5. 5Run suitecloud project:deploy (or project:validate first, then deploy) to reapply the SDF project's custom objects, scripts and File Cabinet content to the freshly refreshed sandbox.
  6. 6Check deploy.xml to confirm it still references the correct set of objects and files; a project that grew since the last refresh needs deploy.xml (or the auto-generated manifest for object-based deploys) kept in sync with everything intended to ship.
  7. 7Re-test integration credentials (TBA tokens, OAuth 2.0 client credentials) issued specifically for the sandbox, since refresh can invalidate previously issued sandbox tokens tied to the old sandbox state.
  8. 8Re-run any post-deploy configuration steps that live outside SDF's scope (for example, feature enablement, certain preferences, or non-SDF-managed saved searches) that a refresh would also have reset to production's state.

What survives a refresh and what does not

Data, and customizations that are part of production's current state, survive because refresh literally clones production into the sandbox. If a feature, script or custom record was already live in production before the refresh, it comes along automatically.

What does not survive is anything that exists only in the sandbox and has not been promoted to production: unreleased script versions being tested, sandbox-only configuration used for QA, or in-progress customizations tracked in an SDF project locally but never deployed to that sandbox account before the refresh replaced it.

This is why teams that rely on SDF treat the sandbox as disposable and the SDF project (in source control) as the source of truth; redeploying after a refresh is expected, routine work, not a recovery exercise.

manifest.xml, deploy.xml and the deploy unit

An SDF project's manifest.xml declares the project's basic metadata and required features/dependencies, while deploy.xml lists exactly which objects, files and configuration should be included when suitecloud project:deploy runs, using path patterns under Objects/ and FileCabinet/.

Keeping deploy.xml accurate matters most right after a refresh: if it excludes a directory or object type that was added since the file was last edited, that content silently will not deploy, and the freshly refreshed sandbox will be missing customizations that developers assume are already there.

<deploy>
  <configuration>
    <path>~/AccountConfiguration/*</path>
  </configuration>
  <files>
    <path>~/FileCabinet/SuiteScripts/*</path>
  </files>
  <objects>
    <path>~/Objects/*</path>
  </objects>
</deploy>

CI/CD around scheduled refreshes

Teams running SuiteCloud CLI in a CI/CD pipeline (using a saved authentication ID or CI-specific credentials) typically add a manual gate or a scheduled job right after each known sandbox refresh window to immediately validate and redeploy, so developers do not lose a day discovering the sandbox reverted underneath them.

It is also worth versioning the SDF project's account-specific overrides (different script deployment IDs, employee/role internal IDs between sandbox and production) carefully, since a refresh can shift what 'the sandbox' contains without changing the SDF project files themselves, which is a common source of deploy-time ID mismatches.

Common pitfalls

  • !Assuming sandbox refresh only touches data and not customizations, then being surprised when unreleased scripts disappear.
  • !Not committing SDF project changes to source control before a scheduled refresh, losing track of what needs to be redeployed.
  • !Forgetting to re-issue or re-test sandbox-specific integration credentials after a refresh invalidates the previous sandbox state.
  • !Letting deploy.xml drift out of sync with the actual Objects/ and FileCabinet/ directories, so a redeploy after refresh silently omits new customizations.
  • !Treating a refresh as available on demand when the account's contract only allows a limited number per period, leading to scheduling conflicts with QA or UAT cycles.

How an ERP-grounded AI assistant handles this

SyteRay-style grounded review of an SDF project's manifest.xml and deploy.xml can flag, before a redeploy, objects or files that exist on disk but are not referenced by deploy.xml (or vice versa), which is exactly the drift that causes silent gaps right after a sandbox refresh. It can also summarize what changed in a refreshed sandbox compared to the last known SDF deploy state, saving a manual diff.

See ERPray

Frequently asked questions

How often can I refresh a NetSuite sandbox?

Refresh frequency depends on the account's contract and sandbox tier; many accounts are limited to a set number of refreshes over a period rather than being able to refresh on demand daily, so check Setup > Company > Sandbox Refresh Status for the account's actual allowance.

Will a sandbox refresh delete my SuiteCloud CLI saved authentication?

The locally saved authentication ID on the developer's machine is unaffected, but tokens or credentials that were specific to the sandbox's prior state (such as TBA tokens issued in that sandbox) can be invalidated, so re-authenticating after a refresh is good practice.

Does refresh affect production, or only the sandbox being refreshed?

Only the sandbox being refreshed is affected; production is the source that gets copied from, and other sandboxes are untouched unless they are also scheduled for refresh separately.

Should every customization go through SDF instead of being made directly in the sandbox UI?

For anything meant to reach production, yes. Direct UI changes in a sandbox that are never captured in an SDF project are exactly what gets lost on the next refresh, whereas an SDF project in source control can always be redeployed regardless of how many times the sandbox is refreshed.

Related

Advanced

Avoiding governance limit errors in NetSuite Map/Reduce scripts

A NetSuite Map/Reduce script gives each map or reduce invocation of a key its own fresh governance allotment instead of sharing one pool across the whole run, so most SSS_USAGE_LIMIT_EXCEEDED failures come from a single key doing too much work, not from the total record count. Fix it by moving heavy logic out of getInputData, keeping map and reduce functions idempotent and cheap per key, and checking runtime.getCurrentScript().getRemainingUsage() before expensive calls.

Advanced

Authenticating NetSuite RESTlets with OAuth 2.0 and Token-Based Authentication

NetSuite RESTlets can be called with either Token-Based Authentication (TBA, OAuth 1.0a signed requests) or OAuth 2.0, and both require a Setup > Integrations > Manage Integrations record before any token is issued. Machine-to-machine OAuth 2.0 uses a client credentials grant with a JWT bearer assertion signed by a certificate; TBA uses a consumer key/secret plus a per-user access token signed with HMAC-SHA256.

Advanced

Working with NetSuite's SuiteTalk REST Web Services API

SuiteTalk REST exposes NetSuite records at https://ACCOUNTID.suitetalk.api.netsuite.com/services/rest/record/v1/{recordType}/{id} and ad hoc SQL-like queries at /services/rest/query/v1/suiteql, both authenticated with TBA or OAuth 2.0. It returns JSON, paginates large result sets with limit/offset and a hasMore flag, and needs expandSubResources or a specific fields query to pull sublist and related data efficiently.

Error fix

Fix NetSuite SSS_USAGE_LIMIT_EXCEEDED Error

SSS_USAGE_LIMIT_EXCEEDED fires when a SuiteScript execution consumes all the governance units (usage points) allotted to its script type before it finishes. Fix it by checking runtime.getCurrentScript().getRemainingUsage() before expensive calls, yielding or rescheduling in Scheduled scripts, and moving heavy record-count work into Map/Reduce, which yields automatically across stages.

Error fix

Fix NetSuite INVALID_FLD_VALUE Error

INVALID_FLD_VALUE means NetSuite rejected a value you tried to set on a field because it does not match the field's expected type, list option, or reference record. Fix it by confirming the internal ID or text value actually exists on that field's source list and matches the field's value type (text versus list versus record reference) before setting it.

Error fix

Fix NetSuite SSS_MISSING_REQD_ARGUMENT Error

SSS_MISSING_REQD_ARGUMENT means a NetSuite API call, most often record.create(), record.load(), or search.create(), was called without a parameter that method requires, such as type or id. Fix it by checking the object literal you passed against the current SuiteScript 2.x API signature and confirming no required key is undefined at runtime.

AI for ERP

AI for NetSuite, Beyond the Built-In Text Tools

NetSuite's built-in AI covers text generation, not grounded answers on your own data. See how a private LLM over SuiteQL adds real Q&A and controls.

AI for ERP

AI agents for NetSuite manufacturing operations

AI agents for NetSuite manufacturing: WIP tracking, routing exceptions, and work order status grounded in SuiteQL, with human approval on anything that writes back.

Stuck on Oracle NetSuite?

Talk to engineers who work inside Oracle NetSuite every week, and who build private AI that answers these questions from your own ERP data.

Talk to an ERP engineerBrowse ERP Help
All ERP Help articles