DOCS

제품 관리

홈글로벌 이커머스 Catalog 제품 관리

Catalog 관리

제품 생성 및 수정.

Dashboard 또는 API에서 Zonos Catalog 제품을 추가, 수정, 삭제하는 방법을 알아보세요. 코드를 작성하지 않으려는 경우나 소규모로 변경하려는 경우에는 Dashboard의 Catalog를 사용하세요. 프로덕션 구현에서 Catalog와 직접 연동하려면 API를 사용하세요.

Catalog에서 제품을 생성하려면:

  1. Catalog로 이동해 오른쪽 상단의 Add product를 클릭합니다.
  2. 제품 세부 정보를 추가합니다. 제품을 생성하는 데 필요한 필드는 SKU 및/또는 제품 ID 필드뿐입니다. 이 필드는 Catalog 제품을 참조하는 데 사용됩니다. Catalog의 식별자에 대해 자세히 알아보세요.
  3. 선택 사항—HS 코드를 추가합니다.
  4. 선택 사항—배송 정보(중량, 치수, 계량 단위 등)를 추가합니다.
  5. 선택 사항—제한 국가를 추가합니다.
  6. save product를 클릭합니다.

Catalog에서 여러 제품을 생성하려면:

여러 제품 또는 전체 카탈로그를 한 번에 업로드하기.

중요: 이미 존재하는 제품을 다시 생성하려고 하면, Catalog는 SKU 및/또는 product ID를 기준으로 해당 제품을 인식하고 기존 제품의 세부 정보를 새 세부 정보로 덮어씁니다.

DHL 배송의 경우, 제품을 위험물로 태그하면 해당 제품의 라벨을 생성할 때마다 올바른 DHL 부가가치 서비스가 자동으로 적용됩니다. 이는 규제 대상이지만 특례 조항이나 수량 면제하에 배송되는 “저위험” 또는 면제 등급의 규제 품목을 포함합니다.

위험물 태그는 카탈로그 제품의 **속성(attribute)**으로 저장됩니다. 즉, 제품에 대한 key/value 쌍입니다. 속성은 API(catalogItemsCreate 또는 catalogItemsUpdate)를 통해서만 설정할 수 있으며, 이에 해당하는 Dashboard 필드나 CSV 열은 없습니다.

DHL 전용

위험물 태깅은 DHL 배송에만 영향을 미칩니다. 다른 운송업체에서는 태그가 무시됩니다.

지원되는 속성 키

DANGEROUS_GOODS는 DHL 위험물 태깅에 지원되는 속성 키입니다. 아직 ItemAttributeInput 레퍼런스의 승인된 키 목록에는 포함되어 있지 않지만, API에서는 사용할 수 있습니다.

제품에 태그를 지정하려면 키 DANGEROUS_GOODS와 아래 지원되는 카테고리 중 하나를 값으로 하는 속성을 추가하세요.

1mutation CatalogItemsCreate(
2$sku: String!
3$name: String
4$attributes: [ItemAttributeInput!]
5) {
6 catalogItemsCreate(
7 input: [{ sku: $sku, name: $name, attributes: $attributes }]
8 ) {
9 id
10 name
11 sku
12 attributes {
13 key
14 value
15 }
16 }
17}

지원되는 위험물 값

값↕카테고리↕
NOT_RESTRICTED_A70Not Restricted, Special Provision A70—압력 물품(가스 스트럿, 쇼크 업소버 등)(UN3164).
NOT_RESTRICTED_A67Not Restricted, Special Provision A67—가연성 액체로 작동하는 엔진 또는 기계(UN3528).
NOT_RESTRICTED_A02Not Restricted, Special Provision A02—ADR 도로 운송 소량 화물 조항에 따른 면제.
LIMITED_QUANTITYLimited Quantity(ADR)—규제 한도 내 소량으로 포장된 위험물.
EXCEPTED_QUANTITYExcepted Quantity(IATA)—대부분의 항공 운송 위험물 규정에서 면제되는 극소량.
CONSUMER_COMMODITYConsumer commodity ID8000—에어로졸, 향수 등 소량의 위험 성분을 포함한 소매용 일상 제품.
MAGNETIZED_MATERIALMagnetized material(UN2807)—항공기 계기에 영향을 줄 수 있을 만큼 강한 자기장을 가진 품목.
BIOLOGICAL_SUBSTANCEBiological substance(UN3373)—진단용 또는 임상용 검체 등 Category B 생물학적 물질.
라벨에 태그 자동 적용

제품에 태그를 지정하는 것은 첫 단계입니다. Zonos가 DHL 라벨에 카테고리를 자동으로 적용하도록 하려면 라벨 설정에서 Ship dangerous goods를 켜세요. 개별 라벨에서 카테고리를 직접 선택할 수도 있습니다—위험물 신고하기를 참조하세요.

제품을 편집하면 기존 제품에 추가 정보 또는 업데이트된 정보를 효율적으로 반영할 수 있습니다. 제품을 삭제하고 다시 업로드하는 대신, 업데이트된 정보를 업로드하면 Catalog가 item key preference에 따라 SKU 또는 제품 ID를 기준으로 기존 제품과 매칭합니다. 이 방식으로 Dashboard나 API를 사용해 새 제품을 생성하거나 기존 제품을 편집할 때 최소한의 작업으로 카탈로그를 최신 상태로 유지할 수 있습니다.

이미 Catalog에 존재하는 카탈로그 제품을 생성/편집하는 경우 다음과 같이 동작합니다:

Catalog는 기존 품목의 빈 필드를 덮어씁니다.

  • 예를 들어 기존 제품(SKU 321)에 weight 값이 없고, 새로 업로드한 동일한 제품(SKU 321)에 1.3lbs의 weight가 있다면, 이 1.3lbs 값이 이전의 빈 필드를 덮어씁니다.

Catalog는 기존 필드를 새 필드 값으로 덮어씁니다.

  • 예를 들어 기존 제품(SKU 123)의 price가 18.99 USD이고, 동일한 제품(SKU 123)의 업데이트된 price가 22.99 USD라면, 새로운 22.99 USD가 이전 price를 덮어씁니다.

Catalog는 빈 필드로 기존 값을 덮어쓰지 않습니다.

  • 예를 들어 기존 제품(SKU 456)의 HS code가 6109.10이고, 업데이트된 제품(SKU 456)의 HS code가 비어 있다면, 기존 HS code가 그대로 유지됩니다.

제품을 편집하려면:

  1. Products 탭을 클릭합니다.
  2. 편집할 제품을 선택합니다.
  3. 원하는 내용을 변경합니다.
  4. save product를 클릭합니다.

여러 제품 또는 모든 제품을 한 번에 편집하려면 SKU 또는 제품 ID가 포함된 업데이트된 CSV 파일을 Catalog에 업로드하기만 하면 됩니다. 이렇게 하면 기존 품목이 자동으로 업데이트됩니다.

제품을 삭제하려면:

  1. Dashboard에서 Products 탭을 클릭합니다.
  2. 삭제할 제품을 선택합니다. 제품을 선택하면 삭제 버튼이 나타납니다.
  3. Delete를 클릭한 다음 Delete all을 클릭해 삭제를 확인합니다.

모든 제품을 삭제하려면:

  1. Dashboard에서 Products 탭을 선택합니다.
  2. 오른쪽 상단의 Manage Catalog를 클릭한 다음 Delete all을 클릭합니다.
  3. Delete all을 한 번 더 클릭해 삭제를 확인합니다.

대량(약 20,000개 이상)의 품목을 삭제하는 경우, 삭제가 진행 중임을 알리는 알림이 표시됩니다. 이 동안에는 삭제가 완료될 때까지 Catalog를 사용할 수 없습니다. 다만 알림을 닫고 다른 페이지로 이동해도 삭제 프로세스는 중단되지 않습니다.

특정 국가(또는 여러 국가)로의 배송을 제한하려면 제품을 생성하거나 업데이트할 때 제한을 추가할 수 있습니다.

Zonos Duty & Tax 앱은 해외 주문에서 특정 제품만 제외하는 품목 단위 제한을 지원하지 않습니다. 제한된 품목이 카트에 있으면 해당 국가로의 배송 자체가 카트 전체 단위로 차단되어야 합니다. 이는 온보딩 시 사전에 설정해야 하는 카트 단위 제한 규칙으로 처리됩니다. Catalog는 Duty & Tax 앱과 호환되지만, 품목 단위 제한은 Zonos Checkout을 사용할 때만 지원됩니다.

Catalog에서 단일 제품을 제한하려면:

  1. Products 탭을 클릭합니다.
  2. 제한을 추가할 제품을 선택하면 편집 페이지가 열립니다.
  3. 편집 페이지 하단의 Restricted countries 섹션을 찾습니다.
  4. 국가 이름을 선택하거나 입력해 제품을 제한할 국가를 추가합니다.
  5. save product를 클릭합니다.

Catalog에서 여러 제품을 제한하려면:

  1. Import/export 탭을 클릭합니다.
  2. Catalog template CSV를 다운로드합니다.
  3. SKU/Product ID와 제한 국가를 포함해 제품 정보로 템플릿을 작성합니다. 2자리 ISO 코드를 세로 막대로 구분해 입력합니다(예: AU|KR|MY|SG). 모든 국가를 제한하려면 값에 ALL을 입력합니다. 한두 국가를 제외한 모든 국가를 제한하려면 ALL- 뒤에 제한하지 않을 국가를 세로 막대로 구분해 입력합니다(예: ALL-CA|FR|US). CSV 형식에 대해 자세히 알아보세요. 기존에 설정된 제한 국가를 모두 제거하려면 값에 NONE을 입력합니다.
  4. 파일을 CSV로 저장한 다음, CSV를 다운로드한 동일한 페이지에서 드래그 앤 드롭하거나 browse를 클릭해 파일을 선택하여 Catalog에 업로드합니다.
  5. 미리보기 화면에서 업로드한 제품을 확인하고 upload를 클릭합니다.

제한된 제품 필터링:

Dashboard에서 전체 카탈로그를 CSV 형식으로 다운로드해 Excel이나 Google 스프레드시트에서 열면 카탈로그에서 직접 제한된 제품을 필터링할 수 있습니다. 필터링 기능을 사용하면 제한된 제품만 표시할 수 있어, 카탈로그에서 제한된 제품을 쉽게 찾고 관리할 수 있습니다.

CSV 파일을 변경한 후 카탈로그를 업데이트해야 한다면 파일을 다시 업로드하세요. SKU 및/또는 제품 ID를 기준으로 매칭되는 제품이 업데이트된 버전으로 교체됩니다.

Checkout을 사용하는 경우, 제품이 고객의 국가로 제한되어 있으면 Checkout에 제한 메시지가 표시됩니다. 기본적으로 이 메시지는 “This item is restricted from import to your country.”로 표시됩니다.

Dashboard 또는 API를 통해 SKU, 제품 ID, 제품명으로 Catalog에서 제품을 검색할 수 있습니다. SKU 및 제품 ID 검색은 정확히 일치하는 경우에만 결과가 반환되며 부분 일치는 지원되지 않습니다. 다만 제품명으로 검색할 때는 부분 일치가 지원됩니다.

SKU 또는 제품 ID로 필터링하려면:

  1. Dashboard에서 Products 탭을 클릭합니다.
  2. Catalog 왼쪽 상단에서 SKU 또는 Product ID를 선택합니다.
  3. SKU, 제품 ID, 또는 제품명을 입력합니다.
  4. Apply를 클릭해 필터링된 제품을 확인합니다.

제품명으로 검색하려면:

  1. Dashboard에서 Products 탭을 클릭합니다.
  2. Catalog 오른쪽 상단의 검색 필드에 제품명을 입력합니다.
  3. 필터링된 제품을 확인합니다.

Catalog 테이블에서 50개 이하의 품목을 선택하면 카탈로그가 Dashboard에서 직접 다운로드됩니다. 하지만 Export all을 선택하거나 50개를 초과하는 품목을 선택하면 CSV가 이메일로 발송됩니다.

50개 이하의 품목을 내보내려면 다음 단계를 따르세요:

  1. Catalog 테이블에서 50개 이하의 품목을 직접 선택합니다.
  2. 오른쪽 상단의 Export를 클릭합니다.
  3. 이메일 수신함에서 CSV 파일을 확인합니다.

모든 제품을 내보내려면:

  1. Dashboard -> Products -> Catalog로 이동합니다.
  2. Add product 옆의 Manage Catalog 드롭다운을 클릭한 다음 Export all을 클릭합니다.
  3. 다운로드 폴더에서 카탈로그 파일을 확인합니다.

이메일에서 다운로드에 문제가 있나요?

이메일 링크에서 CSV 다운로드에 문제가 있다면 브라우저가 다운로드를 차단했기 때문일 수 있습니다. 이 경우 다음 단계를 따르세요:

  1. 이메일의 "Download" 버튼을 마우스 오른쪽 버튼으로 클릭합니다.
  2. "Copy link address"를 선택해 다운로드 URL을 복사합니다.
  3. 복사한 URL을 브라우저에 붙여넣고 Enter 키를 누릅니다.
  4. 브라우저에서 직접 카탈로그가 다운로드됩니다.

API에서 ClassificationsCreateFromCatalog mutation의 catalogItemId를 사용해 카탈로그의 제품을 Classify할 수 있습니다.

카탈로그의 제품을 Classify하려면 name이 필요합니다. Catalog 및 classification 필드의 전체 목록은 GraphQL API 레퍼런스를 참조하세요.

카탈로그 제품을 생성과 동시에 Classify하려면, 아래의 ClassificationsCreateFromCatalog mutation을 CatalogItemsCreate mutation에 추가하세요.

카탈로그 제품을 8자리 이상(국가별)으로 Classify하기 

shipToCountries 필드가 입력되면 classification은 8자리 이상(국가별) HS 코드가 됩니다. shipToCountries를 지정하지 않으면 classification은 기본적으로 6자리(범용) HS 코드가 됩니다. 범용 HS 코드와 국가별 HS 코드의 차이에 대해 자세히 알아보세요.

아래 예시에서는 캐나다의 국가별 코드를 생성하기 위해 shipToCountries 필드를 지정합니다.

1mutation ClassificationsCreateFromCatalog(
2$catalogItemToClassify: [ClassificationFromCatalogInput!]!
3) {
4 classificationsCalculateFromCatalog(input: $catalogItemToClassify) {
5 id
6 configuration {
7 shipToCountries
8 }
9 hsCode {
10 code
11 }
12 name
13 }
14}

다음은 요청 예시입니다. Zonos Classify는 name만으로도 classification을 생성할 수 있지만, 최상의 classification 결과를 얻으려면 가능한 한 많은 세부 정보를 추가하는 것을 강력히 권장합니다.

1{
2 "catalogItemToClassify": [
3 {
4 "catalogItemId": "catalog_item_893jkdkllg03k9khjd9"

API 오류 및 해결 방법 

오류↕해결 방법↕
A SKU or product ID is required to create a product카탈로그 품목을 생성, 편집, 삭제하려면 식별자(SKU/제품 ID)가 필요합니다. 이를 해결하려면 SKU 및/또는 제품 ID를 추가하세요.
The product you are trying to edit does not exist*존재하지 않는 제품은 편집할 수 없습니다. 이를 해결하려면 원하는 SKU 및/또는 제품 ID로 새 제품을 생성하세요.
Customs description exceeds character limit of 30 characters.기본적으로 customs description은 30자로 제한되며, 이는 상업 송장(commercial invoice)에서 가장 일반적으로 사용되는 문자 제한과 일치합니다.
Product type invalid. Catalog supports the following product types: digital_good. For physical goods, leave it blank.Catalog는 digital_good과 physical_good product type만 지원합니다. 제품이 physical good(가장 일반적인 경우)이라면 이 필드를 비워 두세요.
Packing preference invalid. Catalog supports the following packing preferences: ships_alone and consolidated. If your product can be consolidated with other products, leave blank.Packing preference가 잘못되었습니다. Catalog는 ships_alone과 consolidated packing preference를 지원합니다. 제품을 다른 제품과 함께 포장할 수 있다면 기본값이 consolidated이므로 이 필드를 비워 둘 수 있습니다.
Country must be specified when providing an HS code품목을 생성할 때 국가별 HS code를 지정하면 ship-to country가 필요합니다. 이를 해결하려면 ship-to country를 추가하세요.
Price must be greater than 0Catalog는 음수 price 값을 지원하지 않습니다. 이를 해결하려면 0보다 큰 price를 추가하세요.
Currency code must be provided when a price value is suppliedprice를 지정하는 경우 currency code가 필요합니다. 이를 해결하려면 currency code를 추가하세요.
Price must be provided when a currency code is suppliedcurrency code를 지정하는 경우 price가 필요합니다. 이를 해결하려면 price를 추가하세요.
The accompanying dimensional field cannot be left blank치수 필드 하나를 지정하면 나머지 두 개도 필요합니다. 예를 들어 width로 8 inches를 지정하면 height와 length도 필요합니다.
Measurement value must be greater than 0Catalog는 음수 또는 0인 measurement 값을 지원하지 않습니다. 이를 해결하려면 0보다 큰 값을 추가하세요.
When providing a dimensional value, dimensional units cannot be left empty치수 값을 지정하는 경우 치수 단위가 필요합니다. 이를 해결하려면 치수 단위를 추가하세요.
When providing a weight value, the weight unit cannot be left emptyweight 값을 지정하는 경우 weight 단위가 필요합니다. 이를 해결하려면 weight 단위를 추가하세요.

* API 오류에만 해당

GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

ItemAttributeInput

데모 예약하기

이 페이지가 도움이 되었나요?

지원 받기·법적 문서·© 2026 Zonos
이 페이지에서:
  • Catalog 관리
  • 제품을 위험물로 태그하기(DHL)
  • 제품 Classify