Avalara Sales Tax

Kraal can use Avalara AvaTax to calculate sales tax for ERPNext sales invoices. Each connection is scoped to one Kraal legal entity and one Avalara company.

Kraal shows four separate facts about every connection:

• API environment — Sandbox or Production
• account lifecycle — trial, paid, or not yet verified
• usage mode — development, controlled pilot, or live
• commit policy — whether Avalara commit is disabled or occurs after ERPNext posting

These labels are not interchangeable. In particular, a 90-day trial may authenticate against Avalara's Production API. That does not make it a live account or permit committed client transactions.

The integration is designed to keep the accounting and tax records aligned:

• invoice previews use an uncommitted Avalara estimate
• any material invoice edit invalidates the previous preview
• Kraal recalculates final tax before posting the invoice
• ERPNext receives the exact tax returned by Avalara
• for an approved paid pilot or live connection, Kraal commits only after the ERPNext invoice is submitted
• reconciliation compares both records and surfaces exceptions for review

Trial and development connections work differently: Kraal permits only clearly identified fictional tests, leaves the provider transaction uncommitted, and blocks ordinary client invoices and automated refunds.

Avalara remains the tax-calculation provider. Kraal does not file returns, remit tax, determine where a client must register, or replace advice from the client's tax professional.

Before you start

Confirm that you have:

• selected the correct Kraal client and legal entity
• a healthy ERPNext connection for that entity
• authority to connect the client's Avalara account
• an Avalara account with an active company for the same legal entity
• a reviewed ERPNext sales-tax liability account
• complete customer ship-to addresses
• reviewed Avalara tax codes for pilot items, or an approved default classification policy
• reviewed customer exemption treatment where applicable

Use the API environment assigned to the credentials. Do not infer the endpoint from the words “trial” or “paid.” Kraal verifies the selected endpoint during connection. A Production API badge paired with Trial account, Development use, and Commit disabled is an expected development profile—not permission for live activity.

Protect the client's credentials

Enter the Avalara account ID and license key only in Kraal's Avalara setup screen. The license key is write-only. Kraal clears both fields from the form after submission and does not show the key again.

Never put an Avalara license key, password, token, browser session, or setup link in a support ticket, chat message, shared document, screenshot, or invoice field. Kraal support should never ask you to send one.

If setup is interrupted, use Resume securely in Kraal. This issues fresh one-time setup state after access checks; do not try to preserve setup state in a bookmark or browser note.

Connect Avalara

1. Open the correct entity

1. Select the client and legal entity in Kraal.
2. Open Accounting > Integrations.
3. Select Avalara sales tax.
4. Check the API environment, account lifecycle, usage mode, and commit-policy badges before continuing.

Sandbox and Production are separate API environments. A company in one cannot satisfy setup in the other. The account lifecycle remains a separate fact.

2. Choose an account path

Choose one of the paths shown in Kraal:

• Use existing account — select its API environment and intended account profile, then connect credentials already issued by Avalara.
• Create or connect 90-day trial — complete Avalara's hosted signup, select the API environment assigned to the trial, then return to Kraal. Trial use remains development-only and uncommitted.
• Create Production account — complete customer-owned onboarding with Avalara, then return to Kraal.

Kraal may offer simple company initialization for evaluation in Sandbox. Use Avalara directly for complex company, nexus, registration, exemption, or filing configuration.

3. Verify the connection

Enter the account ID and license key, then select Verify and connect. Kraal authenticates against the selected API environment and confirms company access without returning credentials to the browser.

If the connection fails, confirm the environment and account access. Re-enter the license key in Kraal rather than sending it to another person for troubleshooting.

4. Bind one Avalara company

Select the active Avalara company that represents the Kraal legal entity. Review the company name and code carefully.

Kraal prevents the same Avalara company from being bound to two Kraal entities in the same API environment. If the company is already bound, stop and verify the legal-entity mapping instead of choosing another company as a workaround.

5. Validate the default ship-from address

Enter the entity's normal ship-from address and select Validate ship-from.

If Avalara suggests a corrected address, compare it with the client's source records. Accept the correction only when it is appropriate. Kraal does not mark a browser-entered address as verified until the provider validation succeeds and any correction is explicitly accepted.

6. Save posting policy

Choose the reviewed ERPNext sales-tax liability account and default Avalara tax code. Confirm the default only after reviewing its intended use.

Item-specific tax codes are preferable. A default is a controlled fallback, not a substitute for reviewing products and services that have different tax treatment. A line remains blocked when it has neither a reviewed item mapping nor an approved default, or when its tax evidence needs review.

If prices include tax, review the client workflow carefully. Tax-inclusive credit notes require individual handling in the initial integration.

7. Run the test calculation

Use only the fictional test customer, test items, amount limit, and dedicated test scope shown by Kraal. The setup test creates an uncommitted estimate; it does not post an ERPNext invoice.

Recheck readiness after the test. A development-ready result means uncommitted testing is ready; it does not enable normal invoice posting. Live invoice posting additionally requires a verified paid account and approved pilot or live usage. Selecting “paid” in the browser does not grant that authority; Kraal verifies paid eligibility separately.

Readiness checks

Kraal evaluates the connection for the selected entity. Required checks include:

• provider connection and account access
• authenticated verification of the selected API environment
• a coherent account lifecycle, usage mode, and commit policy
• exact Avalara company binding and active-company status
• ERPNext readiness
• verified default ship-from address
• sales-tax liability account and posting policy
• reviewed item-tax-code coverage or an approved default
• customer and exemption inputs needed for the transaction
• a successful test calculation

A connected badge alone does not mean invoice posting is ready. Resolve every blocking readiness item first, and read the profile labels: development readiness and live readiness authorize different actions.

Use a trial or development connection

A trial is for integration validation. It must not be used with real client customers, items, invoice amounts, or filing activity.

In development mode:

• use only a dedicated Kraal and ERPNext test entity
• use fictional records visibly marked as test data
• stay within the limit displayed by Kraal
• expect every Avalara calculation to remain uncommitted
• do not create normal client invoices, refunds, voids, or adjustments through the integration
• confirm Commit disabled before each test

If the UI shows Production API for the trial, keep following these development restrictions. The endpoint label describes where the credentials authenticate; the other badges describe what Kraal permits.

Create a sales invoice

The normal invoice workflow below applies only to a verified paid connection in an approved pilot or live usage mode. When that connection is ready:

1. Select a customer with a complete destination address.
2. Add invoice lines with item codes, quantities, rates, and income accounts.
3. Review item tax classifications and customer exemption treatment.
4. Select Calculate Avalara tax and wait for the preview to finish.
5. Review the calculated tax, warnings, and environment badge.
6. Submit only when the preview is current and the invoice details are correct.

The preview is not a posted or committed tax record. Changes to the customer, address, date, currency, item, quantity, rate, discount, or tax treatment require you to select Recalculate Avalara tax. Kraal does not automatically create another provider calculation while you edit.

During submission, Kraal obtains a final uncommitted calculation, posts the exact tax to ERPNext, and then commits the matching Avalara transaction. Repeating the same approved request should reuse its operation record rather than create another invoice or tax transaction. Development connections stop before this live workflow and remain uncommitted.

Do not add an ERPNext tax template on top of an Avalara-enabled invoice. Kraal supplies the provider tax directly for the configured entity.

Understand invoice tax status

The invoice detail can show separate ERPNext and Avalara outcomes:

Status	Meaning	Operator action
Preview ready	An uncommitted calculation matches the current draft	Review, then submit if appropriate
Development test complete	A fictional test calculated and remains uncommitted	Record the result; do not treat it as a live invoice
Committed and matched	ERPNext and Avalara agree	No action needed
Commit needs repair	ERPNext posted, but Kraal could not prove the Avalara commit	Do not recreate the invoice; use the surfaced repair action
Reconciliation mismatch	Amount, state, or lineage differs	Review the exception before close
Provider locked	Avalara no longer permits the requested change	Escalate for an authorized accounting decision
Posting blocked	Required tax inputs or readiness controls are incomplete	Correct the blocker and recalculate

An uncertain response is not treated as permission to create a duplicate. Kraal re-reads provider state and retains a durable repair record when the final outcome cannot be proved.

Credit notes and refunds

Create a credit note from the original submitted sales invoice so Kraal can preserve the original Avalara line references. Automated Avalara refunds require a committed and reconciled source transaction; uncommitted development tests are not refundable through this workflow.

For the initial workflow:

• select whole original invoice lines
• do not change the immutable original line reference
• use a full credit or a reviewed subset of original lines
• review tax-inclusive credits individually
• do not create a separate negative sales invoice to imitate a refund

Kraal posts the ERPNext credit note first, then requests the corresponding Avalara refund and retains the linkage for reconciliation. If either side needs repair, use the existing credit note and surfaced repair state rather than creating another one.

Tax-only refunds, adjustments to committed documents, and voids require elevated authority and an evidence-backed reason. A locked or previously reported provider transaction may require a different accounting correction; Kraal should not silently overwrite it.

Reconciliation and close

Kraal compares the submitted ERPNext invoice with its Avalara transaction, including transaction identity, state, amount, tax, and reversal lineage. Scheduled checks can surface:

• missing provider transactions
• duplicate transaction codes
• amount or tax mismatches
• uncommitted or unexpectedly voided records
• incomplete refunds or credits
• operations that need a safe retry or manual review

Unresolved tax exceptions block tax readiness for close only after an authoritative paid pilot or live profile is active. Development trials and incomplete optional setup do not become client close controls. A matched Kraal/Avalara record means the two systems agree; it does not assert that a tax return was filed or tax was remitted.

Disconnect or rotate credentials

Disconnecting stops new Avalara tax execution for the entity and clears stored credential material. Historical invoice evidence remains available for audit and reconciliation.

Disconnecting does not reverse invoices, refunds, or committed Avalara transactions. Kraal blocks disconnect while provider operations still need repair; resolve those items first so their lineage and outcome can be proved.

To replace a license key, use the authorized reconnect or credential-rotation action in Kraal. Enter the replacement only in the protected setup form and run readiness checks again. Do not send the old or new key to support.

Get help safely

When escalating an Avalara issue, include:

• Kraal client and legal-entity names
• the four profile labels shown by Kraal: API environment, account lifecycle, usage mode, and commit policy
• invoice or credit-note number, if applicable
• approximate time of the attempt
• the status and safe error code shown by Kraal
• whether the operation was a preview, submission, commit repair, credit, or reconciliation check

Do not include credentials, tokens, setup links, full customer addresses, taxpayer identifiers, or copied provider request and response bodies.

See Troubleshooting for common recovery steps and Sales & Purchase Invoices for the general invoice workflow.