Using tax_address_region_id with Sage Business Cloud Accounting

Overview

The tax_address_region_id field is required when creating invoices in Sage Business Cloud Accounting for Canada and United States accounts. This field specifies the tax region (province/state) for accurate tax calculation.

Important: This field is not currently mapped in the Unified API connector, so you must use the pass_through feature to include it in your requests.

When is tax_address_region_id Required?

✅ Required for: Canada and United States Sage Business Cloud Accounting accounts
❌ Not needed for: Other countries (e.g., Great Britain, France, Germany, etc.)

Region ID Format

The tax_address_region_id follows a specific pattern:

Canada: CA-XX where XX is the two-letter province/territory code
United States: US-XX where XX is the two-letter state code

Canadian Province/Territory Codes

Province/Territory	Code	Region ID
Alberta	AB	`CA-AB`
British Columbia	BC	`CA-BC`
Manitoba	MB	`CA-MB`
New Brunswick	NB	`CA-NB`
Newfoundland and Labrador	NL	`CA-NL`
Nova Scotia	NS	`CA-NS`
Northwest Territories	NT	`CA-NT`
Nunavut	NU	`CA-NU`
Ontario	ON	`CA-ON`
Prince Edward Island	PE	`CA-PE`
Québec	QC	`CA-QC`
Saskatchewan	SK	`CA-SK`
Yukon	YT	`CA-YT`

United States State Codes

Use standard two-letter state abbreviations with the US- prefix.

How to use pass_through

Correct Structure

{
  "customer": { "id": "..." },
  "invoice_date": "2025-01-15",
  "line_items": [...],
  "pass_through": [
    {
      "service_id": "sage-business-cloud-accounting",
      "extend_paths": [
        {
          "path": "$.sales_invoice.tax_address_region_id",
          "value": "CA-PE"
        }
      ]
    }
  ]
}

Correct Path

{
  "path": "$.sales_invoice.tax_address_region_id",
  "value": "CA-PE"
}

Complete Working Example

{
  "type": "product",
  "customer": {
    "id": "6f9ef56480244aa9bc6bd5bb5fd1b6ec"
  },
  "invoice_date": "2025-11-25",
  "due_date": "2025-11-27",
  "status": "draft",
  "currency": "CAD",
  "total": 0,
  "customer_memo": "Invoice memo text",
  "line_items": [
    {
      "id": "4b00a15a-7626-4885-9741-bd5ef56debe9",
      "description": "Fish Cake",
      "type": "sales_item",
      "tax_amount": 0.9,
      "total_amount": 6,
      "quantity": 2,
      "unit_price": 3,
      "unit_of_measure": "kg",
      "tax_rate": {
        "id": "CA_HST_PE"
      },
      "ledger_account": {
        "id": "436cd9fb851611f0a8690eaf0ceb371d"
      }
    }
  ],
  "billing_address": {
    "line1": "123 Great George",
    "city": "Charlottetown",
    "state": "PE",
    "postal_code": "A1A 1A1",
    "country": "CA"
  },
  "pass_through": [
    {
      "service_id": "sage-business-cloud-accounting",
      "extend_paths": [
        {
          "path": "$.sales_invoice.tax_address_region_id",
          "value": "CA-PE"
        }
      ]
    }
  ]
}

Important Requirements

1. Line Items Must Include tax_amount

{
  "line_items": [
    {
      "description": "Product Name",
      "type": "sales_item",
      "tax_amount": 0.9,
      "total_amount": 6,
      "quantity": 2,
      "unit_price": 3,
      "tax_rate": {
        "id": "CA_HST_PE"
      }
    }
  ]
}

2. pass_through Placement

{
  "customer": {...},
  "line_items": [...],
  "pass_through": [...]
}

3. Region ID Must Match Billing Address

{
  "billing_address": {
    "state": "PE",
    "country": "CA"
  },
  "pass_through": [
    {
      "service_id": "sage-business-cloud-accounting",
      "extend_paths": [
        {
          "path": "$.sales_invoice.tax_address_region_id",
          "value": "CA-PE"
        }
      ]
    }
  ]
}

Common Mistakes to Avoid

Nesting pass_through incorrectly
Wrong path value
Missing tax_amount
Incorrect region ID format

How to Find Valid Region IDs

Query existing invoices
Use standard ISO codes
Query tax rates for a region

Troubleshooting

Common errors include missing tax_address_region_id, missing tax_rate, or incorrect region ID format.

Summary

Use pass_through with path $.sales_invoice.tax_address_region_id
Place pass_through at the root level
Use CA-XX or US-XX format
Include tax_amount on every line item
Region ID must match billing address
Required only for Canada and US accounts