---
title: "corestack_site_magento_store_mapping_update"
url: https://docs.corefinity.com/mcp/tools/corestack_site_magento_store_mapping_update
type: tool
last_updated: 2026-11-13
feature: magento-stores
related:
  - https://docs.corefinity.com/api/reference/domains/update-site-magento-store-mapping.md
  - https://docs.corefinity.com/guides/sites/go-live/magento-stores.md
---
# corestack_site_magento_store_mapping_update

**Change Magento stores on addresses.** Choose which Magento website or store view each serving address shows. Read corestack_site_magento_stores_list first for both versions. Add new addresses with corestack_domains_update. Scope: write. Long-running: answers with a task.

- Scope: `write`
- Runs as a task: yes

## When to use it

Change which Magento website or store view an existing serving address shows. Read corestack_site_magento_stores_list
first for both versions. To add a new address use corestack_domains_update, or corestack_site_attach_domain before the
site is live. The task follows the whole store change, including the store addresses. Nothing changed answers
`operation: null` and `stores`, without a task. A failed task answers `work_failed` with the store step and its reason
in `details.magento_stores`. The site remains busy until its store work ends.

After the store change completes and before changing DNS:

Request `/` with `corestack_site_smoke_test`, setting `host` to the store domain. The final URL must be on that
store's `base_url` host from `corestack_site_magento_stores_list` (the domain itself, or its bare or `www` form
when the base URL uses it), and the title must be that store's. Magento redirects to the store's base URL; a
redirect to any other host means its base URL points elsewhere.
GraphQL picks its store from the `Store` header, so it cannot prove a domain's store.

## Inputs

- `site_id` (integer, at least 1, required)
- `nginx_version` (integer, at least 0, required): From the stores read.
- `domains_version` (integer, at least 0, required): From the same stores read.
- `default` (object or null): `{code, type}` where type is `website` or `store`; omitted keeps it, null restores Magento's default.
- `hosts` (object): A partial map `host: {code, type}`, or `host: null` to remove a mapping. Omitted hosts stay as they were. Only addresses already serving this site may be changed.
- `point_base_urls` (array of hosts, up to 10): Explicitly point these stores' base URLs here, including addresses currently elsewhere. Ask the person before moving another address. With no explicit choice only the site's own addresses move automatically.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "default": {
      "additionalProperties": false,
      "description": "Default store; null restores Magento's default, omitted keeps it.",
      "properties": {
        "code": {
          "maxLength": 32,
          "minLength": 1,
          "type": "string"
        },
        "type": {
          "enum": [
            "website",
            "store"
          ],
          "type": "string"
        }
      },
      "required": [
        "code",
        "type"
      ],
      "type": [
        "object",
        "null"
      ]
    },
    "domains_version": {
      "minimum": 0,
      "type": "integer"
    },
    "hosts": {
      "description": "Partial map: host => {code, type: website|store}, or null to unmap. Only addresses already serving this site.",
      "type": "object"
    },
    "nginx_version": {
      "minimum": 0,
      "type": "integer"
    },
    "point_base_urls": {
      "description": "Explicitly move these stores' base URLs here, including addresses currently elsewhere. Ask the person first.",
      "items": {
        "maxLength": 253,
        "minLength": 1,
        "type": "string"
      },
      "maxItems": 10,
      "type": "array"
    },
    "site_id": {
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "site_id",
    "nginx_version",
    "domains_version"
  ],
  "type": "object"
}
```

## Refusals

- `not_magento`: this row is not a Magento 2 site.
- `stale`: read both versions again and send the new values.
- `busy`: another site change is running; follow it before trying again.
- `domains_locked`: the site's domains are managed by staff; contact support.
- `deleted`: this site has been deleted.
- `provisioning`: wait for the site to finish being created.
- `removed`: the site is no longer available.
- `managed_elsewhere`: another Control Panel manages this site; use it there.
- `store_hosts`: the site has platform store addresses managed by staff; contact support.
- `store_required`: choose a Magento website or store view for every serving alias.
- `store_unknown`: `hosts.<host>` or `default` identifies the choice. Read the stores again and choose a code Magento lists.
- `store_inactive`: `hosts.<host>` or `default` identifies the choice. Switch the store view on in Magento or choose another.
- `store_code_format`: `hosts.<host>` or `default` identifies the choice. Use a Magento code with lower-case letters, digits or underscores, up to 32 characters.
- `store_host_not_served`: first add the address as an alias that shows its own store.
- `store_mapping_foreign`: the store rules are managed outside the Control Panel; contact support.
- `store_mapping_unreadable`: the existing store rules cannot be read safely; contact support.
- `nginx_rules_not_adopted`: the site's rules are not ready for this change; contact support.
- `nginx_rules_locked`: the site's rules are locked; contact support.
- `nginx_invalid`: the site's existing rules need attention before the store can be changed.
- `upstream_unavailable`: Magento's stores could not be read; try again in a moment.
- The refusals every tool can answer: `invalid_arguments`, `tenant_mismatch`, `scope_required`, `pin_refused`, `rate_limited`, `temporarily_unavailable`, `internal_error` (corestack://guides/how-this-server-works).

## Example

```json
{"name":"corestack_site_magento_store_mapping_update","arguments":{"site_id":4211,"nginx_version":4,"domains_version":3,"hosts":{"guns.example.co.uk":{"code":"guns","type":"website"}}}}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_site_magento_store_mapping_update with site_id 4211, nginx_version 4, domains_version 3, hosts {"guns.example.co.uk":{"code":"guns","type":"website"}}. (Change Magento stores on addresses.) Tell me what it returned.
```

## The same task elsewhere

- Endpoint: [PUT /api/corestack/sites/{site}/magento/store-mapping](https://docs.corefinity.com/api/reference/domains/update-site-magento-store-mapping.md)
- Guide: [Magento stores on separate domains](https://docs.corefinity.com/guides/sites/go-live/magento-stores.md)
