DOCS
Checkout•
Strona głównaGlobalny handel elektroniczny Zonos Checkout Profile klientów Zwolnienia podatkowe

Zwolnienia podatkowe

Synchronizuj certyfikaty zwolnienia z podatku od sprzedaży w USA z profilem klienta.

Jeśli sprzedajesz odsprzedawcom, agencjom rządowym lub organizacjom non-profit, ci kupujący posiadają certyfikaty zwolnienia, które zwalniają ich z podatku od sprzedaży w określonych stanach. Zonos przechowuje te certyfikaty w profilu klienta, dzięki czemu zwolniony kupujący może zostać rozpoznany podczas realizacji zakupu.

Zwolnienia są rejestrowane według jurysdykcji. Klient zwolniony z podatku w Karolinie Południowej nie jest automatycznie zwolniony w Teksasie, więc każdy stan, dla którego klient posiada certyfikat, stanowi osobny rekord z własnymi datami i numerem certyfikatu.

Zwolnienia są przypisywane do istniejącego klienta, więc synchronizacja to dwa wywołania: utworzenie klienta, a następnie synchronizacja jego certyfikatów. Oba są indeksowane na podstawie Twojego własnego identyfikatora klienta — tego samego customerId, którego używasz w innych miejscach w Checkout. Zonos nigdy nie wymaga przechowywania wewnętrznego identyfikatora.

Ta funkcja jest dostępna wyłącznie dla niestandardowych integracji API.

Zwolnienia nie są jeszcze stosowane do wycen kosztu dostarczenia

Możesz już dziś synchronizować i zarządzać zwolnieniami, a rekordy są przechowywane w profilu klienta. Odliczanie zwolnienia od podatku w koszcie dostarczenia pojawi się wkrótce, więc zsynchronizowane zwolnienie nie zmienia jeszcze podatku podawanego kupującemu w wycenie. Synchronizowanie już teraz oznacza, że Twoje certyfikaty będą gotowe, gdy ta funkcja zostanie wprowadzona.

Utwórz lub zaktualizuj klienta 

checkoutCustomerUpsert tworzy profil klienta lub aktualizuje go, jeśli już istnieje dla danego customerId. W przeciwieństwie do checkoutCustomerProfileAuthenticate, nie wymaga to obecności kupującego, więc możesz przygotować listę klientów z wyprzedzeniem. Pełny opis działania pól znajdziesz w sekcji utwórz lub zaktualizuj profil bez kupującego.

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

Ponieważ dopasowanie odbywa się na podstawie customerId, wielokrotne wywołanie aktualizuje ten sam profil zamiast tworzyć duplikaty. Można je bezpiecznie uruchamiać dla całej listy klientów przy każdej synchronizacji.

Synchronizuj zwolnienia podatkowe 

checkoutCustomerTaxExemptionsSync przyjmuje wielu klientów jednocześnie. Każdy wpis zastępuje pełny zestaw zwolnień danego klienta.

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}

Pominięcie expiresAt oznacza, że certyfikat nie wygasa. Pominięcie exemptionReason przyjmuje domyślnie wartość UNSPECIFIED.

Jak działa synchronizacja 

Każdą synchronizację regulują trzy zasady.

Lista jest wiążąca. taxExemptions to pełny zestaw zwolnień klienta, a nie lista zmian. Każde zwolnienie już zarejestrowane, którego brakuje na liście, zostaje usunięte — w ten sposób wycofany certyfikat przestaje być honorowany. Wysłanie niepełnej listy po cichu usuwa wszystko, czego na niej nie ma.

Każdy rekord jest zwolnieniem. Nie ma sposobu, aby zarejestrować, że klient nie jest zwolniony gdziekolwiek — zobacz uwagę poniżej.

Usunięcie wszystkich zwolnień to pusta lista. Aby usunąć certyfikaty klienta, wyślij je z wartością "taxExemptions": []. Pominięcie klienta w całym ładunku pozostawia jego istniejące rekordy nienaruszone.

Wysyłaj wyłącznie jurysdykcje, w których klient jest zwolniony

Zonos nie ma rekordu „brak zwolnienia” — dana jurysdykcja albo znajduje się na liście, albo nie. Jeśli Twój system przechowuje razem jurysdykcje zwolnione i niezwolnione, przefiltruj listę do tych zwolnionych przed synchronizacją. Rekord bez zwolnienia jest nieodróżnialny od prawdziwego certyfikatu, więc zostanie zaakceptowany zamiast odrzucony, a klient zostanie potraktowany jako zwolniony w tym stanie.

Powody zwolnienia 

exemptionReason opisuje, dlaczego klient jest zwolniony. Pole to jest opcjonalne i domyślnie przyjmuje wartość UNSPECIFIED, ale warto je podać — zobacz poniżej.

Wartość↕Dotyczy↕
RESALETowarów kupowanych w celu odsprzedaży, a nie konsumpcji
FEDERAL_GOVERNMENTFederalnej agencji lub departamentu USA
STATE_LOCAL_GOVERNMENTAgencji stanowej, hrabstwa, gminy lub okręgu szkolnego
TRIBAL_GOVERNMENTPlemienia uznanego federalnie lub jego członka
CHARITABLEOrganizacji charytatywnej non-profit
RELIGIOUS_ORGANIZATIONKościoła lub innej organizacji religijnej
EDUCATIONAL_ORGANIZATIONSzkoły lub uniwersytetu
DIRECT_PAYKupującego posiadającego zezwolenie na bezpośrednią płatność, który samodzielnie odprowadza podatek
OTHERWszystkiego innego, w tym zagranicznych dyplomatów, produkcji rolnej, produkcji przemysłowej i przesyłek reklamowych
UNSPECIFIEDBrak podanego powodu

Powody dzielą się na dwie grupy, a różnica ma znaczenie. Powody oparte na podmiocie — rządowy, charytatywny, religijny, edukacyjny — zwalniają kupującego niezależnie od tego, co kupuje. Powody oparte na zastosowaniu, przede wszystkim RESALE, obejmują wyłącznie towary kwalifikujące się: certyfikat odsprzedaży obejmuje towary, które kupujący odsprzeda, a nie meble biurowe z tego samego zamówienia.

Bez podanego powodu Zonos nie może rozróżnić tych dwóch przypadków i może zwolnić wyłącznie całe zamówienia, co jest najtrudniejsze do obronienia w przypadku certyfikatów odsprzedaży. Jeśli większość Twoich zwolnień dotyczy odsprzedaży, wysyłanie RESALE jako wartości domyślnej z indywidualnie wymienionymi wyjątkami zwykle wymaga znacznie mniej pracy niż klasyfikowanie każdego klienta.

Numer referencyjny zwolnienia 

exemptionReference to numer wydrukowany na dokumentach zwolnienia klienta. W zależności od stanu i rodzaju zwolnienia może to być numer zezwolenia na odsprzedaż lub zezwolenia sprzedawcy, numer stanowego certyfikatu zwolnienia, numer zezwolenia na bezpośrednią płatność lub federalny numer identyfikacji podatkowej.

Jest on wymagany w każdym rekordzie. Zapisuj i wysyłaj go dokładnie tak, jak widnieje na certyfikacie — formaty znacznie różnią się w zależności od jurysdykcji (SR EAA 12-345678, 85-8012345678C-9, 12-3456789), a Zonos zachowuje wartość w przesłanej postaci, jedynie usuwając otaczające białe znaki. Nie zmieniaj wielkości liter ani nie usuwaj myślników i spacji.

Ze względu na ochronę prywatności exemptionReference można wysłać, ale nie jest on zwracany podczas odczytu zwolnień, ponieważ może zawierać federalny numer identyfikacji podatkowej.

Odrzucone rekordy 

Rekordy są walidowane pojedynczo. Odrzucony rekord jest zgłaszany w rejected i nie powoduje niepowodzenia pozostałej części paczki, ani nie narusza zwolnienia już zarejestrowanego dla danej jurysdykcji.

Kod↕Przyczyna↕
UNKNOWN_CUSTOMERŻaden klient nie odpowiada customerId. Najpierw utwórz klienta
UNKNOWN_JURISDICTIONadministrativeArea nie jest rozpoznawanym stanem, dystryktem ani terytorium USA
INVALID_DATE_RANGEexpiresAt nie przypada po dacie effectiveAt
MISSING_EXEMPTION_REFERENCEexemptionReference jest puste
DUPLICATE_JURISDICTIONDwa rekordy w jednym ładunku mają ten sam kraj, obszar i datę wejścia w życie. Zachowywany jest pierwszy z nich

Nieznani klienci są odrzucani, a nie tworzeni, więc błędnie wpisany customerId ujawnia się w odpowiedzi zamiast tworzyć profil, który nigdy nie będzie pasował do prawdziwego kupującego.

Walidowane są wyłącznie amerykańskie obszary administracyjne. Jednostki podziału administracyjnego innych krajów są akceptowane w przesłanej postaci.

Odczyt i usuwanie 

Odczytaj zwolnienia klienta, aby potwierdzić, że synchronizacja się powiodła:

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

Aby usunąć wszystkie zwolnienia klienta — na przykład gdy zamyka on swoje konto — użyj checkoutCustomerTaxExemptionsDelete. Zwraca ono SUCCESS niezależnie od tego, czy klient miał jakiekolwiek zwolnienia, więc można je bezpiecznie wywołać więcej niż raz.

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

Czy ta strona była pomocna?

Uzyskaj wsparcie·Dokumenty prawne·© 2026 Zonos
Na tej stronie:
  • Zwolnienia podatkowe
  • Utwórz lub zaktualizuj klienta
  • Synchronizuj zwolnienia podatkowe
  • Jak działa synchronizacja
  • Powody zwolnienia
  • Numer referencyjny zwolnienia
  • Odrzucone rekordy
  • Odczyt i usuwanie