Skip to Content

Deploy Code

Deploy cartridges to one or many instances, switch rows to the active code version with the wand, pick an optional API version for compatibility and follow each cartridge live in B2C Sync

Deploy Code zips every linked cartridge and module, uploads the archives and unzips them on the server, much faster than uploading files one by one. One dialog deploys to a single instance or to several at once, each into its own code version, and B2C Sync shows every cartridge as it goes up

Click Deploy Code: the instances you checked last time come back checked. The wand on a row, or Switch All to Active Code Versions, picks the version the instance runs. A .apiversion file forces the code version to run on one B2C Commerce API version, for compatibility: a row's API version picks it for that instance, API version under the list for all, and Not set uploads none. Deploy opens B2C Sync on its Code Deployment tab, one tab per instance, and one notification sums up all of them with the time

Deploy your code

Open Deploy Code

Click the Deploy Code button in the main toolbar, choose Tools › Salesforce B2C Commerce › Deploy Code..., or press Cmd+Ctrl+Z on macOS (Ctrl+Meta+Z elsewhere, see Keyboard shortcuts)

Check the instances

The dialog always checks the active connection, along with the instances you left checked when it last closed. Check or uncheck rows, whole groups or the Instances box above the list

Check the code versions

Each row shows the code version it deploys to and its status. Click the version to pick another one, or click the wand to switch to the version active on the instance, see Pick a code version

Pick an API version, if you need one

A .apiversion file forces the code version to run on one B2C Commerce API version, for compatibility. Each row's API version picks it for that instance, and API version under the list picks one for all. Leave it Not set and no file is uploaded, see API version

Deploy

Click Deploy, or Deploy to 3 Instances when several are checked. B2C Sync opens on the Code Deployment tab of the first instance, see Follow a deployment, and one notification sums up the result

Deploying doesn't activate the code version. Activate it in B2C Explorer, see OCAPI & Jobs, or in Business Manager

Deploy to several instances

Check as many instances as you need. They all get the same code, each into the code version on its row. The list has up to three kinds of sections

SectionWhat it holds
Active connectionThe connection selected in the main toolbar, always first and never folded
Other connectionsThe connections outside any group. It reads Connections when there is no active connection and no group
A groupThe group's connections under its name and group icon. With two or more instances ready, the group has its own box that checks all of them
  • A section's title shows how many instances it has, and "· 2 selected" once some are checked
  • Each instance's cloud is in its kind's colour, red for Production, blue for Staging and green for Development, see Instance colours
  • Click a title to fold or unfold the section. The dialog remembers folded sections for the project
  • A folded section that has a problem, such as a checked row without a code version, says so in its title
  • Expand All Groups and Collapse All Groups sit in the dialog's toolbar
  • The Instances box above the list checks every instance, next to the "2 of 5 selected" count

Filter instances

The Filter instances field in the dialog's header narrows the list by name, hostname, code version or group as you type

  • Folded sections that have a match open, and the matching text is marked in each row
  • With nothing left, the list reads "No instances match “eu”"
  • Esc clears the filter first. Press it again to close the dialog

Rows that read No account or No hostname can't be checked until the connection has a WebDAV account and a hostname

Pick a code version

Each row starts on the code version selected for its connection, as the main toolbar shows it, or on the version active on the instance when none is selected

ControlWhat it does
Wand next to the row's versionSwitches the row to the version active on the instance. Its tooltip names it, for example "Switch to version3, the active code version on the instance". It shows only when the row is on another version
The row's versionOpens the list of the instance's versions, the active one marked "active on instance". With 7 or more versions, a Search code versions field filters them
Use Active Version In the list: switches the row to the active version, named on the right
New Code Version...In the list: creates a version on the instance and picks it. Names take letters, numbers, dots, dashes and underscores
Refresh Code VersionsIn the list: reloads that instance's versions
Switch All to Active Code Versions In the dialog's toolbar: switches every row to the version active on its instance
Refresh Code Versions In the dialog's toolbar: reloads the versions of every instance

On Deploy, the versions you picked are saved to the connections, as if picked in the toolbar

StatusWhat it means
CheckingThe plugin is reading the code versions from the instance
ActiveThe version is active on the instance, so the deployed code is live right away
InactiveAnother version is active. Activate this one to run the deployed code. The tooltip names the active one
MissingThe instance has no code version with this name. Pick another one or create it
No versionsThe instance has no code versions yet. Create one with New Code Version...
UnreachableThe code versions couldn't be read. Hover the status for the error
No account, No hostnameThe connection needs a WebDAV account and a hostname before you can deploy to it

API version

A .apiversion file forces a code version to run on one supported B2C Commerce API version, such as 22.7, for compatibility. You only need it when your code relies on an older API version. Leave it Not set and the deployment uploads no .apiversion at all

Click Deploy Code: the instances you checked last time come back checked. The wand on a row, or Switch All to Active Code Versions, picks the version the instance runs. A .apiversion file forces the code version to run on one B2C Commerce API version, for compatibility: a row's API version picks it for that instance, API version under the list for all, and Not set uploads none. Deploy opens B2C Sync on its Code Deployment tab, one tab per instance, and one notification sums up all of them with the time
ControlWhat it does
A row's API versionOpens a popup with Not set, the compatibility modes B2C has, newest first, and Custom Version.... The version you pick is saved for that connection in the project right away
API version under the listOpens the same popup with Per instance in place of Not set. A version picked here goes to every checked instance and reads "22.7 for all instances". The rows then show it in grey, with the tooltip "Set for all instances under the list"
Custom Version...Asks for any compatibility mode, a year and a month such as 23.2. It then shows among the known ones
  • With a version, the deployment uploads .apiversion with version=22.7 to the root of the code version, right after the cleanup
  • Not set uploads nothing, and a .apiversion already on the instance stays as it is
  • No cleanup removes .apiversion, not even Full cleanup of the code version. A deployment with another version overwrites it
  • Per instance gives each row its own version back
  • The B2C Sync console prints "API version: 22.7" under the instance and ".apiversion uploaded: version=22.7" once it is up. The upload also shows in the deployment's own requests
  • If .apiversion can't be uploaded, the deployment to that instance stops before any cartridge goes up, with "Could not upload .apiversion" and the reason

The compatibility mode applies only after the code version is activated again. Activate it in B2C Explorer, see OCAPI & Jobs, or in Business Manager

Options

OptionWhat it does
Full cleanup of the code versionRemoves every cartridge and module from the code version before the upload, not only the ones this project deploys. .apiversion stays. Off by default, the dialog remembers it
API versionSets one compatibility mode for every checked instance, or Per instance to use each row's own, see API version. Not set on a row uploads no .apiversion
Runs firstLists the tasks that run before the upload for the checked instances. Edit opens the Tasks tab of Deployment Settings

What a deploy does

  1. Runs the tasks before code deployment once, for all checked instances
  2. Zips each linked cartridge and module once and prints every archive with its size and the total
  3. Uploads to the checked instances in parallel, each in its own B2C Sync tab. Concurrent Threads in Settings, also Parallel requests in B2C Sync, caps how many requests go to each instance at once
  4. On each instance, removes the deployed cartridges and modules from the code version, or all of them with Full cleanup of the code version, uploads .apiversion only when the instance has an API version, then uploads the archives largest first, unzips each one and deletes the zip
  5. Sums up each instance in its Code Deployment tab and in the console

The zips never hold credential and key files, whatever the upload skip list in the project settings says, see What gets uploaded

The notification

One notification sums up the deployment and says how long it took

TitleWhen
"Deployed to Sandbox 01 in 0:38"One instance, every cartridge deployed
"Deployed to 3 instances in 0:41"Several instances, all deployed
"Deployment to Sandbox 01 failed after 0:22"One instance, and it failed
"Deployment failed on 1 of 3 instances after 0:44"Several instances, some failed
"Deployment cancelled after 0:12"You stopped it

Under the title, each instance has one line: its name, the code version, how many cartridges were deployed, failed or skipped, the size and the time, for example "Staging EU · version3 · 12 deployed · 17.1 MB · 0:36". Show Sync Log opens the first instance that failed, else the first one that was stopped, else the last one

Follow a deployment

A deployment that starts opens B2C Sync on its instance's Code Deployment tab. The tool window grows until the first rows show, and the keyboard goes to the table, so arrows and Enter work at once

Deploy Again runs the last deployment once more. The headline follows it from zipping to Deployed 12 cartridges in 0:41, the strip fills a segment per cartridge sized by its zip, and the running rows stay on top while they go up

The summary

The line on top says what happened, and after it the code version, the host and the total size

SummaryWhen
"Deploying to version2", with a spinnerThe deployment runs. After the host, the line counts it out: "Zipping 4 of 12", "Connecting", "Removing old cartridges 3 of 12", then "5 of 12 done · 6.2 MB of 17.1 MB" and the time so far
"Deployed 12 cartridges in 0:38"Every cartridge went up
"11 deployed, 1 failed in 0:44"Some cartridges failed. With nothing deployed, it reads "Deployment failed after 0:22"
"Stopped after 0:12: 5 of 12 deployed"You stopped it

Before the first deployment the line reads Ready to deploy, with the code version and the host of the instance. On a Production instance it reads Production takes no code deployments in red

The red "1 failed" is a link, while the deployment runs and after it ends. Click it to clear the search and show only the Failed cartridges

When the whole deployment fails, for example because the instance can't be reached, the line ends with the error in red. Click it to see the request that failed in the request details

The Code Deployment tab's icon shows a running badge while it runs and a red one when it failed

The code version and the host are links. The version opens B2C Explorer with the version selected under its connection's Code versions, listing them first when needed. The host opens B2C Explorer with the connection selected

Parallel requests sits at the end of the line, and Show Code Deployment and Code Upload Side by Side at the end of the tab row puts your uploads next to the deployment, see B2C Sync

The strip

Under the summary, a strip has one segment per cartridge, as wide as its zip. A segment fills as its zip goes up, turns green once deployed and red when it failed. Queued and skipped cartridges leave the track empty. Hover a segment to see the cartridge, click it to select its row

The table

ColumnWhat it shows
CartridgeThe cartridge, the global modules folder or the B2C module, with its icon. The tooltip gives its kind (Cartridge, Global modules or B2C module) and path
StatusIts state, see below. Hover a failed row for the error
ProgressHow much of the zip went up
SizeThe zip's size. While it goes up, hover it to see how much went up
TimeHow long it took, counting while it runs
  • Running cartridges stay on top whichever way the table sorts, and the table never scrolls by itself, so the row you read stays put
  • Each column is as wide as its words, and Progress takes the rest. When the table gets too narrow, Time goes first
  • The pills above the table, All, Running, Queued, Done, Failed and Skipped, show how many rows each has and filter the table, while the deployment runs too. Skipped shows only when something was skipped
  • Filter cartridges narrows the rows by name. Cmd+F on macOS, Ctrl+F elsewhere, puts the cursor in it. With nothing left, the table reads "No cartridges match" with Show all
StateWhat happens
QueuedWaits for a free upload thread
Removing old copyThe old cartridge is removed from the code version
Uploading 64%The zip goes up
Uploading 100%The zip is up and the instance is still to answer, and hovering it says so
UnzippingThe instance unzips the archive
Cleaning upThe zip is deleted from the code version
DeployedDone. "Deployed, old copy not removed" or "Deployed, zip left in the code version" when a cleanup step failed
FailedThe cartridge didn't deploy, for example "Upload failed: Read timed out", "Unzip failed: ...", "401 Unauthorized, check the credentials" or "521 Sandbox is stopped"
SkippedThe deployment stopped or failed before this cartridge went up

Request details

Show Request Details on the toolbar or in a row's menu opens every request of the selected cartridge: the old copy removed, the zip sent, unzipped on the instance and the zip removed

Ask for the details of a cartridge to follow its deployment request by request: the old folder removed, the zip sent, unzipped on the instance, and the zip removed

A failed request is selected first, otherwise the last one. Response shows the instance's answer, Request shows what went up with sign-in details masked. For everything on the panel, see Request details

With no row selected, the details show the requests the deployment sent for itself: the connection check, the listing of the code version, the .apiversion upload when an API version is set and, in a full cleanup, the removal of cartridges it doesn't bring. To get back to them from a row, Cmd-click (Ctrl-click on Windows and Linux) the selected row

Toolbar and row menu

ButtonWhat it does
Deploy Again Opens Deploy Code again. Before the first deployment it reads Deploy Code…
Retry Failed and Skipped Deploys the failed and skipped cartridges again
Stop Deployment Stops the deployment. The zips already going up finish, the cartridges that haven't started are marked Skipped, and the console prints "⏹ Deployment stopped: 5 of 12 uploaded"
Show Request Details Shows or hides the request details beside the table

Right-click a row, or several, for its menu

ItemWhat it does
Show in Console Brings the console in beside the table and selects the cartridge's last line there
Show Request Details Opens or closes the request details beside the table
Select in Project View Selects the cartridge folder in the Project view. Enter and a double-click do the same
Copy Copies the rows as text
Deploy Selected Again Deploys only the selected cartridges again

Retry Failed and Skipped and Deploy Selected Again send only those cartridges, to the same code version. They don't run the tasks before code deployment and don't do a full cleanup

Before any deployment the table reads No deployments yet with a Deploy Code… link, under an empty strip and the filter buttons at 0. For the console, the layouts and the tab per instance, see B2C Sync

Deployment Settings

Open it with Deployment Settings... at the bottom of the Deploy Code dialog, or Tools › Salesforce B2C Commerce › Deployment Settings...

TabSettingDefaultWhat it does
GeneralFull cleanup of the code versionOffThe same option as in the Deploy Code dialog
TasksTasks before code deploymentNoneIDE run configurations, for example an npm build, that run once before the upload. Edit limits a task to some instances (include or exclude). Reorder with the arrows

A failing task stops the deploy with "[SFCC] ... task failed with an error". Renaming a run configuration removes it from the task list, add it again after a rename

Code versions

Uploads and Auto Upload go to the selected code version of the active connection, a local choice. The active code version is the one the instance runs

ControlWhereWhat it does
Select Code Version Main toolbarShows the selected version. The popup lists all versions, marks the active one "[Active on instance]", and has Add Code Version at the top. Opening it asks the instance for the latest list. Names longer than 30 characters are cut, hover for the full name
Switch to Active Code Version Main toolbarAsks the instance which code version is active and selects it, see below
Code VersionConnections SettingsThe same selection, plus Add Code Version
Code version and wandDeploy Code dialogThe version each instance deploys to, see Pick a code version
Code version linkB2C SyncOpens the version in B2C Explorer, see The summary
Code versions folderB2C ExplorerOne folder per version, with Select Code Version, and with OCAPI on Activate Code Version and Activate and Select Code Version

Switch to the active code version

Click the wand right of Select Code Version to upload where the storefront runs. It asks the instance which code version is active and selects it, the same as the wand in the VS Code extension

The wand asks the instance which code version is active and selects it, so uploads go where the storefront runs
  • The wand spins while the instance answers, then Select Code Version shows the active version
  • A notification names the version, or says it is selected already
  • If the instance can't be read, the notification says why and the selection stays

Clean a code version

Clean active code version removes every file from a code version. It asks you to confirm the host and the version first, and you can pick a version other than the selected one

  • Tools › Salesforce B2C Commerce › Clean active code version
  • More › Instance › Clean active code version
  • Cmd+Shift+X on macOS, Ctrl+Shift+X on Windows and Linux

With an AI agent

An agent connected to B2C MCP can plan a deployment the way Deploy Code runs it, to one instance or several. The plan runs with the tools you gave the agent, and B2C Sync shows the deployment, see Files & Deploys

Troubleshooting

SymptomWhat to do
Deploy Code is missing from the toolbarThe project has no linked cartridge or no active connection, see Cartridges & Modules
A row reads No account or No hostnameAdd a WebDAV account or a hostname with Edit Connection, see Connections Settings
A row reads UnreachableHover the status for the error. Use Edit Connection and run Test Connection
A folded section's title shows a problemUnfold it. A checked row there has no code version or a missing one
"Choose a code version for ..." or "... has no code version named ..."Pick a version on that row, click its wand, or create the version with New Code Version...
"Could not prepare the code for upload" with "Merge the duplicate cartridges into one or exclude one of them"Two linked folders have the same cartridge name. Unlink or exclude one of them
Cartridges read Failed with "Upload failed: Read timed out"Click Retry Failed and Skipped, or select the rows and use Deploy Selected Again
"401 Unauthorized, check the credentials"The account or WebDAV access key is wrong for this host
"521 Sandbox is stopped"Start the sandbox, for example from On-Demand Sandboxes, then retry
"Deployed, old copy not removed"The cartridge went up, but the old copy couldn't be removed first. Deploy it again, or use Full cleanup of the code version
The code version selector reads Empty | Use button to the right >Click Switch to Active Code Version to select the version active on the instance, or open the selector to load the list
Uploads suddenly go to another code versionThe selected version disappeared from the list, for example after it was deleted on the instance, and the plugin switched to the active one. Pick the version again in Select Code Version, or add it with Add Code Version
The deploy finished but the storefront is unchangedCheck that the row read Active, or activate the deployed version, and that the site's cartridge path includes your cartridges

On this page