자체 시스템에서 바로 Verified Account 카탈로그를 프로그래밍 방식으로 구축하세요.
Catalog API는 Verified Account 카탈로그를 구축하는 세 가지 방법 중 하나로, 개발 인력이 있고 이미 제품 데이터를 보유한 시스템(ERP, WMS, PIM 또는 배송 플랫폼)을 갖춘 배송업체를 위한 옵션입니다. 해당 시스템이 기준 데이터(source of truth)로 유지되며, 채널 연동에서 동기화하거나 CSV 파일을 업로드하는 대신 Zonos에 제품을 직접 기록합니다. 지원되는 채널을 통해 판매하거나 코드를 작성하고 싶지 않다면, 이 두 가지 옵션으로 더 적은 작업으로 동일한 카탈로그를 구축할 수 있습니다.
API로 생성한 품목은 다른 방식으로 추가한 품목과 완전히 동일하게 처리됩니다. 품목이 카탈로그에 들어오면 Zonos는 어떤 경로로 추가되었는지 구분하지 않습니다. HS 코드를 제공하지 않은 경우 각 품목은 통관을 위해 분류되고, 미국 PGA(Partner Government Agency) 요건에 대해 심사되며, 해당 품목이 포함된 배송물의 관세 및 세금 계산에 사용됩니다.
이 중 한 부분은 API 밖에서 처리됩니다. PGA 심사에서 품목에 조치 필요 플래그가 지정되면, 해당 플래그와 연결된 규정 준수 질문지는 Dashboard에서 답변하고 확인해야 합니다. 이를 위한 API는 없으며, Zonos가 가능한 항목을 미리 채워 두므로 대부분의 작업은 검토하고 확인하는 것입니다. 이 연동을 구축하는 사람과 해당 플래그를 처리하는 사람은 대개 다르므로, 카탈로그가 로드된 후 조직 내 누군가가 Dashboard에서 이를 처리하도록 계획하세요. 플래그가 지정된 품목도 배송이 차단되지는 않지만, 배송 전에 플래그를 해소해야 미국 국경에서 배송물이 보류되는 것을 막을 수 있습니다.
제품에 대한 고유 식별자입니다. *각 제품에는 SKU 또는 product ID(또는 둘 다)가 필요합니다.
productId
예*
플랫폼에서 사용하는 제품 식별자입니다. *각 제품에는 SKU 또는 product ID(또는 둘 다)가 필요합니다.
manufacturerProductId
EU만 해당
비표준 제조업체 제품 식별자(NS-PID)입니다. 150 EUR 이하의 EU행 B2C 배송에 필수입니다.
gtin
EU만 해당
표준 제조업체 제품 식별자(S-PID)로, 숫자만 입력합니다. 제품에 바코드가 있는 경우 150 EUR 이하의 EU행 B2C 배송에 필수입니다.
name
예
제품 이름입니다.
customsDescription
권장
세관 신고용으로, 제품이 무엇인지를 쉬운 말로 설명합니다. "Summer Vibes Tee"가 아니라 "Cotton t-shirt"처럼 작성하세요.
countryOfOrigin
권장
제품이 제조된 국가의 2자리 ISO 코드입니다. 정확한 관세 계산에 필요합니다.
measurements
권장
운임 산정과 세관 신고에 사용되는 무게 및 치수입니다.
hsCode
아니요
국제 공통 6자리 HS 코드입니다. 생략하면 Zonos가 제품 이름과 설명을 바탕으로 제품을 분류합니다.
amount
아니요
숫자로 표시한 제품 가격입니다.
currencyCode
아니요
가격 통화의 3자리 ISO 코드입니다. amount를 제공하는 경우 필수입니다.
itemType
아니요
PHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE 또는 PARTIAL_ITEM입니다. 비물리적 품목이 상품으로 신고되지 않도록 합니다.
provinceOfOrigin
아니요
제품이 생산된 주 또는 도입니다. 일부 도착 국가에서 필수입니다.
productComposition
아니요
{material, percentage} 목록입니다. 이 정보가 없으면 섬유 제품은 6자리를 넘어 분류할 수 없습니다.
catalogItemUrl
아니요
사이트의 제품 페이지 링크입니다. 분류 정확도를 높여 줍니다.
imageUrl
아니요
공개적으로 접근 가능한 제품 이미지 URL입니다. 분류 정확도를 높여 줍니다.
EU 제품 식별자(PID) 추가
Verified Account로 EU에 배송하는 경우, 2026년 11월 1일부터 EU는 150 EUR 이하의 기업-소비자 간(B2C) 배송에 제품 식별자(PID)를 요구합니다. 이 식별자는 카탈로그 품목에 저장하세요. 대부분의 Verified Account에서는 우편 운송사가 Zonos에 배송 데이터를 보내고, Zonos가 배송물의 각 품목을 카탈로그와 매칭해 저장된 식별자를 적용하므로 배송 시점에 별도로 보낼 것이 없습니다.
식별자↕
설명↕
API 필드↕
필수 여부↕
판매자 제품 식별자(M-PID)
SKU 또는 품목 코드
sku
항상
비표준 제조업체 제품 식별자(NS-PID)
제조업체의 모델 번호 또는 부품 번호입니다. 제품을 직접 제조하는 경우 자체 모델 번호 또는 부품 번호를 사용하세요.
manufacturerProductId
항상
표준 제조업체 제품 식별자(S-PID)
바코드(UPC, EAN 또는 ISBN)
gtin
제품에 해당 식별자가 있는 경우만
새 제품은 catalogItemCreate로 식별자를 보내세요. 이미 카탈로그에 있는 제품은 동일한 필드를 받는 catalogItemUpdate로 보내세요. Zonos가 둘을 연결할 수 있도록 각 품목의 sku를 다른 모든 곳에서 사용하는 SKU와 일치시키세요.
Zonos는 식별자를 사용해 각 배송 항목을 카탈로그 품목과 연결하며, 그 순서는 product ID, SKU, name입니다. 어떤 식별자를 사용하든 카탈로그와 운송사에 보내는 데이터 간에 정확하고 일관되게 유지하세요.
우편 배송에는 추가 제약이 있습니다. Zonos는 우편 운송사로부터 제한된 필드만 전달받으며, 많은 경로에서 제품별 정보를 담은 필드는 세관 설명뿐입니다. 카탈로그 전체에서 동일한 설명은 그 자체로는 어떤 제품도 식별할 수 없습니다.
운송사에 보내는 배송 데이터에서 식별자를 어떤 형식으로 보내야 하는지는 우편 운송사에 따라 다릅니다. 우편 운송사마다 배송물을 카탈로그와 매칭하는 방식이 다르기 때문입니다. 모든 우편 운송사로 이동해 사용하는 우편 운송사를 선택하세요. 해당 페이지에서 그 우편 운송사의 매칭 방식과 정확히 무엇을 보내야 하는지 확인할 수 있습니다.
품목의 customsDescription을 운송사에 보내는 문자열과 동일하게 설정할 필요는 없지만, 그렇게 하면 항목이 매칭되지 않아 원인을 파악해야 할 때 양쪽을 직접 비교할 수 있습니다.
매칭은 주로 다음과 같은 경우에 실패합니다:
우편 운송사가 매칭에 사용하는 식별자가 배송 데이터에 없는 경우
식별자가 카탈로그의 어떤 항목과도 정확히 일치하지 않는 경우
운송사의 글자 수 제한으로 식별자가 잘린 경우
배송마다 형식이 달라지는 경우
이 동작은 아직 확정되지 않았으며 출시 전에 변경될 수 있습니다.
카탈로그 품목 업데이트
catalogItemUpdate는 생성과 동일한 입력 타입을 사용합니다. 변경하려는 필드만 보내세요.
Catalog API
Catalog API
자체 시스템에서 바로 Verified Account 카탈로그를 프로그래밍 방식으로 구축하세요.
Catalog API는 Verified Account 카탈로그를 구축하는 세 가지 방법 중 하나로, 개발 인력이 있고 이미 제품 데이터를 보유한 시스템(ERP, WMS, PIM 또는 배송 플랫폼)을 갖춘 배송업체를 위한 옵션입니다. 해당 시스템이 기준 데이터(source of truth)로 유지되며, 채널 연동에서 동기화하거나 CSV 파일을 업로드하는 대신 Zonos에 제품을 직접 기록합니다. 지원되는 채널을 통해 판매하거나 코드를 작성하고 싶지 않다면, 이 두 가지 옵션으로 더 적은 작업으로 동일한 카탈로그를 구축할 수 있습니다.
API로 생성한 품목은 다른 방식으로 추가한 품목과 완전히 동일하게 처리됩니다. 품목이 카탈로그에 들어오면 Zonos는 어떤 경로로 추가되었는지 구분하지 않습니다. HS 코드를 제공하지 않은 경우 각 품목은 통관을 위해 분류되고, 미국 PGA(Partner Government Agency) 요건에 대해 심사되며, 해당 품목이 포함된 배송물의 관세 및 세금 계산에 사용됩니다.
이 중 한 부분은 API 밖에서 처리됩니다. PGA 심사에서 품목에 조치 필요 플래그가 지정되면, 해당 플래그와 연결된 규정 준수 질문지는 Dashboard에서 답변하고 확인해야 합니다. 이를 위한 API는 없으며, Zonos가 가능한 항목을 미리 채워 두므로 대부분의 작업은 검토하고 확인하는 것입니다. 이 연동을 구축하는 사람과 해당 플래그를 처리하는 사람은 대개 다르므로, 카탈로그가 로드된 후 조직 내 누군가가 Dashboard에서 이를 처리하도록 계획하세요. 플래그가 지정된 품목도 배송이 차단되지는 않지만, 배송 전에 플래그를 해소해야 미국 국경에서 배송물이 보류되는 것을 막을 수 있습니다.
작동 방식
배송하는 각 제품에 대해 카탈로그 품목을 생성합니다.
각 품목에 우편 운송사가 전달할 식별자가 포함되어 있는지 확인합니다.
배송 데이터가 Zonos에 도달하면 각 항목이 카탈로그 품목과 매칭되고, 해당 품목의 제품 데이터가 계산에 적용됩니다.
카탈로그 품목 생성
catalogItemCreate는 목록을 입력으로 받으므로 한 번의 요청으로 여러 제품을 보낼 수 있습니다.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}동일한 제품을 두 번 보내는 경우
이미 존재하는 SKU 또는 product ID를 가진 제품을 보내면, Zonos는 새 제품을 추가하지 않고 해당 제품을 업데이트합니다. 따라서 재시도와 반복 실행은 안전합니다.
반대로, SKU 또는 product ID가 같은 서로 다른 두 제품은 하나로 병합됩니다. 대량으로 등록하기 전에 데이터에 중복이 없는지 확인하세요.
필드
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount를 제공하는 경우 필수입니다.itemTypePHYSICAL_GOOD,DIGITAL_GOOD,SERVICE,SUBSCRIPTION,BUNDLE또는PARTIAL_ITEM입니다. 비물리적 품목이 상품으로 신고되지 않도록 합니다.provinceOfOriginproductComposition{material, percentage}목록입니다. 이 정보가 없으면 섬유 제품은 6자리를 넘어 분류할 수 없습니다.catalogItemUrlimageUrlEU 제품 식별자(PID) 추가
Verified Account로 EU에 배송하는 경우, 2026년 11월 1일부터 EU는 150 EUR 이하의 기업-소비자 간(B2C) 배송에 제품 식별자(PID)를 요구합니다. 이 식별자는 카탈로그 품목에 저장하세요. 대부분의 Verified Account에서는 우편 운송사가 Zonos에 배송 데이터를 보내고, Zonos가 배송물의 각 품목을 카탈로그와 매칭해 저장된 식별자를 적용하므로 배송 시점에 별도로 보낼 것이 없습니다.
skumanufacturerProductIdgtin새 제품은
catalogItemCreate로 식별자를 보내세요. 이미 카탈로그에 있는 제품은 동일한 필드를 받는catalogItemUpdate로 보내세요. Zonos가 둘을 연결할 수 있도록 각 품목의sku를 다른 모든 곳에서 사용하는 SKU와 일치시키세요.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {idskumanufacturerProductIdgtin}}gtin은 대시나 공백 없이 숫자만 보내세요. UPC, EAN, JAN 및 13자리 ISBN 값은 모두 이 하나의 필드에 들어갑니다. 10자리 ISBN을 보유하고 있다면 대신 13자리 버전을 보내세요.제품에 바코드가 없다면 빈 문자열을 보내거나, SKU를 재사용하거나,
N/A같은 자리 표시 텍스트를 채우지 말고gtin을 생략하세요.Landed Cost API를 직접 호출하는 경우, Landed Cost 요청에 이 식별자를 포함할 수도 있습니다. 대부분의 Verified Account는 그렇게 하지 않는데, Zonos에 배송 데이터를 보내는 쪽이 우편 운송사이기 때문입니다.
규정에서 요구하는 사항은 EU 제품 식별자 가이드를 참고하세요.
품목을 매칭 가능하게 만들기
Zonos는 식별자를 사용해 각 배송 항목을 카탈로그 품목과 연결하며, 그 순서는 product ID, SKU, name입니다. 어떤 식별자를 사용하든 카탈로그와 운송사에 보내는 데이터 간에 정확하고 일관되게 유지하세요.
우편 배송에는 추가 제약이 있습니다. Zonos는 우편 운송사로부터 제한된 필드만 전달받으며, 많은 경로에서 제품별 정보를 담은 필드는 세관 설명뿐입니다. 카탈로그 전체에서 동일한 설명은 그 자체로는 어떤 제품도 식별할 수 없습니다.
운송사에 보내는 배송 데이터에서 식별자를 어떤 형식으로 보내야 하는지는 우편 운송사에 따라 다릅니다. 우편 운송사마다 배송물을 카탈로그와 매칭하는 방식이 다르기 때문입니다. 모든 우편 운송사로 이동해 사용하는 우편 운송사를 선택하세요. 해당 페이지에서 그 우편 운송사의 매칭 방식과 정확히 무엇을 보내야 하는지 확인할 수 있습니다.
품목의
customsDescription을 운송사에 보내는 문자열과 동일하게 설정할 필요는 없지만, 그렇게 하면 항목이 매칭되지 않아 원인을 파악해야 할 때 양쪽을 직접 비교할 수 있습니다.매칭은 주로 다음과 같은 경우에 실패합니다:
카탈로그 품목 업데이트
catalogItemUpdate는 생성과 동일한 입력 타입을 사용합니다. 변경하려는 필드만 보내세요.mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}품목 다시 조회하기
catalogItem쿼리는id,productId또는sku를 받습니다. Zonos가 제품에 대해 보유한 정보를 확인할 때 사용하세요.query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}카탈로그 품목 삭제
catalogItemDelete는 SKU나 product ID가 아닌 Zonos 카탈로그 품목 ID를 받습니다. 먼저catalogItem쿼리로 ID를 확인하세요.mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}관련 문서
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
이 페이지가 도움이 되었나요?