> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/tax-integrations/taxjar.md). # TaxJar ## Overview The TaxJar integration connects Younium to **TaxJar** for US sales tax **calculation** on draft invoices and **reporting** (order creation) when invoices are posted. Tax is applied only to invoice lines whose tax template detail matches the ship-to address and has **Use TaxJar** enabled. The integration uses a TaxJar API access token (sandbox or production) and optional state-level filtering with per-state financial account overrides. *** ## Authentication You connect TaxJar with an API token, which you generate in TaxJar and paste into the integration settings together with a choice of sandbox or production. Younium checks the token against TaxJar the moment you save. If it works, the connection is marked active. If it does not, the connection stays inactive and the reason TaxJar gave is shown in the settings. The connection lasts until the token is revoked or replaced in TaxJar. Nothing expires on a schedule and there is no periodic reauthorisation. *** ## Sandbox vs. Production You choose sandbox or production when you connect, and the choice decides which TaxJar account Younium calculates and reports against. Each has its own token, so moving from testing to live means reconnecting rather than switching the choice on its own. *** ## Activation Activation is the moment Younium first calls TaxJar with the token you entered; a token is required, and activation fails immediately without one. Activating also creates the charge custom field **TaxJax Product Tax Code**, which carries the TaxJar product tax code for a charge. Activation connects and nothing more — the exchanges the integration runs are turned on separately when you save the settings. *** ## Deactivation Deactivating the integration removes the stored TaxJar settings and stops both exchanges: draft invoices are no longer sent for tax calculation, and posted invoices are no longer reported to TaxJar. Tax amounts already written onto invoices are left as they are. *** ## Save and Setup `SaveAndSetup` persists calculation/reporting flags and state configuration, then: * Subscribes or unsubscribes `InvoiceDraftCreated` → `taxjar-taxcalulations-draft-invoice` when `DoSalesTaxCalculations` is true/false. * Subscribes or unsubscribes `InvoicePosted` → `taxjar-taxreporting-post-invoice` when `DoSalesTaxReporting` is true/false. * Populates account custom field list **`Exemption type`** (see below). * Ensures charge custom field **`TaxJax Product Tax Code`**. ### Settings | Setting | Description | Default | | ------------------------- | ------------------------------------------------------------------------ | -------------------------------------- | | `DoSalesTaxCalculations` | Enable draft invoice tax calculation via TaxJar | Per tenant | | `DoSalesTaxReporting` | Enable posted invoice reporting to TaxJar | Per tenant | | `StatesForTaxCalculation` | Comma-separated state filter; optional `:FinancialAccountCode` per state | Optional — empty means no state filter | | `ProductTaxCode` | Default TaxJar product tax code when charge has none | Per tenant | ### States configuration format `StatesForTaxCalculation` is a comma-separated list of entries like `ca` or `ca:FIN001` (spaces stripped, compared lowercase to `addressTo.State`). If the setting is non-empty and the invoice ship-to state does not match any entry, draft calculation is **skipped** (informational log, no error). When a financial account code suffix is present, tax items on calculated lines use that financial account instead of the template default. *** ## Custom fields created by the integration | Entity | Custom field name (logical) | Type | Notes | | ------- | --------------------------- | ---- | --------------------------------------------------- | | Account | `Exemption type` | List | Do not rename; keys sent as TaxJar `exemption_type` | | Charge | `TaxJax Product Tax Code` | Text | Product tax code per charge; do not rename | Integration-prefixed field names in code use `IntegrationUtils.GetIntegrationCustomFieldName("TaxJar", ...)`. ### Exemption type list (Key → display Value) | Key | Value | | ------------- | ----------- | | `non_exempt` | Non exempt | | `wholesale` | Whole sale | | `government` | Government | | `marketplace` | Marketplace | | `other` | Other | Draft calculation resolves the account’s list **Value** to **Key** for the API. Posted reporting requires the account custom field when `StatesForTaxCalculation` is configured. *** ## Tax line eligibility For each invoice line, Younium resolves `OrderProductCharge.TaxTemplate` to the most specific **TaxTemplateDetail** for the destination address (`DeliveryAddress` if present, else `InvoiceAddress`) and country. A line is processed only when `TaxTemplateDetail.UseTaxJar == true`. If `StatesForTaxCalculation` is set and the address has no **State** while TaxJar calculation applies, draft calculation throws an error. Posted reporting skips the invoice entirely if no line’s template detail has `UseTaxJar` for the destination. *** ## Field mapping ### Ship-to address resolution | Context | Address used | | ----------------- | ----------------------------------------------------- | | Draft calculation | `Invoice.DeliveryAddress` ?? `Invoice.InvoiceAddress` | | Posted reporting | Same | ### Draft tax calculation (`TaxForOrder` — per eligible line) Legal entity address is **from**; invoice destination is **to**. | Younium field | TaxJar parameter | | ------------------------------------------------------------- | ------------------------------- | | `LegalEntity.Address.Country.TwoAlphaCode` | `from_country` | | `LegalEntity.Address.Zip` | `from_zip` | | `LegalEntity.Address.State` | `from_state` | | `LegalEntity.Address.City` | `from_city` | | `LegalEntity.Address.Street` | `from_street` | | `addressTo.Country.TwoAlphaCode` | `to_country` | | `addressTo.Zip` | `to_zip` | | `addressTo.State` | `to_state` | | `addressTo.City` | `to_city` | | `addressTo.Street` | `to_street` | | `InvoiceLine.Subtotal.Amount` | `amount` | | `0` | `shipping` | | Exemption list Key (from account custom field) | `exemption_type` | | `InvoiceLine.Id` | `line_items[].id` | | `1` | `line_items[].quantity` | | Charge `TaxJax Product Tax Code` or `settings.ProductTaxCode` | `line_items[].product_tax_code` | | `InvoiceLine.Subtotal.Amount` | `line_items[].unit_price` | | `"younium"` | `plugin` | **Write-back:** For tax items tied to the line’s tax template, `TaxItem.Amount.Amount` is set to `rates.AmountToCollect` (TaxJar response). Line `Tax`, `Total`, and invoice totals are recalculated and saved. Required legal entity address fields (when calculating): country two-alpha code, zip, state, city, street — missing values throw `ApiException`. ### Posted tax reporting (`CreateOrder` / `CreateRefund`) Header fields for the main order (debit lines only on mixed invoices): | Younium field | TaxJar field | | ------------------------------------------------ | -------------------------------------------------------------------- | | `Invoice.InvoiceNumber` | `transaction_id` | | `Invoice.Posted` | `transaction_date` | | Legal entity address | `from_country`, `from_zip`, `from_state`, `from_city`, `from_street` | | Destination address | `to_country`, `to_zip`, `to_state`, `to_city`, `to_street` | | `Invoice.Subtotal.Amount - creditSubtotalAmount` | `amount` | | `0` | `shipping` | | `Invoice.Tax.Amount - creditTaxAmount` | `sales_tax` | | `"younium"` | `plugin` | | Exemption key (when states configured) | `exemption_type` | **Line items** (debit lines: `Subtotal.Amount >= 0`): | Younium field | TaxJar line item field | | -------------------------------------------- | ---------------------- | | `1` | `quantity` | | `InvoiceLine.Subtotal.Amount` | `unit_price` | | Charge tax code or `settings.ProductTaxCode` | `product_tax_code` | | `InvoiceLine.Tax.Amount` | `sales_tax` | | `InvoiceLine.ChargeDescription` | `description` | **Credit lines on debit invoice** (`Subtotal.Amount < 0`): reported separately via `CreateRefund` with `transaction_id` = `{InvoiceNumber}_creditLines`, `transaction_reference_id` = `InvoiceNumber`, and credit line items (same field mapping). TaxJar does not accept mixed debit/credit lines on one order. **Credit invoice** (a negative invoice total): credit and debit amounts are separated and reported to TaxJar the same way as on a debit invoice. > **Note on posting:** Posting an invoice reports it to TaxJar but does not recalculate its tax. Tax is calculated on the draft invoice, so the amounts on a posted invoice are the ones calculated before posting. *** ## Workflows ### Draft invoice tax calculation | Item | Value | | ------------- | ------------------------------------------------------------------ | | Runs when | A draft invoice is created in Younium | | Preconditions | Valid settings; optional state match | | Outcome | Tax amounts updated on eligible lines; invoice totals recalculated | ### Posted invoice tax reporting | Item | Value | | ------------- | ------------------------------------------------------------------------------------------------------------------ | | Runs when | An invoice is posted in Younium | | Preconditions | Valid settings; at least one TaxJar-eligible line; destination country required | | Outcome | The invoice is reported to TaxJar as an order, with a refund also reported for any credit lines on a debit invoice | Reporting does **not** write tax back to Younium — it sends transactions already reflected on the posted invoice. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.younium.com/tax-integrations/taxjar.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.