Move your integration to boltapp.com

Allow boltapp.com in your Content Security Policy

If your storefront sends a Content-Security-Policy header, you must add the boltapp.com hosts next to the existing bolt.com entries. A policy that only names bolt.com blocks the upgraded plugin's scripts and API calls. Keep both domains until Bolt confirms bolt.com is retired.

A wildcard *.boltapp.com entry in each directive is a simpler alternative and is what Bolt's Salesforce Composable guide uses.

Expected result: the browser console shows no CSP violations for boltapp.com after the plugin upgrade.

Update outbound firewall rules

If your servers restrict outbound HTTPS, allow api.boltapp.com and api-sandbox.boltapp.com alongside the current api.bolt.com hosts.

Expected result: curl -I https://api.boltapp.com from your web server returns an HTTP response instead of a timeout.

Update inbound rules that inspect Bolt's requests

If a WAF or bot rule identifies Bolt by its User-Agent, match on Bolt - https://www.boltapp.com as well as the old value. Bolt's IP addresses have not changed, so IP-based rules need no edit.

Expected result: the webhook and shipping calls Bolt makes to your store keep returning 2xx in your server logs.

Accept both bolt.com and boltapp.com where you validate Bolt tokens or URLs

If your code checks the iss claim on Bolt SSO or OpenID Connect tokens, accept all four values. A token can name either domain as its issuer, so keep the bolt.com values even after your store moves to boltapp.com:

https://bolt.com
https://api.bolt.com
https://boltapp.com
https://api.boltapp.com

Bolt's own plugins do this; the Magento 2 patch widens the check the same way. Apply the same rule to any regular expression or allowlist that matches Bolt URLs so a boltapp.com host is not rejected.

Expected result: a shopper signs in with Bolt and your code accepts the token no matter which domain issued it.

Re-copy the Bolt webhook URL into your payment gateway

If you registered a Bolt webhook URL in your payment processor's dashboard, that URL is a Bolt host and it moves with the migration. Open Settings > Payments > Manage your processor in the Merchant Dashboard, copy the webhook URL shown there, and paste it into your processor's webhook configuration. The setup page for your processor under Payment processors shows where each one keeps that setting.

Expected result: a test event from your processor reaches Bolt, and the transaction status updates in the Merchant Dashboard.

Add boltapp.com to your Google Pay merchant profile

This applies only if you registered your own Google Pay merchant ID rather than using Bolt's. The Google Pay console lists the websites allowed to show the Google Pay button, and checkout served from connect.boltapp.com is a different origin from connect.bolt.com. Add connect.boltapp.com to your integration in the Google Pay and Wallet Console, and keep the existing connect.bolt.com entry until Bolt retires it.

Expected result: the Google Pay button renders in Bolt checkout served from connect.boltapp.com.

Update mail filters and bookmarks

Allow @boltapp.com senders in any mail rule that currently allows only @bolt.com. Update saved links to the Merchant Dashboard to merchant.boltapp.com and merchant-sandbox.boltapp.com.

Check your current version

From your Magento root:

composer show boltpay/bolt-magento2 | grep versions

A version in the output means Composer installed the plugin under vendor/boltpay/bolt-magento2. If Composer reports that the package is not found, the plugin was installed by hand under app/code/Bolt/Boltpay: read the version from composer.json in that folder. You can also read the version in Stores > Configuration > Sales > Payment Methods > Bolt Pay.

Expected result: you know your version and where the plugin is installed.

Download and apply the patch in a staging environment first

From your Magento root, download the patch for your version, dry run it, then apply it in maintenance mode and rebuild the store. Replace VERSION with your version:

# Download the patch for your version, if you do not have it yet
curl -fLO https://raw.githubusercontent.com/BoltApp/bolt-magento2/master/patches/boltapp-domains/bolt-magento2-VERSION-boltapp-domains.patch

# Check that the patch applies, without changing any file
patch --dry-run -p1 -d vendor/boltpay/bolt-magento2 < bolt-magento2-VERSION-boltapp-domains.patch

# Enable maintenance mode
php bin/magento maintenance:enable

# Apply the patch
patch -p1 -d vendor/boltpay/bolt-magento2 < bolt-magento2-VERSION-boltapp-domains.patch

# Run upgrade, compilation, and static deployment
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f en_US

php bin/magento cache:clean

# Disable maintenance mode after all steps succeed
php bin/magento maintenance:disable

If the plugin is under app/code/Bolt/Boltpay, use that path after -d in both patch commands. Keep -p1 and -d: the patch file names paths inside the plugin, such as Helper/Config.php, so Adobe's plain patch < FILE from the Magento root cannot find the files and asks File to patch: for each one.

Go past the dry run only if every line it prints starts with checking file. Anything else means the patch does not fit as it stands, and patch changes every file it can, so applying it would leave the plugin partly patched. If the dry run stops at a question, press Ctrl+C. Then:

• File to patch: means the folder after -d is not your plugin folder.
• A line containing FAILED means the patch does not match your version, or a plugin file it changes has local edits. Compare that file with the patch.
• Reversed (or previously applied) patch detected! means the patch is already applied. Skip the apply command.

setup:static-content:deploy -f en_US deploys the en_US locale only. If your storefronts or admin users work in other locales, list them all, for example en_US fr_FR, or leave the list out to deploy every locale in use.

Expected result: the first line of the downloaded file names your plugin version, grep api.boltapp.com vendor/boltpay/bolt-magento2/Helper/Config.php prints the production API URL, the storefront renders the Bolt button, and the browser network tab shows calls to connect.boltapp.com.

Keep the patch applied when Composer reinstalls the plugin

This step applies when Composer manages the plugin. Composer treats vendor/ as its own: whenever it installs the plugin again, it unpacks the original release over your patched files. That happens whenever vendor/ is built from scratch, as most deployment pipelines and every new server do, and each time it does, the store goes back to the bolt.com hosts without any error. Register the patch with the composer-patches plugin, and Composer applies it, with the same patch command as the previous step, every time it installs the plugin. If the plugin is under app/code/Bolt/Boltpay, skip this step and commit the patched files to your repository instead.

From your Magento root, install composer-patches and move the patch file into your project:

composer require cweagans/composer-patches:^1.7
mkdir -p patches
mv bolt-magento2-VERSION-boltapp-domains.patch patches/

When Composer asks whether to trust cweagans/composer-patches, answer y. Then add the patch to the extra section of your root composer.json, next to the keys already there:

"extra": {
    "composer-exit-on-patch-failure": true,
    "patches": {
        "boltpay/bolt-magento2": {
            "Move Bolt hosts to boltapp.com": "patches/bolt-magento2-VERSION-boltapp-domains.patch"
        }
    }
}

Apply it through Composer and record the change in composer.lock:

composer install
composer update --lock

composer install removes the plugin, installs it again, and applies the patch. The plugin files end up the same as after the previous step, so you do not need to rebuild the store again. composer-exit-on-patch-failure makes Composer stop with an error if the patch ever fails to apply, instead of leaving the plugin on bolt.com. Commit composer.json, composer.lock, and the patches folder so that every environment applies the same patch.

The ^1.7 constraint keeps composer-patches on its 1.x line, which works with every PHP and Composer version these plugin releases support. If your project already uses composer-patches 2.x, keep it: skip composer require, add the same patches entry, and run composer patches-relock, composer patches-repatch, and composer update --lock instead of the two commands above.

When you later upgrade the plugin, for example to 3.0.0, remove the patches entry in the same change. The patch fits only the version it was made for, so Composer stops with an error otherwise.

Expected result: composer install prints Applying patches for boltpay/bolt-magento2 followed by the patch file, and grep api.boltapp.com vendor/boltpay/bolt-magento2/Helper/Config.php still prints the production API URL.

Reconnect the Bolt integration

From 2.25.2 on, the patch points the Magento integration record at api.boltapp.com. Open Stores > Configuration > Sales > Payment Methods > Bolt Pay > Advanced Options and choose Create and send API keys to Bolt again so Magento re-authorizes the connection. Versions 2.24.1, 2.24.0, and 2.13.0 have no Bolt integration, so skip this step on them.

Expected result: the integration under System > Integrations shows Active, and a sandbox test order syncs back to Magento.

Remove custom URL overrides

If a developer previously set payment/boltpay/custom_api, custom_cdn, custom_account, or custom_merchant_dash to a bolt.com host, clear them or point them at the boltapp.com equivalent:

php bin/magento config:show payment/boltpay/custom_api
php bin/magento config:set payment/boltpay/custom_api ""

Most stores never set these, and the admin form hides the fields, so read them from the command line rather than looking for them in the UI. Note that the admin form's own validation still only accepts bolt.me URLs, so set any replacement value with bin/magento config:set instead of typing it into the admin.

Verify and repeat in production

Place a sandbox order with a test card and confirm it appears in the sandbox Merchant Dashboard. Then repeat the change in production during a low-traffic window. Release the committed files through your normal deployment; with composer-patches, its composer install applies the patch. Then run the Magento commands from the apply step between maintenance:enable and maintenance:disable, and place a low-value live order.

If you maintain your own csp_whitelist.xml, add the boltapp.com hosts from the table above. The patched plugin's own policy already includes both domains.

Let Bolt refresh the tracking script

Bolt installs track.js into your store through the BigCommerce Script Manager as an entry named bolt-track. New installs already point at connect.boltapp.com. Stores installed before the migration keep the old script until Bolt re-installs it. Bolt runs this update for all stores; you do not need to act, but you can confirm the host under Storefront > Script Manager.

Expected result: the bolt-track entry in Script Manager references connect.boltapp.com.

Update the Bolt scripts you added in Script Manager

Bolt updates only its own bolt-track entry. If you or your developer added a Bolt script through Script Manager, such as connect-bigcommerce.js or your own track.js tag, it keeps loading from bolt.com until you change it.

Open Storefront > Script Manager and check every entry other than bolt-track. For each one whose Script URL or Script contents names a bolt.com host, select Edit, replace the host with the same name on boltapp.com, and select Save. For example, connect.bolt.com becomes connect.boltapp.com and connect-sandbox.bolt.com becomes connect-sandbox.boltapp.com.

Expected result: no entry in Script Manager names a bolt.com host, and the browser's network tab shows those scripts loading from boltapp.com.

Update the scripts you added to your theme

If you followed the BigCommerce installation guide and pasted a connect-bigcommerce.js tag into your Cornerstone theme files, open Storefront > My Themes > Advanced > Edit Theme Files and change any src that reads connect.bolt.com or connect-sandbox.bolt.com to the boltapp.com host:

<script src="https://connect.boltapp.com/connect-bigcommerce.js" ...></script>

If you pasted a track.js tag into a template yourself, change its host the same way. Bolt updates only its own bolt-track entry in Script Manager.

Check cart.html, product.html, the mini-cart template, and the Footer Scripts section.

Expected result: the Bolt button renders on the cart page and the browser's network tab shows the scripts loading from connect.boltapp.com.

Pull the release tag and build the cartridge

Fetch the tags from the repository for your integration, check out the release tag from the table, install dependencies, and build. Do not pull the head of the default branch; it may contain unreleased changes.

For managed checkout (bolt-demandware-managed):

git clone https://github.com/BoltApp/bolt-demandware-managed.git
cd bolt-demandware-managed
git fetch --tags
git checkout bolt-sfcc-managed-26.6.0
npm install
npm run build

For Embeddable Checkout (bolt-demandware-embedded):

git clone https://github.com/BoltApp/bolt-demandware-embedded.git
cd bolt-demandware-embedded
git fetch --tags
git checkout release-23.6.1
npm install
npm run build

If you already have a clone, skip the git clone and cd lines and run the rest from the repository root. If you carry custom changes on top of the Bolt cartridge, create a branch from the release tag and reapply your changes there.

Expected result: git describe --tags prints the release tag, the build completes, and the cartridge folders contain the compiled client scripts.

Upload to a sandbox instance and activate the code version

Point dw.json at your sandbox, upload, then activate the new code version in Administration > Site Development > Code Deployment:

npm run upload:all

If you upload under a new code version name, re-import the Bolt metadata and re-add the cartridges to the cartridge path as described in the SFCC setup guide.

Expected result: Administration > Operations > Service Status shows bolt.http healthy and the Bolt button renders on the cart page.

Invalidate the page cache

Script tags are rendered into cached pages, so a storefront can keep serving the old connect.bolt.com tag after activation. Invalidate the page cache under Administration > Sites > Manage Sites > your site > Cache.

Expected result: view-source on the cart page shows connect.boltapp.com in the Bolt script tags.

Update the storefront CSP

For a Composable Storefront, update the helmet directives in app/ssr.js so every directive that lists *.bolt.com also lists *.boltapp.com, as shown in the Composable Storefront guide. For an SFRA storefront, update any CSP configured at your CDN or in httpHeadersConf.json.

Repeat on staging and production

Deploy the same code version through your normal release process, activate it, invalidate the cache, and place a low-value order.

Check the installed version

In WP Admin > Plugins, find Bolt Checkout for WooCommerce and note the version. Anything below 2.23.1 needs the update, including 2.23.0. The current release is listed on the plugin's directory page at wordpress.org.

Update the plugin on a staging site

In WP Admin > Dashboard > Updates, select Bolt Checkout for WooCommerce and choose Update Plugins. If your host disables updates, download the current release from the plugin directory and install it under Plugins > Add New > Upload Plugin.

Expected result: the plugin row shows version 2.23.1, and Bolt still appears as a payment gateway under WooCommerce > Settings > Payments.

Update the Bolt Extension plugin at the same time

If your store also runs a WooCommerce Bolt Checkout Extensions plugin built for your store, install the matching new build. Running a new core plugin with an old extension plugin breaks checkout features. Delete the old extension plugin, install the new one, and activate it.

Verify and repeat in production

Toggle Bolt Sandbox Mode on, place an order with a test card, then turn sandbox mode off and repeat the update on production. If your store uses Bolt SSO, also sign in with a Bolt account and confirm the login completes.

Check the global scripts in your theme

Open layout/theme.liquid and find the Bolt <link> and <script> tags from the Shopify installation guide. Confirm they load from c.boltapp.com and that data-checkout-link-host ends in .c.boltapp.com:

<link rel="stylesheet" href="https://c.boltapp.com/shopify/bolt-button.css">
<script
  src="https://c.boltapp.com/shopify/bolt-button.js?v="
  data-publishable-key="{PUBLISHABLE_KEY}"
  data-checkout-link-host="{HOST}.c.boltapp.com"
  data-merchant-id="{MERCHANT_ID}"
  defer="defer">
</script>

If either still reads bolt.com, change it to boltapp.com.

Expected result: the Bolt button renders and opens checkout on a .c.boltapp.com host.

Change the API base URL

Set your API base URL to https://api.boltapp.com for production and https://api-sandbox.boltapp.com for sandbox. If you use the environment variable pattern from the Environments page, update BOLT_API_BASE_URL.

Expected result: a call your integration already makes, such as creating an order token, succeeds against the new host and returns the same data as before.

Change the script tags on your storefront

Update the track.js and connect.js tags described in the Direct API guide so they load from connect.boltapp.com or connect-sandbox.boltapp.com.

Accept the token issuer for both domains

If you verify Bolt SSO or OpenID Connect tokens, accept the iss values for both domains as listed in Changes that affect every store. Fetch signing keys from the discovery document on your API base URL rather than a hardcoded JWKS URL so they follow the host change automatically.