주문 일괄 업로드

업로드 페이지에서 CSV template을 직접 다운로드할 수 있습니다. template에는 필수 및 선택 열이 모두 포함되어 있으며, 필수 열은 헤더 행에 별표(*)로 표시됩니다.

품목당 하나의 행

각 행은 하나의 주문이 아니라 하나의 품목을 나타냅니다. 동일한 Order ID를 공유하는 행은 하나의 다중 품목 주문으로 그룹화되므로, 품목이 3개인 주문은 3개의 행으로 구성됩니다. 수령인, 주소, service level, shipping amount, currency, duty paid by, carton과 같은 주문 수준 값은 각 그룹의 첫 번째 행에서 읽어옵니다.

필수 열

각 행에 필요한 정보는 다음 세 가지 범주로 나뉩니다.

Recipient — 수령인의 이름, 전화번호, 배송 주소(목적지 국가 포함)입니다. 이메일은 선택 사항이지만, 입력하면 형식이 검증됩니다. 우편번호와 주/도(state/province)는 해당 국가의 주소 형식에서 사용하는 경우에만 필수입니다. 우편번호가 없는 국가(예: Hong Kong, Tanzania)는 해당 셀을 비워 두면 됩니다. 주/도 목록이 있는 국가에서는 carrier가 목적지를 rate할 수 있도록 인식된 지역 이름 또는 코드(예: Dubai의 경우 "Dubayy" 또는 "DU")를 사용하세요.

Items — 최소한 품목 이름과 가격이 필요합니다. 수량은 선택 사항이며 기본값은 1입니다. HS code와 country of origin을 제공하면 classification 정확도가 향상되고 confirmation screen에서 처리 시간이 단축될 수 있습니다.

Shipping — 계정에 구성된 carrier와 일치하는 service level code(예: fedex.international_priority, ups_worldwide_expedited)입니다. Shipping Amount 열은 선택 사항입니다. 금액(0 허용)을 입력하면 해당 금액이 주문의 shipping charge로 사용되고, 비워 두면 service level에 대한 carrier rate estimate가 계산됩니다. 계산된 행은 confirmation screen에서 각각 몇 초 더 소요되며, label 생성 시 최종 carrier charge는 estimate와 다를 수 있습니다. 일부 목적지는 자동으로 rate할 수 없습니다("service not available for destination country" 오류) — 해당 행에만 shipping amount를 입력하면 됩니다. 한 파일에서 비어 있는 행과 채워진 행을 자유롭게 혼합할 수 있습니다.

선택 열

Recipient tax ID — Tax ID Type 및 Tax ID Number 열을 사용하여 주문에 수령인 tax identifier를 포함할 수 있습니다. type은 아래 코드 중 하나여야 합니다(대소문자 구분 없음). 두 열을 함께 제공해야 하며, type만 있거나 number만 있으면 confirmation screen에서 오류로 표시됩니다. tax ID는 주문 수령인에 저장되며 label 생성 시 carrier에 전달됩니다. 여러 품목 주문의 경우 주문의 첫 번째 행에 있는 tax ID가 사용됩니다.

국가별 코드가 있으면 해당 코드를 사용하고, 목록에 없는 국가는 TIN을 사용하세요.

추가 특수 목적 코드(FED, FTZ, DUN, DAN/TAN/DTF duty and tax deferment account)는 Zonos 담당자가 사용하도록 안내한 경우에만 허용됩니다.

Duty Paid By — 주문별로 선택적 DDP 또는 DDU입니다. 비워 두면 기본 동작이 적용됩니다. 목적지에서 지원하는 경우 DDP, 지원하지 않는 경우 DDU로 자동 fallback합니다. 명시적 DDP는 엄격합니다 — fallback 대신 행이 오류로 처리됩니다. DDU는 배송 시 duties and taxes를 수령인이 부담합니다. confirmation screen과 results download에는 각 주문에 실제로 적용된 값이 표시되며, DDU 행에는 orange badge가 표시됩니다. 여러 품목 주문의 경우 처음 지정된 값이 우선하며, 충돌하는 값은 오류입니다.

Carton quantity — 주문이 동일한 여러 박스로 배송되는 경우 Carton Quantity와 Carton Length/Width/Height/Weight 열을 함께 설정하세요. carton 열은 하나의 박스를 설명합니다(weight는 포장된 박스 하나의 무게). quantity는 이를 곱합니다. 예를 들어 360개를 박스당 30개씩 포장하면 박스 치수, 가득 찬 박스 하나의 무게, carton quantity 12를 사용합니다. 비워 두면 1입니다. 박스 크기가 혼합된 주문은 CSV로 설명할 수 없습니다 — 해당 주문의 carton 열을 비워 두면 Zonos가 품목 무게를 기준으로 자동 boxing합니다.

팁

• carrier settings에 표시된 service level code를 정확히 사용하세요. 인식되지 않는 service level code가 있는 행은 confirmation screen에 경고가 표시됩니다.
• US territory는 다릅니다. US Virgin Islands는 별도 country code(VI)를 사용하며 international로 배송되고, Puerto Rico는 US를 사용하며 domestic으로 배송됩니다.
• Carrier(특히 UPS)는 P.O. Box 배송 주소를 거부합니다 — 주소 줄에 "P.O. Box"가 포함된 행은 일반적인 service availability 오류로 rating에 실패할 수 있습니다. 가능하면 street address를 사용하세요.
• Word 또는 Excel의 typographic punctuation(curly quote, en/em dash)은 자동으로 수정됩니다. accent letter가 있어야 할 자리에 question mark가 나타나면 파일 encoding이 손실된 것입니다 — 해당 행이 표시되므로 텍스트를 다시 입력할 수 있습니다.
• state 또는 province code가 필요한 목적지 국가(예: Brazil, US, Canada)에서는 state 필드에 올바른 ISO code를 입력하세요.
• Order ID는 필수이며 계정 전체에서 고유해야 합니다(이전 업로드 포함) — 이전에 사용된 ID(지난 시즌 파일이나 취소된 주문 포함)는 주문 생성 시 거부됩니다. 파일을 재사용하나요? ID에 suffix를 추가하세요(예: volume 33의 경우 ACALB-33). ID는 confirmation screen에 표시되며 생성된 주문의 merchant reference로 유지됩니다.
• 수령인 이름, 주소, 도시, 주/도(state/province), 회사명, 품목 이름에는 Latin 문자만 사용해야 합니다. 일본어나 아랍어와 같은 non-Latin 문자는 거부됩니다.
• 완전히 비어 있는 행은 무시되므로, 파일 끝에 있는 빈 행은 문제가 되지 않습니다.

표준 template의 모든 열을 template 순서대로 나열합니다. Conditional은 특정 경우에만 해당 열이 필수임을 의미합니다 — 자세한 내용은 위의 필수 열을 참조하세요.

Japan Post는 업로드 페이지에서 동일한 방식으로 다운로드하는 자체 CSV template을 사용합니다. service level 열이 없으며 — 업로드 시 carrier의 첫 번째 service level이 지정되고 label 흐름에서 다시 선택합니다 — 이러한 업로드는 항상 단일 carton으로 배송되므로 carton quantity 열도 없습니다.

표준 template에서는 선택 사항이지만 Japan Post에서는 필수인 열은 다음과 같습니다.

• HS code
• Country of origin
• Item weight — 여기서는 weight unit이 선택 사항으로 유지되며 기본값은 grams입니다
• Postal code
• State/province
• Shipping amount — 표준 template과 달리 비워 둘 수 없습니다

template에는 주문에 저장되고 label 생성 시 배송에 적용되는 Japan Post shipping 필드도 추가됩니다: Contents Type, Licence Number, Certificate Number, Invoice, Tax Code/VAT Number, Pay Condition, Remarks, Sender's Reference Number, Non-commercial. 모두 선택 사항입니다. 텍스트 필드는 최대 25자까지 입력할 수 있으며, Non-commercial은 true 또는 false만 허용합니다.

업로드 후 confirmation screen에 각 주문의 계산된 landed cost breakdown이 표시되며, 주문이 생성되기 전에 검토할 수 있습니다. 화면에는 다음이 표시됩니다.

목적지에서 해당 국가의 de minimis threshold 미만인 신고 가치에 대해 import fee를 부과하지 않는 경우, 행에 duties, taxes, fees가 $0으로 표시될 수 있습니다 — landed cost가 누락된 것이 아니라 실제로 0이며, 해당 주문의 유일한 비용은 shipping입니다.

Create orders 버튼에는 제출될 주문 수가 표시됩니다(예: Create 17 orders). Ready 또는 Warning status의 행만 포함되며, 오류가 있는 행은 제외됩니다.

Download results CSV를 사용하면 전체 quote breakdown(선택된 rate, item total, shipping, duties, taxes, fees, 주문별 총액)을 내보낼 수 있습니다 — 주문 생성 전 고객에게 견적을 제공할 때 유용합니다. Start over를 클릭하면 업로드를 취소하고 수정된 파일로 새로 시작할 수 있습니다.

Shipping Amount를 비워 두면 service level 열에 CSV의 service level과 일치하는 rate가 표시됩니다. 요청한 service level을 목적지에서 사용할 수 없으면 가장 가까운 사용 가능 rate가 선택되고 Different service level badge로 표시됩니다. 여러 대안이 있는 경우 Select a rate dropdown에서 주문 생성 전 rate를 선택할 수 있습니다.

문제는 confirmation screen에 인라인으로 표시됩니다.

오류

오류가 있는 행은 Create orders를 클릭할 때 제외됩니다. CSV에서 문제를 수정하고 다시 업로드하여 해당 행을 포함하세요. 일반적인 오류는 다음과 같습니다.

• Low-value orders not allowed — 주문 가치가 store의 최소 threshold 미만입니다.
• Invalid state code — state 또는 province code가 목적지 국가에 유효하지 않습니다. Brazil, US, Canada 등의 국가에서 필수입니다.
• Missing required field — 필수 열이 비어 있거나 파싱할 수 없습니다.
• Order ID already exists — 각 order ID는 이전 업로드의 주문을 포함하여 계정 전체에서 고유해야 합니다. 이미 사용된 ID가 있는 행은 나머지 파일이 성공해도 생성 시 실패합니다 — fresh ID(예: -33 suffix)로 실패한 행만 다시 업로드하세요.

경고

경고가 있는 행은 제출에 포함됩니다. Create orders를 클릭하기 전에 검토하세요. 일반적인 경고는 다음과 같습니다.

• Service level not configured — CSV의 service level code가 계정에 연결되어 있지 않습니다. 주문은 생성되지만 rating이 올바르지 않을 수 있습니다. carrier settings를 확인하거나 CSV의 service level code를 업데이트하세요.

현재 업로드 limit은 CSV당 200개 주문입니다. 주문은 API call당 최대 50개씩 batch로 제출됩니다 — 업로드에 ready 주문이 50개를 초과하면 여러 batch로 자동 처리됩니다.

Coming soon: 향후 업데이트에서 200개 주문 cap이 제거되고 더 큰 업로드를 위한 background job processing이 추가될 예정입니다.