Sincronize certificados de isenção de imposto sobre vendas dos EUA com um perfil de cliente.
Se você vende para revendedores, órgãos públicos ou organizações sem fins lucrativos, esses compradores possuem certificados de isenção que os isentam do imposto sobre vendas em estados específicos. A Zonos armazena esses certificados junto a um perfil de cliente para que um comprador isento possa ser reconhecido no checkout.
As isenções são registradas por jurisdição. Um cliente isento na Carolina do Sul não é automaticamente isento no Texas, portanto cada estado para o qual o cliente possui um certificado é um registro separado, com suas próprias datas e número de certificado.
As isenções são vinculadas a um cliente já existente, então a sincronização acontece em duas chamadas: criar o cliente e, em seguida, sincronizar seus certificados. Ambas são identificadas pelo seu próprio ID de cliente — o mesmo customerId que você usa em outras partes do Checkout. A Zonos nunca exige que você armazene um ID interno.
As isenções ainda não são aplicadas às cotações de landed cost
Você já pode sincronizar e gerenciar isenções hoje, e os registros ficam armazenados no perfil do
cliente. A dedução de uma isenção do imposto em um landed cost está por vir, então uma isenção
sincronizada ainda não altera o imposto cotado a um comprador. Sincronizar agora significa que
seus certificados já estarão prontos quando isso acontecer.
checkoutCustomerUpsert cria um perfil de cliente, ou o atualiza se já existir um para aquele customerId. Ao contrário de checkoutCustomerProfileAuthenticate, isso não exige que o comprador esteja presente, então você pode provisionar sua lista de clientes com antecedência. Consulte criar ou atualizar um perfil sem um comprador para o comportamento completo dos campos.
Como isso corresponde pelo customerId, chamar essa mutação repetidamente atualiza o mesmo perfil em vez de criar duplicatas. É seguro executar isso em toda a sua lista de clientes a cada sincronização.
A lista é a fonte da verdade.taxExemptions é o conjunto completo de isenções do cliente, não uma lista de alterações. Qualquer isenção já registrada que esteja ausente da lista é removida — é assim que um certificado retirado deixa de ser honrado. Enviar uma lista parcial remove silenciosamente tudo o que ficou de fora.
Todo registro é uma isenção. Não há como registrar que um cliente não é isento em algum lugar — veja a observação abaixo.
Remover todas as isenções é uma lista vazia. Para limpar os certificados de um cliente, envie-os com "taxExemptions": []. Deixar o cliente de fora do payload por completo mantém seus registros existentes inalterados.
Envie apenas as jurisdições em que o cliente é isento
A Zonos não possui um registro de "não isento" — uma jurisdição está na lista ou não está. Se o seu
sistema armazena jurisdições isentas e não isentas juntas, filtre apenas as isentas antes de
sincronizar. Um registro não isento é indistinguível de um certificado real, portanto é aceito em
vez de rejeitado, e o cliente será tratado como isento naquele estado.
exemptionReason descreve por que o cliente é isento. É opcional e assume UNSPECIFIED por padrão, mas vale a pena informá-lo — veja abaixo.
Valor↕
Aplica-se a↕
RESALE
Mercadorias compradas para revenda, não para consumo
FEDERAL_GOVERNMENT
Uma agência ou departamento federal dos EUA
STATE_LOCAL_GOVERNMENT
Um órgão estadual, condado, município ou distrito escolar
TRIBAL_GOVERNMENT
Uma tribo reconhecida federalmente ou membro de uma tribo
CHARITABLE
Uma organização beneficente sem fins lucrativos
RELIGIOUS_ORGANIZATION
Uma igreja ou outra organização religiosa
EDUCATIONAL_ORGANIZATION
Uma escola ou universidade
DIRECT_PAY
Um comprador que possui uma licença de pagamento direto e remete o imposto por conta própria
OTHER
Qualquer outro caso, incluindo diplomata estrangeiro, produção agrícola, produção industrial e mala direta
UNSPECIFIED
Nenhum motivo informado
Os motivos se dividem em dois grupos, e a diferença importa. Motivos baseados na entidade — governo, beneficência, religião, educação — isentam o comprador independentemente do que ele compra. Motivos baseados no uso, RESALE acima de todos, cobrem apenas as mercadorias qualificadas: um certificado de revenda cobre o estoque que o comprador vai revender, não os móveis de escritório no mesmo pedido.
Sem um motivo, a Zonos não consegue diferenciar os dois casos e só pode isentar pedidos inteiros, o que é mais difícil de justificar para certificados de revenda. Se a maioria das suas isenções for de revenda, enviar RESALE como padrão com exceções listadas individualmente costuma dar muito menos trabalho do que classificar cada cliente.
exemptionReference é o número impresso na documentação de isenção do cliente. Dependendo do estado e do tipo de isenção, pode ser um número de licença de revenda ou de vendedor, um número de certificado de isenção estadual, um número de licença de pagamento direto ou um ID fiscal federal.
Ele é obrigatório em todo registro. Armazene e envie exatamente como aparece no certificado — os formatos variam muito por jurisdição (SR EAA 12-345678, 85-8012345678C-9, 12-3456789), e a Zonos preserva o valor enviado, exceto pela remoção de espaços em branco nas extremidades. Não altere a capitalização nem remova hifens ou espaços.
Por privacidade, exemptionReference pode ser enviado, mas não é retornado ao ler as isenções de
volta, já que pode conter um ID fiscal federal.
Os registros são validados um de cada vez. Um registro rejeitado é reportado em rejected e não reprova o restante do lote, nem altera a isenção já registrada para aquela jurisdição.
Código↕
Causa↕
UNKNOWN_CUSTOMER
Nenhum cliente corresponde ao customerId. Crie o cliente primeiro
UNKNOWN_JURISDICTION
administrativeArea não é um estado, distrito ou território dos EUA reconhecido
INVALID_DATE_RANGE
expiresAt não é posterior a effectiveAt
MISSING_EXEMPTION_REFERENCE
exemptionReference está vazio
DUPLICATE_JURISDICTION
Dois registros em um mesmo payload compartilham país, região e data de vigência. O primeiro é mantido
Clientes desconhecidos são rejeitados em vez de criados, então um customerId digitado incorretamente aparece na resposta em vez de criar um perfil que nunca corresponderá a um comprador real.
Apenas regiões administrativas dos EUA são validadas. Subdivisões de outros países são aceitas como enviadas.
Para remover todas as isenções de um cliente — quando ele encerra a conta, por exemplo — use checkoutCustomerTaxExemptionsDelete. Ela retorna SUCCESS independentemente de o cliente ter ou não alguma isenção, portanto é seguro chamá-la mais de uma vez.
Isenções fiscais
Isenções fiscais
Sincronize certificados de isenção de imposto sobre vendas dos EUA com um perfil de cliente.
Se você vende para revendedores, órgãos públicos ou organizações sem fins lucrativos, esses compradores possuem certificados de isenção que os isentam do imposto sobre vendas em estados específicos. A Zonos armazena esses certificados junto a um perfil de cliente para que um comprador isento possa ser reconhecido no checkout.
As isenções são registradas por jurisdição. Um cliente isento na Carolina do Sul não é automaticamente isento no Texas, portanto cada estado para o qual o cliente possui um certificado é um registro separado, com suas próprias datas e número de certificado.
As isenções são vinculadas a um cliente já existente, então a sincronização acontece em duas chamadas: criar o cliente e, em seguida, sincronizar seus certificados. Ambas são identificadas pelo seu próprio ID de cliente — o mesmo
customerIdque você usa em outras partes do Checkout. A Zonos nunca exige que você armazene um ID interno.Esse recurso está disponível apenas para integrações personalizadas da API.
Você já pode sincronizar e gerenciar isenções hoje, e os registros ficam armazenados no perfil do cliente. A dedução de uma isenção do imposto em um landed cost está por vir, então uma isenção sincronizada ainda não altera o imposto cotado a um comprador. Sincronizar agora significa que seus certificados já estarão prontos quando isso acontecer.
Criar ou atualizar o cliente
checkoutCustomerUpsertcria um perfil de cliente, ou o atualiza se já existir um para aquelecustomerId. Ao contrário decheckoutCustomerProfileAuthenticate, isso não exige que o comprador esteja presente, então você pode provisionar sua lista de clientes com antecedência. Consulte criar ou atualizar um perfil sem um comprador para o comportamento completo dos campos.mutation checkoutCustomerUpsert($input: CheckoutCustomerProfileInput!) {checkoutCustomerUpsert(input: $input) {customerIdemailnamephone}}Como isso corresponde pelo
customerId, chamar essa mutação repetidamente atualiza o mesmo perfil em vez de criar duplicatas. É seguro executar isso em toda a sua lista de clientes a cada sincronização.Sincronizar isenções fiscais
checkoutCustomerTaxExemptionsSyncaceita vários clientes ao mesmo tempo. Cada entrada substitui o conjunto completo de isenções daquele cliente.mutation checkoutCustomerTaxExemptionsSync($input: [CheckoutCustomerTaxExemptionSyncInput!]!) {checkoutCustomerTaxExemptionsSync(input: $input) {customerIdaccepted {idcountryCodeadministrativeAreaeffectiveAtexpiresAtexemptionReason}rejected {codemessageadministrativeAreaeffectiveAt}}}Um
expiresAtomitido significa que o certificado não expira. UmexemptionReasonomitido é definido comoUNSPECIFIEDpor padrão.Como funciona a sincronização
Três regras regem toda sincronização.
A lista é a fonte da verdade.
taxExemptionsé o conjunto completo de isenções do cliente, não uma lista de alterações. Qualquer isenção já registrada que esteja ausente da lista é removida — é assim que um certificado retirado deixa de ser honrado. Enviar uma lista parcial remove silenciosamente tudo o que ficou de fora.Todo registro é uma isenção. Não há como registrar que um cliente não é isento em algum lugar — veja a observação abaixo.
Remover todas as isenções é uma lista vazia. Para limpar os certificados de um cliente, envie-os com
"taxExemptions": []. Deixar o cliente de fora do payload por completo mantém seus registros existentes inalterados.A Zonos não possui um registro de "não isento" — uma jurisdição está na lista ou não está. Se o seu sistema armazena jurisdições isentas e não isentas juntas, filtre apenas as isentas antes de sincronizar. Um registro não isento é indistinguível de um certificado real, portanto é aceito em vez de rejeitado, e o cliente será tratado como isento naquele estado.
Motivos de isenção
exemptionReasondescreve por que o cliente é isento. É opcional e assumeUNSPECIFIEDpor padrão, mas vale a pena informá-lo — veja abaixo.RESALEFEDERAL_GOVERNMENTSTATE_LOCAL_GOVERNMENTTRIBAL_GOVERNMENTCHARITABLERELIGIOUS_ORGANIZATIONEDUCATIONAL_ORGANIZATIONDIRECT_PAYOTHERUNSPECIFIEDOs motivos se dividem em dois grupos, e a diferença importa. Motivos baseados na entidade — governo, beneficência, religião, educação — isentam o comprador independentemente do que ele compra. Motivos baseados no uso,
RESALEacima de todos, cobrem apenas as mercadorias qualificadas: um certificado de revenda cobre o estoque que o comprador vai revender, não os móveis de escritório no mesmo pedido.Sem um motivo, a Zonos não consegue diferenciar os dois casos e só pode isentar pedidos inteiros, o que é mais difícil de justificar para certificados de revenda. Se a maioria das suas isenções for de revenda, enviar
RESALEcomo padrão com exceções listadas individualmente costuma dar muito menos trabalho do que classificar cada cliente.Referência da isenção
exemptionReferenceé o número impresso na documentação de isenção do cliente. Dependendo do estado e do tipo de isenção, pode ser um número de licença de revenda ou de vendedor, um número de certificado de isenção estadual, um número de licença de pagamento direto ou um ID fiscal federal.Ele é obrigatório em todo registro. Armazene e envie exatamente como aparece no certificado — os formatos variam muito por jurisdição (
SR EAA 12-345678,85-8012345678C-9,12-3456789), e a Zonos preserva o valor enviado, exceto pela remoção de espaços em branco nas extremidades. Não altere a capitalização nem remova hifens ou espaços.Por privacidade,
exemptionReferencepode ser enviado, mas não é retornado ao ler as isenções de volta, já que pode conter um ID fiscal federal.Registros rejeitados
Os registros são validados um de cada vez. Um registro rejeitado é reportado em
rejectede não reprova o restante do lote, nem altera a isenção já registrada para aquela jurisdição.UNKNOWN_CUSTOMERcustomerId. Crie o cliente primeiroUNKNOWN_JURISDICTIONadministrativeAreanão é um estado, distrito ou território dos EUA reconhecidoINVALID_DATE_RANGEexpiresAtnão é posterior aeffectiveAtMISSING_EXEMPTION_REFERENCEexemptionReferenceestá vazioDUPLICATE_JURISDICTIONClientes desconhecidos são rejeitados em vez de criados, então um
customerIddigitado incorretamente aparece na resposta em vez de criar um perfil que nunca corresponderá a um comprador real.Apenas regiões administrativas dos EUA são validadas. Subdivisões de outros países são aceitas como enviadas.
Ler de volta e remover
Leia as isenções de um cliente para confirmar que uma sincronização foi aplicada:
query checkoutCustomerTaxExemptions($customerId: String!) {checkoutCustomerTaxExemptions(customerId: $customerId) {countryCodeadministrativeAreaeffectiveAtexpiresAtexemptionReason}}Para remover todas as isenções de um cliente — quando ele encerra a conta, por exemplo — use
checkoutCustomerTaxExemptionsDelete. Ela retornaSUCCESSindependentemente de o cliente ter ou não alguma isenção, portanto é seguro chamá-la mais de uma vez.mutation checkoutCustomerTaxExemptionsDelete($customerId: String!) {checkoutCustomerTaxExemptionsDelete(customerId: $customerId)}CheckoutCustomerProfileInput CheckoutCustomerTaxExemptionSyncInput
checkoutCustomerTaxExemptionsDelete checkoutCustomerTaxExemptionsSync checkoutCustomerUpsert
Esta página foi útil?