Overview

Tax Rule objects define the criteria for automatically applying tax rates to financial line items based on order origin and destination locations.

In Rose Rocket, Tax Rule objects work in conjunction with Tax Rate objects to automate tax calculations on invoices. A Tax Rule specifies when a particular tax rate should be applied based on geographic criteria such as country and state/province codes for both the origin (shipper) and destination (consignee) addresses.

API Configuration

When using the API to make requests, refer to the following pages detailing the process. These guides walk through the requirements and setup to access the Rose Rocket API with your application.

Authentication - Access Rose Rocket with OAuth 2.0
Object operations - Configure your requests

Tax Rule Object Structure

Use the table below for information about the taxRule object.

Object Key Name: taxRule

Fields	Label	Type	Description
`id`	ID	string	Global unique identifier for record
`fullId`	Full ID	string	User identified record ID (e.g., `TAX-RULE-1`)
`name`	Name	string	Optional name of the tax rule for easy identification
`internalStatus`	Internal Status	string, enumerated	Status of the tax rule. Valid values are: `active`, `draft`, `archived`. Defaults to `active`. Only `active` rules are applied by the tax automation system.
`originStateCode`	Origin State	string	State or province code abbreviation for the shipper (origin) address (e.g., `CA` for California, `ON` for Ontario). Must be accompanied by `originCountryCode` if specified.
`originCountryCode`	Origin Country	string	Country code of the shipper (origin) address (e.g., `US`, `CA`)
`destinationStateCode`	Destination State	string	State or province code abbreviation for the consignee (destination) address (e.g., `NY` for New York, `QC` for Quebec). Must be accompanied by `destinationCountryCode` if specified.
`destinationCountryCode`	Destination Country	string	Country code of the consignee (destination) address (e.g., `US`, `CA`)
`effectiveDate`	Effective Date	string, date	Date when this tax rule takes effect (`YYYY/MM/DD`)
`taxRate`	Tax Rate	Tax Rate connected object. See Tax Rate	The tax rate to be applied when this rule matches. Required for the tax rule automation to function. One tax rate can be connected to multiple tax rules.
`lineItems`	Line Items	Financial Line Item connected object array (hidden field)	The financial line items to which this tax rule has been applied. This is automatically managed by the system. See Financial Line Items.
`taxRuleLabel`	Tax Rule Label	string (derived field)	Auto-generated human-readable label showing the origin and destination criteria (e.g., `From CA, US → To NY, US`). Derived from the location code fields.

Configuration Requirements

Organization-Level Settings

Tax rules must be enabled at the organization level before they will be applied. The organization configuration includes a hasTaxRulesEnabled setting that controls whether the tax rule automation system is active for your organization. This setting is off by default at the org-level.

Customer-Level Tax Exemption

Individual customers can be marked as tax-exempt using the isTaxExempt field on the Customer object. When a customer is marked as tax-exempt, tax rules will not be applied to invoices for that customer, regardless of the organization-level settings or matching tax rules. Customers are tax-exempt by default.

This allows you to maintain a comprehensive set of tax rules while selectively exempting specific customers who have tax-exempt status.

How Tax Rules Work

Tax Rules enable automatic tax calculation based on the origin and destination of shipments. When creating an invoice, the system evaluates all active tax rules to find the most specific rule that matches the order's origin and destination addresses.

Rule Matching Priority

The system applies rules based on a specificity hierarchy, from most specific to least specific:

Origin Country + State, Destination Country + State (4 fields - most specific)
Origin Country, Destination Country + State (3 fields)
Origin Country + State, Destination Country (3 fields)
Origin Country, Destination Country (2 fields)
Destination Country + State only (2 fields)
Origin Country + State only (2 fields)
Destination Country only (1 field)
Origin Country only (1 field - least specific)

The system selects the first matching rule based on this priority order. This allows you to create broad default rules (e.g., "all CAD orders") and override them with more specific rules (e.g., "Canada to Quebec orders").

Location Field Requirements

When configuring tax rules, the following requirements must be met:

A state/province code cannot exist without its corresponding country code
At least one of origin or destination must be specified
Multiple tax rules can share the same pattern type but must have different location values

Example Scenarios

Example 1: Specific Province-to-Province Rule

Origin: ON, CA (Ontario, Canada)
Destination: QC, CA (Quebec, Canada)
Tax Rate: 14.975% QST + GST

This rule applies the 14.975% combined tax (GST 5% + QST 9.975%) specifically for shipments from Ontario to Quebec.

Example 2: Country-Level Default Rule

Origin: (any)
Destination: CA (Canada)
Tax Rate: 5% GST

This rule applies 5% GST to all shipments delivered to Canada, regardless of origin.

Example 3: Combination of Rules

If you have the following active rules:

From (any) → To CA (Country-level, 5% GST)
From (any) → To QC, CA (Province-specific, 14.975% QST + GST)
From (any) → To ON, CA (Province-specific, 13% HST)

A shipment to Quebec would match rule #2 (most specific), a shipment to Ontario would match rule #3 (province-specific), while a shipment to British Columbia would match rule #1 (country-level default).

Tax Rule Status

Tax rules support three status values:

Active - The tax rule is enabled and will be evaluated by the tax automation system
Draft - The tax rule is being configured and will not be applied to invoices
Archived - The tax rule is no longer in use (e.g., due to tax rate changes or obsolete routing)

NOTE Only tax rules with active status and connected to an active tax rate will be applied by the automation system.

Best Practices

Enable at Organization Level: Ensure hasTaxRulesEnabled is set to true in your organization configuration before creating tax rules
Start Broad, Add Specificity: Begin with country-level rules for common scenarios, then add more specific state/province rules as needed
Use Effective Dates: Leverage the effectiveDate field to prepare for future tax rate changes
Avoid Duplicates: The system prevents creating duplicate rules (same pattern and location values) to maintain data integrity
Archive, Don't Delete: When a tax rule is no longer needed, archive it rather than deleting it to preserve the audit trail on financial line items
Test Before Activating: Use the draft status to configure and review rules before setting them to active
Customer Tax Exemptions: Use the isTaxExempt field on customer objects for tax-exempt customers rather than creating complex rule exclusions

Related Objects

Tax Rate - The rate applied when the rule matches. See Tax Rate and Tax Rate Components
Financial Line Item - The line items that tax rules are applied to. See Financial Line Items
Invoice - Primary use case for tax rule automation. See Invoices
Address - The origin and destination addresses used for rule matching. See Address