US VAT & TaxJar setup (Coming Soon)

Coming soon – This feature is rolling out in the next UniBee release. The APIs and UI entries below are final, but production tenants won’t see them until the official launch announcement.

​

Overview

• Connect a TaxJar account via API key and set it as the default US VAT gateway.
• Define global defaults (tax code, origin/destination addresses, nexus addresses, upload/validation toggles).
• Override tax settings per product or plan with the same usVATConfig schema.
• Enforce US-only sales, address validation, and automatic TaxJar filings.
• Use either the Admin Portal import forms or the APIs listed below.

​

1. Initialize the TaxJar gateway

Prerequisite: TaxJar API key with the “Transactions” scope enabled (for tax calculation and order uploads).

​

Admin Portal steps

1. Go to Settings → VAT & Tax → US VAT gateways.
2. Click Add gateway and pick TaxJar.
3. Paste your API key, mark whether it should be the default gateway, and save.

​

API example

curl --location --request POST "https://api.unibee.dev/merchant/vat/setup_us_vat_gateway" \
  --header "Authorization: Bearer $UNIBEE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "gatewayName": "TaxJar",
    "isDefault": true,
    "apiKeys": {
      "apiKey": "taxjar_live_********************************"
    }
  }'

• gatewayName – currently TaxJar; future gateways will use the same endpoint.
• isDefault – set true if this should become the global default.
• apiKeys.apiKey – the live or sandbox token from TaxJar.

After initialization, you can confirm the connection by calling GET /merchant/profile/get. The response now includes usVATAPIKeys and globalUSVATConfig.

​

2. Configure the global US VAT defaults

​

Key fields

​

API example

curl --location --request POST "https://api.unibee.dev/merchant/vat/setup_global_us_vat_config" \
  --header "Authorization: Bearer $UNIBEE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "global_us_vat_config": {
      "active": true,
      "defaultGatewayName": "TaxJar",
      "taxCode": "31000",
      "fromAddress": {
        "countryCode": "US",
        "zipCode": "10001",
        "state": "NY",
        "city": "New York",
        "address": "335 Madison Ave"
      },
      "toAddress": {
        "countryCode": "US",
        "zipCode": "94105",
        "state": "CA",
        "city": "San Francisco",
        "address": "525 Market St"
      },
      "nexusAddresses": [],
      "checkAddressViaGateway": true,
      "uploadInvoiceToGateway": true
    }
  }'

• The response to GET /merchant/profile/get includes availableGatewayNames. Use this list to render gateway pickers—no need to supply it when you call setup_global_us_vat_config.
• Changing defaultGatewayName clears the cached tax code list. Prompt users to fetch a fresh list via /merchant/vat/us_vat_category_list.
• When the global config is active and a shopper selects US in Checkout/Sub Update/Assign Subscription, the address becomes mandatory. After the address changes, call your Preview API again so UniBee recalculates tax.
• Invoice metadata now carries USVATCalculateHistoryRequestId and USVATCalculateGatewayName for auditability.

​

3. Product & plan-level overrides

​

JSON snippet (Plan update)

{
  "planId": 456,
  "usVATConfig": {
    "active": true,
    "taxCode": "40030",
    "fromAddress": {
      "countryCode": "US",
      "zipCode": "98101",
      "state": "WA",
      "city": "Seattle",
      "address": "1201 3rd Ave"
    },
    "sellOnUSOnly": false
  }
}

​

4. Checkout & operational behavior

• US address required – When global US VAT is active and the shopper selects US, Checkout/Sub Update/Assign Subscription screens must collect the full US address.
• Force address validation – If checkAddressViaGateway = true, any US address (checkout, product config, plan config, global config) must be validated by calling POST /merchant/vat/us_vat_validate_address. Surface the normalized suggestions returned by TaxJar for the user to choose.
• Preview after address change – Tax amounts differ per state/city/ZIP, so always re-run the preview API after the user edits their US address.
• Upload invoices – When uploadInvoiceToGateway = true, UniBee submits invoices to TaxJar automatically, enabling managed filings.
• TaxJar category list – Use GET /merchant/vat/us_vat_category_list to show the latest product tax codes. The list is gateway-specific; refetch whenever the default gateway changes.
• UI hints – availableGatewayNames (from GET /merchant/profile/get) tells you which gateways can be selected in Global Config forms.
• Metadata on invoices – Helps support teams trace which gateway calculation and request ID were used.
• US-only plans – Checkout Plan Detail responses now include sellOnUSOnly (outer flag) so you can hide non-US plans until the buyer selects the United States.

​

5. API reference cheat sheet

​

6. Front-end checklist

• ☑️ Render the available gateways using availableGatewayNames.
• ☑️ When the default gateway changes, clear dependent fields (tax code, addresses, nexus) and prompt the user to fetch the new category list.
• ☑️ Enforce US address collection any time the buyer selects US while global US VAT is active.
• ☑️ If forced address validation is enabled, make sure both customer-entered addresses and configuration addresses are validated via us_vat_validate_address.
• ☑️ After successful validation or manual edits, rerun the Preview API because taxes will change.
• ☑️ Respect the sellOnUSOnly flag when showing plans in Checkout/Hosted pages.
• ☑️ Surface errors when an address, gateway, or tax code is missing—UniBee will reject the calculation otherwise.