Esenzioni fiscali

Se vendi a rivenditori, enti governativi o organizzazioni no profit, questi acquirenti possiedono certificati di esenzione che li esentano dall'imposta sulle vendite in stati specifici. Zonos archivia questi certificati in relazione a un profilo cliente in modo che un acquirente esente possa essere riconosciuto al momento del checkout.

Le esenzioni vengono registrate per giurisdizione. Un cliente esente in South Carolina non è automaticamente esente in Texas, quindi ogni stato per cui il cliente possiede un certificato costituisce un record separato con proprie date e numero di certificato.

Le esenzioni si applicano a un cliente esistente, quindi la sincronizzazione richiede due chiamate: creare il cliente, poi sincronizzare i suoi certificati. Entrambe utilizzano come chiave il tuo stesso ID cliente — lo stesso customerId che usi altrove in Checkout. Zonos non richiede mai di archiviare un ID interno.

Questa funzionalità è disponibile solo per le integrazioni API personalizzate.

Creare o aggiornare il cliente 

checkoutCustomerUpsert crea un profilo cliente, oppure lo aggiorna se ne esiste già uno per quel customerId. A differenza di checkoutCustomerProfileAuthenticate, questa mutazione non richiede la presenza dell'acquirente, quindi puoi predisporre in anticipo l'elenco dei tuoi clienti. Consulta creare o aggiornare un profilo senza un acquirente per il comportamento completo dei campi.

Poiché la corrispondenza avviene su customerId, chiamarla ripetutamente aggiorna lo stesso profilo invece di creare duplicati. È sicuro eseguirla su tutto il tuo elenco clienti a ogni sincronizzazione.

Sincronizzare le esenzioni fiscali 

checkoutCustomerTaxExemptionsSync accetta più clienti alla volta. Ogni voce sostituisce l'intero insieme di esenzioni di quel cliente.

Un expiresAt omesso indica che il certificato non ha scadenza. Un exemptionReason omesso ha come valore predefinito UNSPECIFIED.

Come funziona la sincronizzazione 

Tre regole governano ogni sincronizzazione.

L'elenco è autoritativo. taxExemptions rappresenta l'insieme completo delle esenzioni del cliente, non un elenco di modifiche. Qualsiasi esenzione già registrata ma assente dall'elenco viene rimossa — è così che un certificato revocato smette di essere applicato. L'invio di un elenco parziale rimuove silenziosamente tutto ciò che ne è escluso.

Ogni record è un'esenzione. Non esiste un modo per registrare che un cliente non è esente in un determinato luogo — vedi la nota qui sotto.

Rimuovere tutte le esenzioni equivale a un elenco vuoto. Per cancellare i certificati di un cliente, inviali con "taxExemptions": []. Omettere completamente il cliente dal payload lascia invariati i suoi record esistenti.

Motivi di esenzione 

exemptionReason descrive il motivo per cui il cliente è esente. È facoltativo e ha come valore predefinito UNSPECIFIED, ma specificarlo vale lo sforzo — vedi sotto.

I motivi si dividono in due gruppi, e la differenza è rilevante. I motivi basati sull'entità — governativo, benefico, religioso, educativo — esentano l'acquirente indipendentemente da ciò che acquista. I motivi basati sull'uso, in primis RESALE, coprono solo i beni idonei: un certificato di rivendita copre l'inventario che l'acquirente rivenderà, non i mobili da ufficio nello stesso ordine.

Senza un motivo, Zonos non può distinguere i due casi e può solo esentare interi ordini, il che è più difficile da giustificare per i certificati di rivendita. Se la maggior parte delle tue esenzioni riguarda la rivendita, inviare RESALE come valore predefinito con le eccezioni elencate singolarmente comporta di solito molto meno lavoro rispetto a classificare ogni cliente.

Riferimento dell'esenzione 

exemptionReference è il numero stampato sulla documentazione di esenzione del cliente. A seconda dello stato e del tipo di esenzione, può trattarsi di un numero di permesso di rivendita o di venditore, di un numero di certificato di esenzione statale, di un numero di permesso di pagamento diretto o di un codice fiscale federale.

È obbligatorio per ogni record. Archivialo e invialo esattamente come appare sul certificato — i formati variano notevolmente a seconda della giurisdizione (SR EAA 12-345678, 85-8012345678C-9, 12-3456789), e Zonos conserva il valore così come inviato, salvo la rimozione degli spazi bianchi circostanti. Non modificare la capitalizzazione né rimuovere trattini e spazi.

Record rifiutati 

I record vengono convalidati singolarmente. Un record rifiutato viene segnalato in rejected e non fa fallire il resto del batch, né altera l'esenzione già registrata per quella giurisdizione.

I clienti sconosciuti vengono rifiutati anziché creati, così un customerId digitato in modo errato emerge nella risposta invece di creare un profilo che non corrisponderà mai a un acquirente reale.

Vengono convalidate solo le aree amministrative statunitensi. Le suddivisioni di altri paesi vengono accettate così come inviate.

Rilettura e rimozione 

Leggi le esenzioni di un cliente per confermare che una sincronizzazione sia andata a buon fine:

Per rimuovere ogni esenzione di un cliente — ad esempio quando chiude il proprio account — usa checkoutCustomerTaxExemptionsDelete. Restituisce SUCCESS indipendentemente dal fatto che il cliente avesse o meno esenzioni, quindi è sicuro chiamarla più di una volta.