Руководство по полю Handle в CSV Shopify

Что такое Handle в Shopify?

Handle — уникальный идентификатор товара в CSV товаров Shopify. У него две задачи:

1. Группирует строки вариантов — все строки одного товара должны иметь одинаковый Handle. По столбцу Handle Shopify понимает, какие строки относятся друг к другу.
2. Задаёт URL товара — Handle становится частью адреса: yourstore.com/products/<handle>

Handle — самый важный столбец CSV Shopify. Ошибки в Handle приводят к сбоям импорта чаще, чем любое другое поле.

Правила допустимого Handle

Допустимый handle в Shopify должен:

• Быть уникальным среди всех товаров магазина (включая уже существующие)
• Содержать только строчные латинские буквы, цифры и дефисы
• Не содержать пробелов (используйте дефисы)
• Не содержать специальных символов: никаких &, %, ?, /, @ и символов Unicode
• Быть заполненным в каждой строке — пустые handle не допускаются

| Допустимо | Недопустимо | Причина | |---|---|---| | blue-leather-wallet | Blue Leather Wallet | Заглавные буквы и пробелы | | product-123 | product/123 | Содержит косую черту | | mens-running-shoes | men's-running-shoes | Содержит апостроф | | widget-v2 | widget_v2 | Содержит подчёркивание (технически допустимо, но не рекомендуется) | | shirt-sm | `` | Пусто (не допускается) |

Как Handle группирует варианты

В формате CSV Shopify товар с несколькими вариантами занимает несколько строк. Все строки одного товара должны иметь одинаковый Handle:

Handle,Title,Option1 Name,Option1 Value,Variant Price,Variant SKU
blue-wallet,Blue Wallet,Size,Small,29.99,BW-SM
blue-wallet,,Size,Medium,31.99,BW-MD
blue-wallet,,Size,Large,31.99,BW-LG

Читая этот файл, Shopify:

• видит 3 строки с Handle blue-wallet
• создаёт один товар с названием «Blue Wallet»
• создаёт 3 варианта: Small ($29,99), Medium ($31,99), Large ($31,99)
• берёт Title, Body HTML, Vendor и другие поля товара из первой строки

Первая строка (родительская): содержит данные уровня товара (Title, Body HTML, Image Src, Vendor и т. д.) Следующие строки (строки вариантов): имеют тот же Handle, пустой Title и только данные варианта

Частые ошибки Handle

Два товара с одинаковым Handle

Признак: При импорте данные одного товара перезаписывают другой, или варианты разных товаров сливаются в один товар.

Причина: У двух разных товаров в CSV одинаковый Handle.

Решение: Сделайте Handle каждого товара уникальным. Если названия товаров похожи, добавьте отличительную часть:

• blue-wallet и red-wallet (вместо wallet для обоих)
• mens-shirt-v1 и mens-shirt-v2

Handle не совпадает с существующим товаром (непреднамеренное обновление)

Признак: Импорт создаёт новый дубликат товара вместо обновления существующего.

Причина: Handle в вашем CSV не совпадает в точности с Handle существующего товара в Shopify (другой регистр, другое написание, лишний или недостающий дефис).

Решение: Сначала экспортируйте текущие товары из Shopify. В файле экспорта будут точные Handle. Используйте именно их в файле импорта.

Пробелы или заглавные буквы в Handle

Признак: Импорт падает с ошибкой проверки handle, или Shopify автоматически преобразует handle (и получается неожиданный URL).

Решение: В некоторых случаях Shopify сам переводит handle в нижний регистр и заменяет пробелы дефисами, но для импорта CSV лучше заранее отформатировать handle самостоятельно, чтобы избежать непредсказуемых преобразований.

Python — нормализация handle:

import re

def to_shopify_handle(text: str) -> str:
    text = text.lower()
    text = re.sub(r"[^a-z0-9]+", "-", text)
    text = text.strip("-")
    return text

print(to_shopify_handle("Blue Leather Wallet!"))
# blue-leather-wallet

Строки вариантов с разными Handle

Признак: Shopify импортирует каждую строку варианта как отдельный товар (с 0 или 1 вариантом).

Причина: Значение Handle различается в строках, которые должны относиться к одному товару, — часто из-за опечатки или лишнего пробела.

Решение: Отсортируйте CSV по Handle и найдите строки, которые должны иметь общий Handle, но не имеют. Пробел в конце (blue-wallet вместо blue-wallet) — самая частая причина.

Handle и SEO: почему важно не менять Handle

Handle становится URL товара: yourstore.com/products/<handle>. Изменение Handle у уже опубликованных товаров влияет на SEO:

• Старый URL возвращает ошибку 404 (если не настроить перенаправление)
• Ссылки и закладки на старый URL перестают работать
• Поисковые системы, проиндексировавшие старый URL, теряют сигнал ранжирования

Рекомендация: Задавайте Handle правильно с первого раза. Если всё же нужно изменить Handle существующего товара, сразу после импорта настройте перенаправление URL в Shopify (Интернет-магазин → Навигация → Перенаправления URL).

Исправьте автоматически в StriveFormats

StriveFormats проверяет каждый Handle в файле: пустые значения, недопустимые символы и повторяющиеся Handle внутри файла. Он отмечает строки, в которых группировка по Handle не соответствует правилам вариантов Shopify.

Открыть исправитель CSV для Shopify | Посмотреть шаблон Shopify