Reference → Taxes — Reference

Taxes — Reference

The Taxes surface is the tax-calculation plane for every SGEN site that sells goods or services. It owns the catalogue of tax regions a site collects in, the rates that apply per region, the inclusive-versus-exclusive display rule that decides how prices are shown, the digital-goods exception for jurisdictions that tax software differently from physical goods, and the exemption-certificate records that exclude qualifying buyers from collection.

This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping a tax-compliance integration. Customer-facing setup walkthroughs live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.

Overview

Taxes live under the Ecommerce → Taxes module in SG-Admin. The module renders four primary views — the region list, the per-region rate editor, the display-rule editor, and the exemption certificate list — and exposes write operations for region create, rate edit, display-rule edit, exemption upload, and region delete.

The module is paired by convention with the Orders surface and the Shipping surface. Tax decisions made here are read at checkout by the cart engine alongside the shipping resolution, written onto the order record at purchase time as a line-item snapshot, and consulted again on refund to compute the refundable tax portion. Engineers reading the SG-Admin source will see the read half (region resolution, rate quoting, exemption check) split from the write half (region CRUD, rate edits, exemption ingest); the reference below describes the combined surface as it appears to a calling integration.

A second surface — digital-goods overrides — lives adjacent under the same module. Some jurisdictions tax digital products at a different rate than physical products, or apply place-of-supply rules that diverge from the standard destination-based rule. The override surface lets an operator declare those exceptions per region.

Where it lives in SG-Admin:

Sidebar: SG-Admin → Ecommerce → Taxes
URL prefix: /sg-admin/taxes/
View templates: application/views/Admin/Taxes/

The module surface is scoped to tax calculation and exemption. Order totals, refund logic, and payout reconciliation live in adjacent surfaces. This page covers only the region-rate-exemption plane.

┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Ecommerce → Taxes [+ Add region]│├──────────────────────────────────────────────────────────────────────┤│ Region name Coverage Rate Display ││ ───────────────── ──────────────────── ─────────── ──────────────││ Philippines (VAT) PH 12.00% Inclusive ││ EU VAT (DE) Germany 19.00% Inclusive ││ EU VAT (FR) France 20.00% Inclusive ││ United States (CA) California 7.25% + loc Exclusive ││ Digital — EU EU 27 countries varies Inclusive ││ ││ [⋯ Edit] [⋯ Rates] [⋯ Exemptions] [⋯ Delete] │└──────────────────────────────────────────────────────────────────────┘

Actions

The Taxes surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.

List regions

Returns the tax regions configured for the current site, in display order. Each row carries its name, its coverage (country code, country-and-subdivision pair, or postal-code range), the headline rate, the display rule, and an active flag. The default sort is the operator-defined display order, used by the checkout engine to resolve a buyer destination into a region — the first matching region wins.

Create region

Opens an empty region form. Required fields: region name, coverage, base rate, display rule (inclusive or exclusive). Optional fields cover the tax label shown to the buyer (for example, "VAT" or "GST"), the digital-goods override flag, and the place-of-supply rule. On submit, the surface validates that the coverage does not collide with an earlier region and persists the new record.

Edit region

Loads an existing region into the same form shape used for create, pre-populated. Submit replaces the stored region definition. Existing orders are unaffected — they carry a snapshot of the rate that applied at purchase time.

Edit rate

For regions with a single flat rate, the rate editor is the same form used to create the region. For regions with sub-rates (for example, US states with local rates layered on top of the state rate), the rate editor exposes a sub-rate table where each row carries a sub-region and a rate.

Edit display rule

Toggles between inclusive (prices shown to the buyer already include tax) and exclusive (tax is added at the cart). The display rule cascades to product pages, cart, checkout, and email receipts. Switching the rule does not reprice existing products; it only changes how the existing price is interpreted.

Add digital-goods override

Opens a sub-form attached to a region. Captures the override rate and the place-of-supply rule for digital products. When set, the cart engine routes digital line items through the override and physical line items through the base rate.

Upload exemption certificate

Opens the exemption form. Captures the buyer identifier (customer account ID, business tax number, or email), the issuing authority, the certificate document upload, an effective date range, and a list of regions the exemption applies to. On submit, the surface stores the document, indexes the buyer identifier, and exempts matching orders from collection in the named regions.

Revoke exemption

Marks an exemption record inactive. Orders placed before revocation retain their tax-free status. Orders placed after revocation collect tax in the previously exempted regions.

Delete region

Removes a region. The surface prompts for confirmation, lists the orders that previously used the region (for audit), and on confirm removes the region. Existing orders retain their tax snapshot and are unaffected.

Data model

A tax region carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.

Field	Type	Notes
`id`	integer	Primary key. Stable across edits.
`name`	string	Operator-facing label.
`coverage`	array	Country codes, subdivision pairs, or postal-code ranges.
`base_rate`	decimal	The headline rate, expressed as a percentage.
`display_rule`	enum	`inclusive` or `exclusive`.
`tax_label`	string	Buyer-facing label — for example, "VAT", "GST", "Sales tax".
`display_order`	integer	Resolution priority at checkout — lower wins.
`status`	enum	`active` or `inactive`.
`created_at`	timestamp	Set on create, immutable.
`updated_at`	timestamp	Touched on any edit.

A sub-rate (layered onto a region) carries:

Field	Type	Notes
`id`	integer	Primary key.
`region_id`	integer	Foreign key to the parent region.
`coverage`	string	Sub-region identifier — for example, a city or postal code.
`rate`	decimal	Sub-rate, added on top of the base rate.
`applies_to`	enum	`physical`, `digital`, or `both`.

A digital-goods override carries:

Field	Type	Notes
`id`	integer	Primary key.
`region_id`	integer	Foreign key to the parent region.
`digital_rate`	decimal	Replaces the base rate for digital line items.
`place_of_supply`	enum	`destination` (buyer location) or `origin` (seller location).

An exemption certificate carries:

Field	Type	Notes
`id`	integer	Primary key.
`buyer_identifier`	string	Customer ID, business tax number, or email.
`issuing_authority`	string	Free-text — for example, "California State Board of Equalization".
`document_url`	string	Reference to the uploaded certificate document.
`regions`	array	List of region IDs the exemption applies to.
`effective_from`	date	Lower bound of validity.
`effective_to`	date	Upper bound. Optional; null means open-ended.
`status`	enum	`active` or `revoked`.

TAX REGION├── id integer primary key├── name string operator-facing label├── coverage array country codes / subdivisions / postal├── base_rate decimal headline rate (percentage)├── display_rule enum inclusive | exclusive├── tax_label string buyer-facing — VAT / GST / Sales tax└── status enum active | inactive↓ has many (optional) ↓ has at most one (optional)SUB-RATE DIGITAL OVERRIDE├── coverage sub-region ├── digital_rate decimal├── rate decimal └── place_of_supply destination | origin└── applies_to physical|digital↓ has many (independent)EXEMPTION CERTIFICATE├── buyer_identifier customer / tax number / email├── document_url reference to upload├── regions list of region IDs└── effective range from / to dates

Region resolution. At checkout the cart engine walks the region list in display_order ascending, takes the first region whose coverage contains the destination, and applies that region's base rate. If a digital-goods override exists and the line item is digital, the override replaces the base rate for that line. If an active exemption certificate matches the buyer identifier and lists the resolved region, tax collection is skipped for the entire order.

Snapshot on order. When an order is placed, each line item's tax breakdown — region ID, applied rate, override flag, exemption flag — is snapshotted onto the order. Subsequent edits to the region or rate do not retroactively change the order. Refunds compute against the snapshot.

Permissions

Access to the Taxes surface is gated at two layers.

Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Taxes surface.

Layer 2 — per-action capability. Within SG-Admin, each Taxes action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:

Capability	Administrator	Editor	Viewer
List regions	✔	✔	✔
Create region	✔	—	—
Edit region	✔	—	—
Edit rate	✔	—	—
Edit display rule	✔	—	—
Add digital override	✔	—	—
Upload exemption	✔	✔	—
Revoke exemption	✔	—	—
Delete region	✔	—	—

Custom roles defined under Settings → Roles override the default map. The capability slugs are stable; the role slugs are configurable.

Document handling. Exemption certificate documents are stored under the Media library with access restricted to operators carrying the upload-exemption capability. The document URL returned to a buyer-facing surface is signed and short-lived. Internal admin views render the document with the standard Media viewer.

Audit. Every write — region create, region edit, rate edit, display-rule change, digital override, exemption upload, exemption revoke, region delete — emits an Activity Log entry. The log records the acting operator, the target record, and the change shape (field-level diff for edits). Tax-rate changes are tagged for compliance review. Activity Log retention is governed by the site's general settings.

REQUEST (checkout or admin)│▼┌───────────────────────────┐│ Admin gate (admin only) │ unauth → reject└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-action) │└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Region resolver │ match coverage → first wins└─────────────┬─────────────┘│ matched▼┌───────────────────────────┐│ Override check │ digital line → override rate└─────────────┬─────────────┘│▼┌───────────────────────────┐│ Exemption check │ match buyer ID + region → skip└─────────────┬─────────────┘│▼rate applied & snapshotted│▼Activity Log entry (on writes)

Related references

Orders — Reference. Order records snapshot per-line tax breakdown — region, rate, override flag, exemption flag — at purchase time. Refund logic on the order surface reads that snapshot.
Shipping — Reference. Some jurisdictions tax the shipping line; the toggle for that lives here, but resolution runs alongside the shipping resolver at checkout.
Products — Reference. Products carry a tax-class flag (physical or digital) that routes them through base rate or digital override.
Customer Accounts — Reference. Customer records carry an optional tax identifier; exemption certificates index against it.
Settings — Reference. Owns the site's reporting currency and the role capability map that gates this surface.
Reports — Reference. Tax collected per region, per period, is exposed under the reports surface for compliance filing.

For the corresponding customer-facing walkthrough — adding a region, uploading an exemption certificate, configuring digital-goods tax — see the Taxes section of the customer docs at /docs/taxes.

On this page

Guides

Reference

Changelog

Roadmap