Impostos

A API de impostos gerencia as configurações de imposto da loja, incluindo alíquotas, isenções e as regras para diferentes regiões e tipos de produto. Uma regra de imposto diz quanto de imposto se aplica, onde ele se aplica (país, estado, CEPs) e qual tipo de endereço decide a regra.

Você usa estas rotas para carregar as regras de imposto de uma loja nova, para ajustar uma alíquota quando as regras mudam ou para ler as regras que estão valendo hoje. Elas ficam em $BASE_URL/api/taxes, exigem uma conta de administrador e usam credenciais HTTP Basic ($EMAIL:$API_KEY).

Como funciona

Uma regra de imposto é criada uma vez e depois consultada e ajustada ao longo do tempo. Em vez de excluir uma regra que você quer pausar, atualize o status dela para D.

Códigos de status do imposto

Códigos de tipo de alíquota

Códigos de tipo de endereço

Conceitos principais

As alíquotas são enviadas e devolvidas como texto ("7.25"), e identificadores como tax_id também voltam como texto. O indicador price_includes_tax informa se o imposto já está dentro do preço do produto (Y) ou se é somado a ele (N).

Endpoints

Listar regras de imposto

Esta rota aceita paginação e filtros.

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/taxes?country_code=US&state_code=CA"

{
  "taxes": [
    {
      "tax_id": "12",
      "tax_name": "Sales Tax - California",
      "rate_type": "P",
      "rate_value": "7.25",
      "country_code": "US",
      "state_code": "CA",
      "status": "A"
    },
    {
      "tax_id": "13",
      "tax_name": "GST - Canada",
      "rate_type": "P",
      "rate_value": "5.00",
      "country_code": "CA",
      "state_code": "",
      "status": "A"
    }
  ],
  "params": {
    "page": 1,
    "items_per_page": 10,
    "total_items": 2
  }
}

Consultar uma regra de imposto

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/taxes/12"

{
  "tax_id": "12",
  "tax_name": "Sales Tax - California",
  "description": "California state sales tax",
  "rate_type": "P",
  "rate_value": "7.25",
  "priority": "0",
  "country_code": "US",
  "state_code": "CA",
  "zip_codes": "",
  "address_type": "S",
  "product_categories": [],
  "tax_exemptions": [],
  "price_includes_tax": "N",
  "status": "A"
}

Criar uma regra de imposto

O exemplo de requisição também envia description, zip_codes, price_includes_tax e status, que são campos do imposto (veja Campos).

curl -X POST -u "$EMAIL:$API_KEY" "$BASE_URL/api/taxes" \
  -H "Content-Type: application/json" \
  -d '{
  "tax_name": "New York City Tax",
  "description": "NYC local sales tax",
  "rate_type": "P",
  "rate_value": "4.5",
  "country_code": "US",
  "state_code": "NY",
  "zip_codes": "10001,10002,10003,10004,10005,10006,10007",
  "address_type": "S",
  "price_includes_tax": "N",
  "status": "A"
}'

Atualizar uma regra de imposto

Envie somente os campos que você quer alterar.

curl -X PUT -u "$EMAIL:$API_KEY" "$BASE_URL/api/taxes/12" \
  -H "Content-Type: application/json" \
  -d '{
  "rate_value": "8.25",
  "description": "Updated California state sales tax",
  "status": "A"
}'

Excluir uma regra de imposto

curl -X DELETE -u "$EMAIL:$API_KEY" "$BASE_URL/api/taxes/12"

Erros comuns

• Excluir uma regra de imposto para pausá-la. A exclusão é permanente, defina status como D.
• Enviar rate_type como uma palavra. Ele é uma única letra, P ou F.
• Esquecer country_code ao criar uma regra: ele é obrigatório, junto com tax_name, rate_type e rate_value.
• Procurar as regras no nível principal da resposta da listagem. No exemplo, elas vêm dentro de taxes, ao lado de um objeto params com os dados de paginação.

Próximos passos