> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Brand URL Translations

> Translate brand URL paths for multilingual storefronts using the Translations Admin GraphQL API.

# Translations for Brand URLs

> **Note**
>
> The Translations Admin GraphQL API for managing brand URL translations is available on Stencil storefronts only.

The following entities are translatable for brand URLs:

* Brand URL Path
  * URL path as `url_path` — The URL path of the brand on the storefront

## Resource fields

The entities listed above are referenced differently based on resource type and must use the following values in the queries outlined below:

| Entity Type    | `resourceType`    | `resourceId` Format                  |
| -------------- | ----------------- | ------------------------------------ |
| Brand URL Path | `BRAND_URL_PATHS` | `bc/store/brandUrlPath/{{brand_id}}` |

## Querying Brand URL Translations (Storefront API)

Data is returned in the current locale determined by the context (e.g., `Accept-Language` header, channel language settings, or site subfolder). Brand URLs on the storefront reflect the translated URL path; when translations exist for the requested locale, those translated values are returned.

## Managing Brand URL Translations (Admin API)

Brand URL translation management (list, update, delete) is available via the Admin GraphQL API. These mutations and queries are not available on the Storefront API.

### Query a List of Brand URL Translations

#### Request

The request below uses several variables for reusability. Replace `{{channel_id}}` and `{{locale_code}}` with the appropriate values for your use case.

This query returns a paginated list of translations with a maximum of 50 results per request. Use the `cursor` from the response in a subsequent request to fetch more results.

**`Example query: Query a list of translations`**

```graphql title="Example query: Query a list of translations" showLineNumbers={false}
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}

query {
  store {
    translations(filters: {
        resourceType: BRAND_URL_PATHS,
        channelId: "bc/store/channel/{{channel_id}}",
        localeId: "bc/store/locale/{{locale_code}}"
      } first: 50) {
      edges {
        node {
          resourceId
          fields {
            fieldName
            original
            translation
          }
        }
        cursor
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
    }
  }
}
```

#### Response

**`Example query: Query a list of brand URL translations`**

```json title="Example query: Query a list of brand URL translations" showLineNumbers={false}
{
  "data": {
    "store": {
      "translations": {
        "edges": [
          {
            "node": {
              "resourceId": "bc/store/brandUrlPath/1",
              "fields": [
                {
                  "fieldName": "url_path",
                  "original": "/common-good",
                  "translation": "/common-good_es"
                }
              ]
            },
            "cursor": "eyJpZCI6MX0"
          },
          {
            "node": {
              "resourceId": "bc/store/brandUrlPath/2",
              "fields": [
                {
                  "fieldName": "url_path",
                  "original": "/ofs",
                  "translation": null
                }
              ]
            },
            "cursor": "eyJpZCI6Mn0"
          }
        ],
        "pageInfo": {
          "hasNextPage": false,
          "hasPreviousPage": false,
          "startCursor": "eyJpZCI6MX0",
          "endCursor": "eyJpZCI6Mn0"
        }
      }
    }
  }
}
```

### Query a Brand URL Translation by Resource ID

The request below uses several variables for reusability. Replace `{{resourceId}}`, `{{channel_id}}`, and `{{locale_code}}` with appropriate values for your use case. Make sure `resourceId` follows the format from the [Resource fields](#resource-fields) table.

#### Request

**`Example query: Query a brand URL translation by id`**

```graphql title="Example query: Query a brand URL translation by id" showLineNumbers={false}
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}

query {
  store {
    translations(filters: {
      resourceType: BRAND_URL_PATHS,
      channelId: "bc/store/channel/{{channel_id}}",
      localeId: "bc/store/locale/{{locale_code}}",
      resourceIds: ["{{resourceId}}"]
    }) {
      edges {
        node {
          resourceId
          fields {
            fieldName
            original
            translation
          }
        }
        cursor
      }
    }
  }
}
```

#### Response

**`Example query: Query a brand URL translation by id`**

```json title="Example query: Query a brand URL translation by id" showLineNumbers={false}
{
  "data": {
    "store": {
      "translations": {
        "edges": [
          {
            "node": {
              "resourceId": "bc/store/brandUrlPath/1",
              "fields": [
                {
                  "fieldName": "url_path",
                  "original": "/common-good",
                  "translation": "/common-good_es"
                }
              ]
            },
            "cursor": "eyJpZCI6MX0"
          }
        ]
      }
    }
  }
}
```

### Update a Brand URL Translation

#### Request

**`Example mutation: Update a brand URL translation`**

```graphql title="Example mutation: Update a brand URL translation" showLineNumbers={false}
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}

mutation {
  translation {
    updateTranslations(input: {
      resourceType: BRAND_URL_PATHS,
      channelId: "bc/store/channel/{{channel_id}}",
      localeId: "bc/store/locale/{{locale_code}}",
      entities: [
        {
          resourceId: "bc/store/brandUrlPath/1",
          fields: [
            { fieldName: "url_path", value: "/common-good_es" }
          ]
        }
      ]
    }) {
      __typename
      errors {
        __typename
        ... on Error {
          message
        }
      }
    }
  }
}
```

#### Response

**`Example mutation: Update a brand URL translation`**

```json title="Example mutation: Update a brand URL translation" showLineNumbers={false}
{
  "data": {
    "translation": {
      "updateTranslations": {
        "__typename": "UpdateTranslationsResult",
        "errors": []
      }
    }
  }
}
```

#### Response with errors

**`Example mutation: Update a brand URL translation for a missing entity`**

```json title="Example mutation: Update a brand URL translation for a missing entity" showLineNumbers={false}
{
  "data": {
    "translation": {
      "updateTranslations": {
        "__typename": "UpdateTranslationsResult",
        "errors": [
          {
            "__typename": "EntityNotFoundError",
            "message": "Entity bc/store/brandUrlPath/11 not found."
          }
        ]
      }
    }
  }
}
```

### Delete a Brand URL Translation

#### Request

**`Example mutation: Delete a brand URL translation`**

```graphql title="Example mutation: Delete a brand URL translation" showLineNumbers={false}
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}

mutation {
  translation {
    deleteTranslations(input: {
      resourceType: BRAND_URL_PATHS,
      channelId: "bc/store/channel/{{channel_id}}",
      localeId: "bc/store/locale/{{locale_code}}",
      resources: [
        {
          resourceId: "bc/store/brandUrlPath/1",
          fields: ["url_path"]
        }
      ]
    }) {
      __typename
      errors {
        __typename
        ... on Error {
          message
        }
      }
    }
  }
}
```

#### Response

**`Example mutation: Delete a brand URL translation`**

```json title="Example mutation: Delete a brand URL translation" showLineNumbers={false}
{
  "data": {
    "translation": {
      "deleteTranslations": {
        "__typename": "DeleteTranslationsResult",
        "errors": []
      }
    }
  }
}
```

#### Response with errors

**`Example mutation: Delete a brand URL translation for a missing entity`**

```json title="Example mutation: Delete a brand URL translation for a missing entity" showLineNumbers={false}
{
  "data": {
    "translation": {
      "deleteTranslations": {
        "__typename": "DeleteTranslationsResult",
        "errors": [
          {
            "__typename": "EntityNotFoundError",
            "message": "Entity bc/store/brandUrlPath/11 not found."
          }
        ]
      }
    }
  }
}
```