Shopify CSV Handle 필드 가이드

Shopify Handle이란?

Handle은 Shopify 상품 CSV에서 상품을 고유하게 식별하는 값입니다. 두 가지 역할을 합니다.

1. 변형 행을 묶습니다: 같은 상품의 모든 행은 같은 Handle을 써야 합니다. Shopify는 Handle 열을 읽어 어떤 행끼리 묶이는지 판단합니다.
2. 상품 URL을 정합니다: Handle은 URL 경로가 됩니다: yourstore.com/products/<handle>

Handle은 Shopify CSV에서 가장 중요한 열입니다. Handle 오류는 다른 어떤 필드보다 많은 가져오기 실패를 일으킵니다.

올바른 Handle 규칙

올바른 Shopify handle은 다음 조건을 만족해야 합니다.

• 스토어의 모든 상품(기존 상품 포함) 중에서 고유해야 합니다
• 영문 소문자, 숫자, 하이픈만 사용해야 합니다
• 공백이 없어야 합니다(대신 하이픈 사용)
• 특수 문자가 없어야 합니다: &, %, ?, /, @, 유니코드 문자 사용 불가
• 모든 행에서 비어 있지 않아야 합니다: 빈 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이 변형을 묶는 방식

Shopify CSV 형식에서 변형이 여러 개인 상품은 여러 행을 차지합니다. 같은 상품의 모든 행은 같은 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가 이 파일을 읽으면:

• Handle이 blue-wallet인 행 3개를 확인합니다
• "Blue Wallet"이라는 상품 하나를 만듭니다
• Small(29.99달러), Medium(31.99달러), Large(31.99달러) 변형 3개를 만듭니다
• 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이 기존 상품과 맞지 않음(의도치 않은 새 상품 생성)

증상: 가져오기가 기존 상품을 업데이트하지 않고 중복된 새 상품을 만듭니다.

원인: CSV의 Handle이 Shopify 기존 상품의 Handle과 정확히 일치하지 않습니다(대소문자, 철자, 하이픈 하나 차이 등).

해결 방법: 먼저 Shopify에서 현재 상품을 내보내세요. 내보낸 파일에는 현재 Handle이 정확히 들어 있습니다. 가져오기 파일에는 그 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을 꼭 바꿔야 한다면 가져온 직후 Shopify에서 URL 리디렉션을 설정하세요(온라인 스토어 → 탐색 → URL 리디렉션).

StriveFormats로 자동 수정

StriveFormats는 파일의 모든 Handle을 검사해 빈 값, 잘못된 문자, 파일 안의 중복 Handle을 찾아냅니다. Handle 묶음이 Shopify 변형 규칙을 따르지 않는 행도 표시합니다.

Shopify CSV 수정기 열기 | Shopify 템플릿 보기