DOCS
Checkout•
홈글로벌 이커머스 Zonos Checkout Customer profiles 세금 면제

세금 면제

미국 판매세 면세 증명서를 customer profile에 동기화하세요.

재판매업체, 정부 기관, 비영리 단체에 판매하는 경우, 그러한 구매자는 특정 주에서 판매세가 면제되는 면세 증명서를 보유하고 있습니다. Zonos는 그러한 증명서를 customer profile에 저장하여 면세 구매자를 Checkout에서 인식할 수 있도록 합니다.

면제는 관할 구역별로 기록됩니다. 사우스캐롤라이나에서 면세인 고객이 텍사스에서 자동으로 면세되는 것은 아니므로, 고객이 증명서를 보유한 각 주는 자체 날짜와 증명서 번호를 가진 별도의 레코드로 관리됩니다.

면제는 기존 고객에게 연결되므로, 동기화는 두 번의 호출로 이루어집니다. 먼저 고객을 생성하고, 그런 다음 해당 고객의 증명서를 동기화합니다. 두 호출 모두 귀하가 Checkout 전반에서 사용하는 것과 동일한 customerId, 즉 귀하 고유의 고객 ID를 키로 사용합니다. Zonos는 내부 ID를 별도로 저장하도록 요구하지 않습니다.

이 기능은 커스텀 API 통합에서만 사용할 수 있습니다.

면제는 아직 landed cost 견적에 적용되지 않습니다

지금도 면제를 동기화하고 관리할 수 있으며, 레코드는 customer profile에 저장됩니다. landed cost의 세금에서 면제를 차감하는 기능은 곧 제공될 예정이므로, 동기화된 면제가 아직은 쇼퍼에게 제시되는 견적 세금을 변경하지는 않습니다. 지금 동기화해 두면 해당 기능이 제공될 때 증명서가 이미 준비되어 있게 됩니다.

고객 생성 또는 업데이트 

checkoutCustomerUpsert는 customer profile을 생성하며, 해당 customerId로 이미 존재하는 경우에는 업데이트합니다. checkoutCustomerProfileAuthenticate와 달리 쇼퍼가 있을 필요가 없으므로, 고객 목록을 미리 준비해 둘 수 있습니다. 전체 필드 동작은 쇼퍼 없이 프로필 생성 또는 업데이트를 참조하세요.

1mutation checkoutCustomerUpsert($input: CheckoutCustomerProfileInput!) {
2 checkoutCustomerUpsert(input: $input) {
3 customerId
4 email
5 name
6 phone
7 }
8}

customerId를 기준으로 매칭되므로, 반복 호출해도 중복 생성 없이 동일한 프로필이 업데이트됩니다. 매번 동기화할 때마다 전체 고객 목록에 대해 실행해도 안전합니다.

세금 면제 동기화 

checkoutCustomerTaxExemptionsSync는 여러 고객을 한 번에 받습니다. 각 항목은 해당 고객의 전체 면제 세트를 대체합니다.

1mutation checkoutCustomerTaxExemptionsSync(
2$input: [CheckoutCustomerTaxExemptionSyncInput!]!
3) {
4 checkoutCustomerTaxExemptionsSync(input: $input) {
5 customerId
6 accepted {
7 id
8 countryCode
9 administrativeArea
10 effectiveAt
11 expiresAt
12 exemptionReason
13 }
14 rejected {
15 code
16 message
17 administrativeArea
18 effectiveAt
19 }
20 }
21}

expiresAt을 생략하면 증명서가 만료되지 않는다는 의미입니다. exemptionReason을 생략하면 기본값은 UNSPECIFIED입니다.

동기화 동작 방식 

모든 동기화에는 세 가지 규칙이 적용됩니다.

목록이 기준입니다. taxExemptions는 변경 사항의 목록이 아니라 고객의 전체 세트입니다. 이미 기록되어 있는 면제 중 목록에서 빠진 항목은 제거됩니다. 이것이 철회된 증명서가 더 이상 적용되지 않게 되는 방식입니다. 목록 일부만 보내면 거기에 포함되지 않은 항목은 조용히 제거됩니다.

모든 레코드는 면제입니다. 고객이 특정 지역에서 면제 대상이 아니라는 것을 기록할 방법은 없습니다 — 아래 참고 사항을 확인하세요.

모든 면제를 제거하려면 빈 목록을 보냅니다. 고객의 증명서를 모두 삭제하려면 "taxExemptions": []로 보내세요. 고객을 payload에서 아예 빠뜨리면 기존 레코드는 그대로 유지됩니다.

고객이 면제 대상인 관할 구역만 보내세요

Zonos에는 "면제 대상 아님" 레코드가 없습니다 — 관할 구역은 목록에 있거나 없거나 둘 중 하나입니다. 귀하의 시스템이 면제 대상과 비면제 대상 관할 구역을 함께 저장한다면, 동기화하기 전에 면제 대상만 걸러내세요. 비면제 레코드는 실제 증명서와 구분할 수 없으므로 거부되지 않고 수락되며, 해당 고객은 그 주에서 면제 대상으로 처리됩니다.

면제 사유 

exemptionReason은 고객이 면제 대상인 이유를 설명합니다. 선택 사항이며 기본값은 UNSPECIFIED이지만, 값을 제공할 만한 가치가 있습니다 — 아래를 참조하세요.

Value↕Applies to↕
RESALE소비가 아니라 재판매를 위해 구매한 상품
FEDERAL_GOVERNMENT미국 연방 기관 또는 부처
STATE_LOCAL_GOVERNMENT주 기관, 카운티, 지자체, 또는 교육구
TRIBAL_GOVERNMENT연방 인정 부족(tribe) 또는 부족 구성원
CHARITABLE자선 비영리 단체
RELIGIOUS_ORGANIZATION교회 또는 기타 종교 단체
EDUCATIONAL_ORGANIZATION학교 또는 대학
DIRECT_PAYdirect pay permit을 보유하고 직접 세금을 납부하는 구매자
OTHER외국 외교관, 농업 생산, 산업 생산, 우편 직송(direct mail)을 포함해 그 밖의 모든 경우
UNSPECIFIED사유 미제공

사유는 두 그룹으로 나뉘며, 그 차이가 중요합니다. 주체 기반 사유 — 정부, 자선, 종교, 교육 — 는 구매자가 무엇을 구매하든 상관없이 면제됩니다. 용도 기반 사유, 그중에서도 특히 RESALE은 해당 요건을 충족하는 상품만 적용됩니다. 재판매 증명서는 구매자가 재판매할 재고를 대상으로 하며, 같은 주문에 포함된 사무용 가구까지 대상으로 하지는 않습니다.

사유가 없으면 Zonos는 둘을 구분할 수 없어 주문 전체만 면제할 수 있으며, 이는 재판매 증명서에 대해 가장 방어하기 어려운 방식입니다. 면제 대부분이 재판매라면, RESALE을 기본값으로 보내고 예외를 개별적으로 나열하는 방식이 모든 고객을 일일이 분류하는 것보다 대개 훨씬 수고를 덜어줍니다.

면제 참조 번호 

exemptionReference는 고객의 면제 서류에 인쇄된 번호입니다. 주와 면제 유형에 따라 재판매 또는 판매자 허가 번호, 주 면세 증명서 번호, direct pay permit 번호, 또는 연방 세금 ID일 수 있습니다.

모든 레코드에 필수입니다. 증명서에 표시된 그대로 정확히 저장하고 전송하세요 — 형식은 관할 구역마다 크게 다르며(SR EAA 12-345678, 85-8012345678C-9, 12-3456789), Zonos는 앞뒤 공백을 제거하는 것 외에는 전송된 값을 그대로 보존합니다. 대소문자를 바꾸거나 하이픈과 공백을 제거하지 마세요.

exemptionReference는 연방 세금 ID를 포함할 수 있으므로, 개인정보 보호를 위해 전송은 가능하지만 면제 조회 시 다시 반환되지는 않습니다.

거부된 레코드 

레코드는 한 번에 하나씩 검증됩니다. 거부된 레코드는 rejected에 보고되며 나머지 배치를 실패시키지 않고, 해당 관할 구역에 이미 기록된 면제에도 영향을 주지 않습니다.

Code↕Cause↕
UNKNOWN_CUSTOMERcustomerId와 일치하는 고객이 없습니다. 먼저 고객을 생성하세요
UNKNOWN_JURISDICTIONadministrativeArea가 인식되는 미국 주, 특별구, 또는 준주가 아닙니다
INVALID_DATE_RANGEexpiresAt이 effectiveAt보다 이후가 아닙니다
MISSING_EXEMPTION_REFERENCEexemptionReference가 비어 있습니다
DUPLICATE_JURISDICTION한 payload 내 두 레코드가 국가, 지역, 발효일이 동일합니다. 첫 번째 레코드가 유지됩니다

알 수 없는 고객은 생성되지 않고 거부되므로, 잘못 입력된 customerId는 실제 구매자와 절대 일치하지 않는 프로필을 생성하는 대신 응답에 나타납니다.

미국 관할 구역만 검증됩니다. 다른 국가의 하위 구역은 전송된 그대로 수락됩니다.

조회 및 제거 

동기화가 반영되었는지 확인하려면 고객의 면제를 조회하세요.

1query checkoutCustomerTaxExemptions($customerId: String!) {
2 checkoutCustomerTaxExemptions(customerId: $customerId) {
3 countryCode
4 administrativeArea
5 effectiveAt
6 expiresAt
7 exemptionReason
8 }
9}

고객이 계정을 해지하는 경우처럼 고객의 모든 면제를 제거하려면 checkoutCustomerTaxExemptionsDelete를 사용하세요. 고객에게 면제가 있었는지 여부와 관계없이 SUCCESS를 반환하므로, 여러 번 호출해도 안전합니다.

1mutation checkoutCustomerTaxExemptionsDelete($customerId: String!) {
2 checkoutCustomerTaxExemptionsDelete(customerId: $customerId)
3}
GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

CheckoutCustomerProfileInput CheckoutCustomerTaxExemptionSyncInput

MUTATIONS

checkoutCustomerTaxExemptionsDelete checkoutCustomerTaxExemptionsSync checkoutCustomerUpsert

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

지원 받기·법적 문서·© 2026 Zonos
이 페이지에서:
  • 세금 면제
  • 고객 생성 또는 업데이트
  • 세금 면제 동기화
  • 동기화 동작 방식
  • 면제 사유
  • 면제 참조 번호
  • 거부된 레코드
  • 조회 및 제거