# Move your integration to boltapp.com

> Bolt is moving its services from bolt.com to boltapp.com. Review the breaking changes, then upgrade your cart platform plugin and update anything on your side that names a bolt.com host.

Source: https://help.boltapp.com/platforms/boltapp-domain-migration

## Overview [#overview]

Bolt is moving its services from `bolt.com` to `boltapp.com`. Every Bolt host your store talks to gets a `boltapp.com` twin: `api.boltapp.com`, `connect.boltapp.com`, `account.boltapp.com`, and `merchant.boltapp.com`, with the same `-sandbox` variants as before. The [Environments](/api-reference/environments) page lists the current sandbox and production URLs.

The `boltapp.com` hosts serve all Bolt traffic. Anything still pointing at a `bolt.com` host stops working once that host is deprecated. Older Bolt plugins have the `bolt.com` hosts built in, so the fix for most stores is a plugin upgrade.

<Warning>
  **`boltapp.com` is Bolt's permanent domain.** Bolt's own site has already moved, and `api.bolt.com`, `connect.bolt.com`, and every other `bolt.com` sub-domain will be deprecated. Once they are, a store that still uses `bolt.com` hosts loses the Bolt button, checkout, and the plugin's calls to the Bolt API. Upgrade now to the version listed for your platform under [Choose your platform](#choose-your-platform) to move your store to `boltapp.com`.
</Warning>

## What is changing [#what-is-changing]

| Area                                               | Before                                                | After                                                | What breaks if you do nothing                                                                                                |
| -------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Bolt API your plugin calls                         | `api.bolt.com`, `api-sandbox.bolt.com`                | `api.boltapp.com`, `api-sandbox.boltapp.com`         | Order creation, authorization, refunds, and every other server call from the plugin fail whenever `bolt.com` is unavailable. |
| Checkout scripts on your storefront                | `connect.bolt.com/track.js`, `connect.js`, `embed.js` | `connect.boltapp.com/...`                            | The Bolt button and checkout modal stop loading.                                                                             |
| Shopper accounts                                   | `account.bolt.com`                                    | `account.boltapp.com`                                | Shopper login, one-click checkout, and SSO Commerce stop working.                                                            |
| Merchant Dashboard                                 | `merchant.bolt.com`                                   | [merchant.boltapp.com](https://merchant.boltapp.com) | Bookmarks and links in older plugin admin screens stop resolving.                                                            |
| Emails from Bolt                                   | `@bolt.com` senders                                   | `@boltapp.com` senders                               | Mail rules that only allow `@bolt.com` drop Bolt notifications.                                                              |
| User-Agent on calls Bolt makes to your store       | `Bolt - https://www.bolt.com`                         | `Bolt - https://www.boltapp.com`                     | Firewall or bot rules that match the old string block Bolt's webhook and shipping calls.                                     |
| Webhook URL you registered in your payment gateway | Bolt webhook URL on a `bolt.com` host                 | The same URL on a `boltapp.com` host                 | Bolt stops receiving transaction updates from your processor.                                                                |

## What is not changing [#what-is-not-changing]

* **Your API keys, signing secret, and publishable keys.** Upgrading does not change your credentials. Keep the same values in the plugin.
* **Your callback URLs.** The webhook, shipping, tax, and create-order URLs under **Administration > API > Merchant Callbacks** are on your domain, so they stay as they are.
* **Bolt's outbound IP addresses.** If you allowlist Bolt's IPs for callbacks or a payment processor, that list is the same. See the processor setup pages under [Payment processors](/integrations/payment-processors).
* **Your SSO signing keys, audience, and shopper claims.** Only the `iss` claim varies by domain, and code that validates it needs to accept both. See [Changes that affect every store](#changes-that-affect-every-store).
* **Your Trusted Domains.** The storefront domains you registered with Bolt are your own domains and need no change.

## Changes that affect every store [#changes-that-affect-every-store]

Work through these regardless of platform. Do them before the plugin upgrade so the new hosts are reachable the moment the plugin switches.

<Steps>
  <Step title="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.

    | Directive     | Add                                                                                                        |
    | ------------- | ---------------------------------------------------------------------------------------------------------- |
    | `script-src`  | `connect.boltapp.com`, `connect-sandbox.boltapp.com`, `account.boltapp.com`, `account-sandbox.boltapp.com` |
    | `frame-src`   | `connect.boltapp.com`, `connect-sandbox.boltapp.com`, `account.boltapp.com`, `account-sandbox.boltapp.com` |
    | `connect-src` | `api.boltapp.com`, `api-sandbox.boltapp.com`, `connect.boltapp.com`, `connect-sandbox.boltapp.com`         |
    | `img-src`     | `img.boltapp.com`, `img-sandbox.boltapp.com`, `assets.boltapp.com`                                         |

    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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`:

    ```text title="Accepted iss values"
    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.
  </Step>

  <Step title="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](https://merchant.boltapp.com), copy the webhook URL shown there, and paste it into your processor's webhook configuration. The setup page for your processor under [Payment processors](/integrations/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.
  </Step>

  <Step title="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](https://pay.google.com/business/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`.
  </Step>

  <Step title="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](https://merchant.boltapp.com) and [merchant-sandbox.boltapp.com](https://merchant-sandbox.boltapp.com).
  </Step>
</Steps>

## Choose your platform [#choose-your-platform]

Work through [Changes that affect every store](#changes-that-affect-every-store) first. Then follow the section for your platform. Each one lists the versions in use, what carries `boltapp.com`, and the steps to get there.

* [Adobe Commerce and Magento 2](#adobe-commerce-and-magento-2)
* [BigCommerce](#bigcommerce)
* [Salesforce Commerce Cloud](#salesforce-commerce-cloud)
* [WooCommerce](#woocommerce)
* [Shopify](#shopify)
* [SAP Commerce Cloud, Solidus, and Volusion](#sap-commerce-cloud-solidus-and-volusion)
* [Direct API and custom carts](#direct-api-and-custom-carts)

### Adobe Commerce and Magento 2 [#adobe-commerce-and-magento-2]

The `boltpay/bolt-magento2` plugin has the Bolt hosts compiled into `Helper/Config.php`. Every release up to and including 2.27.8 points at `bolt.com`. Version 3.0.0 and later already point at `boltapp.com` and need no change.

For each earlier version in the table below, Bolt publishes a patch file in the [patches/boltapp-domains](https://github.com/BoltApp/bolt-magento2/tree/master/patches/boltapp-domains) folder of the plugin repository. The patch keeps you on the version you run today. You apply it with the `patch` command, following Adobe's [command-line method for applying patches](https://experienceleague.adobe.com/en/docs/commerce-operations/upgrade-guide/patches/apply#command-line). If Composer manages the plugin, you also register the patch with the [cweagans/composer-patches](https://github.com/cweagans/composer-patches) plugin, so that Composer applies it again whenever it reinstalls the plugin.

Every edit in the patch belongs to the move to `boltapp.com`. It adds the `boltapp.com` hosts to `csp_whitelist.xml` next to the existing `bolt.com` entries and accepts SSO tokens from both domains, so the plugin keeps working on either domain during the transition. It also accepts `boltapp.com` custom URLs and updates the `bolt.com` link in the copyright header of every plugin file, which is why the patch touches several hundred files. Version 2.13.0 predates the plugin's CSP policy and its SSO support, so its patch carries neither of those changes.

**Plugin versions in use and their boltapp.com patch**

Find the version you run today and use the patch file on its row. Each patch is built for that version alone, and another version's patch fails its dry run.

| Version in use | Patch file                                   |
| -------------- | -------------------------------------------- |
| 2.27.8         | `bolt-magento2-2.27.8-boltapp-domains.patch` |
| 2.27.7         | `bolt-magento2-2.27.7-boltapp-domains.patch` |
| 2.27.5         | `bolt-magento2-2.27.5-boltapp-domains.patch` |
| 2.27.4         | `bolt-magento2-2.27.4-boltapp-domains.patch` |
| 2.27.3         | `bolt-magento2-2.27.3-boltapp-domains.patch` |
| 2.27.2         | `bolt-magento2-2.27.2-boltapp-domains.patch` |
| 2.27.1         | `bolt-magento2-2.27.1-boltapp-domains.patch` |
| 2.26.4         | `bolt-magento2-2.26.4-boltapp-domains.patch` |
| 2.26.1         | `bolt-magento2-2.26.1-boltapp-domains.patch` |
| 2.25.2         | `bolt-magento2-2.25.2-boltapp-domains.patch` |
| 2.24.1         | `bolt-magento2-2.24.1-boltapp-domains.patch` |
| 2.24.0         | `bolt-magento2-2.24.0-boltapp-domains.patch` |
| 2.13.0         | `bolt-magento2-2.13.0-boltapp-domains.patch` |

<Note>
  If your version is not in the table, upgrade to 3.0.0. If `composer show` reports a `dev-` version, such as `dev-2.27.8.yourstore`, your store runs a build Bolt made for it, and the patch for its base version may not fit. [Contact Bolt support](/support) before you patch it.
</Note>

**Which steps you need**

* **Composer installed the plugin**, so it lives in `vendor/boltpay/bolt-magento2`: every step. Step 2 checks that the patch fits and patches the plugin right away. Step 3 has Composer apply the patch again each time it reinstalls the plugin, which keeps the change in place and carries it to production.
* **You installed the plugin by hand**, so it lives in `app/code/Bolt/Boltpay`: every step except step 3. Composer never replaces `app/code`, so committing the patched files keeps the change.

<Steps>
  <Step title="Check your current version">
    From your Magento root:

    ```bash title="Terminal"
    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.
  </Step>

  <Step title="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:

    ```bash title="Terminal"
    # 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`.
  </Step>

  <Step title="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:

    ```bash title="Terminal"
    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:

    ```json title="composer.json"
    "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`:

    ```bash title="Terminal"
    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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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:

    ```bash title="Terminal"
    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.
  </Step>

  <Step title="Verify and repeat in production">
    Place a sandbox order with a [test card](/getting-started/test-cards) 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.
  </Step>
</Steps>

The [Adobe Commerce setup guide](/platforms/adobe) covers the full configuration if you need to reinstall.

<Warning>
  **Magento 1 is not covered.** The separate `bolt-magento1` plugin ended at 2.10.0 and is no longer maintained, so there is no `boltapp.com` release and no patch for it. If your store still runs Bolt on Magento 1, [contact Bolt support](/support) before the cutover to plan a move to a supported platform.
</Warning>

### BigCommerce [#bigcommerce]

Bolt runs the BigCommerce app itself, so there is no plugin package to upgrade. Three things on your side can still reference `bolt.com`: Bolt's tracking script, Bolt scripts you added in Script Manager, and Bolt script tags in your theme.

**Plugin versions in use and their boltapp.com patch**

Bolt hosts the BigCommerce app, so there is no plugin version to track. The only versioned Bolt code on your side is the Bolt script tags you added, in Script Manager or in your theme.

| Component                                      | Version                         | Action                                          |
| ---------------------------------------------- | ------------------------------- | ----------------------------------------------- |
| Bolt app (BigCommerce App Marketplace)         | Always current, managed by Bolt | None.                                           |
| Bolt scripts you added in Script Manager       | Whatever each script references | Point them at `connect.boltapp.com`, see below. |
| Theme script tags (`connect-bigcommerce.js`)   | Whatever your theme references  | Point them at `connect.boltapp.com`, see below. |
| Bolt Checkout for BigCommerce WordPress plugin | 1.0.0                           | No update exists. Contact Bolt.                 |

<Steps>
  <Step title="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`.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Update the scripts you added to your theme">
    If you followed the [BigCommerce installation guide](/platforms/bigcommerce-full) 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:

    ```html title="Theme template"
    <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`.
  </Step>
</Steps>

<Warning>
  If you run BigCommerce on WordPress with the **Bolt Checkout for BigCommerce** WordPress plugin, that plugin is version 1.0.0 from 2019 and has `bolt.com` built in with no update available. [Contact Bolt support](/support) before the cutover to plan a replacement.
</Warning>

### Salesforce Commerce Cloud [#salesforce-commerce-cloud]

Every Bolt cartridge has the hosts compiled into cartridge code. Site preferences only select the environment, and the `bolt.http` service has no URL in its credential, so the only way to move a Salesforce Commerce Cloud (SFCC) storefront is to deploy an updated cartridge. Metadata imports and service definitions do not need to change.

**Plugin versions in use and their boltapp.com patch**

The cartridges do not report their version to Bolt, so these rows come from the cartridge releases rather than from traffic. Read the version from `package.json` in the cartridge or from **Administration > Site Development > Code Deployment**.

| Integration                     | Repository                 | Release line in use | Version with boltapp.com | Release tag                | Action                                                        |
| ------------------------------- | -------------------------- | ------------------- | ------------------------ | -------------------------- | ------------------------------------------------------------- |
| SFRA V2 (managed checkout)      | `bolt-demandware-managed`  | 25.1.x and older    | 26.6.0                   | `bolt-sfcc-managed-26.6.0` | Deploy 26.6.0.                                                |
| Embeddable Checkout             | `bolt-demandware-embedded` | 23.5.x and older    | 23.6.1                   | `release-23.6.1`           | Deploy 23.6.1.                                                |
| Legacy SiteGenesis or SFRA 21.x | `bolt-demandware`          | 21.4.x              | None planned             | Move to SFRA V2            | This repository is deprecated. Contact Bolt to plan the move. |

<Steps>
  <Step title="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`):

    ```bash title="Terminal"
    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`):

    ```bash title="Terminal"
    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.
  </Step>

  <Step title="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**:

    ```bash title="Terminal"
    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](/platforms/salesforce).

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

  <Step title="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.
  </Step>

  <Step title="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](/platforms/salesforce/sfcc-sfra-v2/sfcc-composable/). For an SFRA storefront, update any CSP configured at your CDN or in `httpHeadersConf.json`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### WooCommerce [#woocommerce]

The **Bolt Checkout for WooCommerce** plugin is distributed through the WordPress plugin directory. Upgrading to 2.23.1 or newer is the whole fix, with one caveat for the companion extension plugin.

**Plugin versions in use and their boltapp.com patch**

Find the version you run today under **WP Admin > Plugins**, then upgrade to 2.23.1. There are no patch releases for older lines.

| Version in use   | Version to install | Action                                                                                   |
| ---------------- | ------------------ | ---------------------------------------------------------------------------------------- |
| 2.23.0           | 2.23.1             | Upgrade to 2.23.1. 2.23.0 already uses `boltapp.com`, but it can reject Bolt SSO logins. |
| 2.22.x and older | 2.23.1             | Upgrade to 2.23.1.                                                                       |

<Steps>
  <Step title="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](https://wordpress.org/plugins/bolt-checkout-woocommerce/).
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Verify and repeat in production">
    Toggle **Bolt Sandbox Mode** on, place an order with a [test card](/getting-started/test-cards), 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.
  </Step>
</Steps>

### Shopify [#shopify]

Bolt hosts the Shopify integration, so there is no app package to upgrade. Check the snippet you pasted into your theme.

**Plugin versions in use and their boltapp.com patch**

Bolt hosts the Shopify integration, so there is no plugin version to track.

| Component                              | Version                         | Action                                            |
| -------------------------------------- | ------------------------------- | ------------------------------------------------- |
| Bolt Checkout Everywhere app           | Always current, managed by Bolt | None.                                             |
| Theme snippet in `layout/theme.liquid` | Whatever your theme references  | Confirm it loads from `c.boltapp.com`, see below. |

<Steps>
  <Step title="Check the global scripts in your theme">
    Open `layout/theme.liquid` and find the Bolt `<link>` and `<script>` tags from the [Shopify installation guide](/platforms/shopify-installation). Confirm they load from `c.boltapp.com` and that `data-checkout-link-host` ends in `.c.boltapp.com`:

    ```html title="theme.liquid"
    <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.
  </Step>
</Steps>

### SAP Commerce Cloud, Solidus, and Volusion [#sap-commerce-cloud-solidus-and-volusion]

These integrations are delivered by your Bolt customer success manager rather than through a public package registry.

**Plugin versions in use and their boltapp.com patch**

These integrations are not published to a package registry, so Bolt does not track a release line for them.

| Platform           | Release line in use         | Patch release with boltapp.com | Action                                                     |
| ------------------ | --------------------------- | ------------------------------ | ---------------------------------------------------------- |
| SAP Commerce Cloud | Build delivered by Bolt     | Next build from Bolt           | Request the current `boltbackoffice` and `boltocc` build.  |
| Solidus            | Bolt gems in your `Gemfile` | Next gem release               | Update the gems and run `bundle update`.                   |
| Volusion           | Files in `vspfiles`         | Next file set from Bolt        | Request the current plugin files and edit the script tags. |

* **SAP Commerce Cloud (hybris):** request the current `boltbackoffice` and `boltocc` extension build from Bolt, deploy it through your normal hybris release process, and update any `bolt.com` host in your Spartacus environment configuration. See [Set up Bolt on SAP Commerce Cloud](/platforms/sap).
* **Solidus:** update the Bolt gems in your `Gemfile` to the current release and run `bundle update`, then check any initializer that sets a Bolt API host. See [Set up Bolt on Solidus](/platforms/solidus).
* **Volusion:** the plugin lives in your store's `vspfiles` folder and the script tags are in your template. Request the current plugin files from Bolt, upload them over sFTP, and edit the `track.js` and `connect.js` tags in your template so they load from `connect.boltapp.com` or `connect-sandbox.boltapp.com`. See [Set up Bolt on Volusion](/platforms/volusion).

### Direct API and custom carts [#direct-api-and-custom-carts]

If you call the Bolt API directly, you control every host, so no plugin upgrade applies.

**Plugin versions in use and their boltapp.com patch**

Not applicable. You call the Bolt API directly, so there is no Bolt plugin or release line on your side. The hosts you need to change are listed in the steps below.

<Steps>
  <Step title="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](/api-reference/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.
  </Step>

  <Step title="Change the script tags on your storefront">
    Update the `track.js` and `connect.js` tags described in the [Direct API guide](/platforms/direct-api) so they load from `connect.boltapp.com` or `connect-sandbox.boltapp.com`.
  </Step>

  <Step title="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](#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.
  </Step>
</Steps>

## Verify the migration [#verify-the-migration]

After upgrading, confirm each of these on your live store:

1. The browser's network tab shows Bolt scripts loading from `connect.boltapp.com`, with no CSP errors in the console.
2. A low-value order completes and appears under **Transactions** in the [Merchant Dashboard](https://merchant.boltapp.com).
3. Your server logs show the order webhook from Bolt arriving with a 2xx response.
4. A shopper can log in with a Bolt account, if you use SSO Commerce or one-click checkout.

## If something goes wrong [#if-something-goes-wrong]

Roll back to the previous plugin version, then [contact Bolt support](/support) with your merchant ID, platform, and the plugin versions you moved between. A rollback puts your store back on `bolt.com` hosts, which Bolt is deprecating. Treat it as a stopgap and move forward to `boltapp.com` as soon as Bolt support helps you fix the problem.