Tax Registrations - Commenda — Entity Management, Indirect Tax, Compliance & Corporate APIs for Multinationals

Overview

A registration represents a seller’s tax registration with a tax authority in a specific jurisdiction (state, city, county, or district). Commenda tracks these registrations at the corporation level to ensure accurate tax calculations and enable automated filing. Before you can collect and remit sales tax in a jurisdiction, you must be registered with the relevant tax authority. Commenda’s registration system:

Enables accurate tax calculations — The /calculate endpoint uses your active registrations to determine applicable taxes
Supports automated filing — Once validated, Commenda automatically files returns on your behalf
Handles complex jurisdiction hierarchies — State-level registrations can cover local jurisdictions, or you can register separately for cities/counties with home-rule authority

Getting Started? See the Registration Content API to discover available jurisdictions and understand what information is needed for each state.

Key Concepts

Registration Content

Commenda maintains a content database of all available tax jurisdictions and their requirements. Each jurisdiction has a unique registration_content_id that you use when creating registrations. Use the Registration Content API to discover jurisdictions and get the required content IDs. This content-based approach ensures:

Correct jurisdiction metadata is automatically applied
Tax type and frequency options are validated against what the jurisdiction actually supports
Portal credentials are collected according to each state’s requirements

Jurisdiction Hierarchy

Registrations follow a hierarchy:

Trade bloc registrations (e.g., EU VAT) — Cover multiple member countries under a single registration. Required before creating member-state-level registrations that reference the trade bloc.
Country registrations — For countries outside the US, or for EU member states linked to a trade bloc registration.
State/Province registrations — Required first for US jurisdictions. Cover most tax collection for the state.
Local registrations (City, County, District) — Optional. Required only for jurisdictions with separate filing requirements (home-rule jurisdictions).

Trade bloc registrations and member states:

A trade bloc registration (e.g., EU VAT) represents a single registration that covers multiple member countries
When creating a registration for an EU member state, you must link it to your existing trade bloc registration using the member_state_registration_id field
The member state registration inherits the portal configuration from the trade bloc registration
Use the Registration Input Options endpoint to discover which member state content IDs are available for a trade bloc registration

Local registrations inherit from their parent state:

When creating a local registration, you must have an active state-level registration first
If you don’t provide tax_types or frequency, they are automatically inherited from the parent state
If you do provide them, they must exactly match the parent state’s values

State updates cascade to local registrations:

Updating tax_types or frequency on a state registration automatically updates all local registrations under that state
Archiving or closing a state registration automatically archives/closes all local registrations under that state

Tax Types

Each registration specifies which tax types you’re collecting. Common tax types include:

RST — Retail Sales Tax
RUT — Retailer’s Use Tax
DTT — District Transaction Tax
SST — Simplified Sellers Use Tax
VAT — Value Added Tax (used for UK, EU, and other international jurisdictions)
GST — Goods and Services Tax (Canada)
HST — Harmonized Sales Tax (Canada)
PST — Provincial Sales Tax (Canada)
QST — Quebec Sales Tax (Canada)
BPT — Business Privilege Tax
BRT — Business and Retail Tax

Some jurisdictions require multiple tax types to be registered together (e.g., RST + DTT in California). Use the Registration Input Options endpoint to discover which tax types are available and required for each jurisdiction.

Registration Workflow

Step 1: Discover Available Jurisdictions

Use the Available Jurisdictions endpoint to find jurisdictions where you can register:

curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/registrations/content/available-jurisdictions' \
  --header 'Authorization: Bearer <your_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": {
      "countries": ["US"],
      "states": ["CA", "TX", "NY"],
      "types": ["STATE_OR_PROVINCE"]
    },
    "limit": 50
  }'

This returns jurisdictions with their jurisdiction_id for the next step.

Step 2: Get Registration Options

Use the Registration Input Options endpoint to retrieve the available tax types, frequencies, and registration content IDs:

curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/registrations/content/registration-input-options' \
  --header 'Authorization: Bearer <your_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": {
      "jurisdiction_ids": ["JUR_US_STATE_CA", "JUR_US_STATE_TX"]
    }
  }'

Response includes registration_content_id, available tax_types, frequencies, and any related tax types that must be registered together.

Step 3: Get Portal Credential Requirements

Use the Portal Fields endpoint to understand what credentials are needed for filing:

curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/registrations/content/portal-fields' \
  --header 'Authorization: Bearer <your_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": {
      "registration_content_ids": ["CCT_US_STATE_CEN_06_RST"]
    }
  }'

This returns the portal information and required credential fields (username, password, PIN, etc.) for each state’s tax portal.

Step 4: Create the Registration

Use the Create Registration endpoint with the content ID from Step 2:

curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/registrations' \
  --header 'Authorization: Bearer <your_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
    "registration_content_id": "CCT_US_STATE_CEN_06_RST",
    "tax_types": ["RST", "DTT"],
    "frequency": "QUARTERLY",
    "effective_start_date": "2024-01-01",
    "tax_registration_id": "123-456789"
  }'

At this point, Commenda will begin returning non-zero tax rates for this jurisdiction from the /calculate endpoint.

Step 5: Add Portal Credentials

Use the Update Registration endpoint to add portal credentials required for automated filing:

curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/registrations/7c9e6679-7425-40de-944b-e07fc1f90ae7' \
  --header 'Authorization: Bearer <your_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "portal_id": "PORTAL_CA_CDTFA",
    "credential_id": "cred_abc123"
  }'

Credentials are stored securely and managed separately from registrations. The credential_id references a stored credential set for the specified portal.

Step 6: Request Validation

Use the Request Validation endpoint to begin automated filing:

curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/registrations/7c9e6679-7425-40de-944b-e07fc1f90ae7/request-validation' \
  --header 'Authorization: Bearer <your_token>'

Commenda will:

Verify your tax registration ID with the state
Test your portal credentials
Configure the account for automated filing

Monitor the validation_status field to track progress.

Step 7: Automated Filing Begins

Once validation_status is VALID, Commenda will automatically:

Calculate your tax liability at the end of each filing period
File returns with the tax authority
Remit payments on your behalf

You should be:

Collecting sales tax using values from the /calculate endpoint
Recording completed transactions using the /transactions endpoint

EU trade bloc registrations

For businesses selling into the European Union, Commenda supports trade bloc registrations that model the EU as a supra-national jurisdiction covering multiple member states.

How it works

Create a trade bloc registration — Register at the EU level using a TRADEBLOC jurisdiction type content ID (e.g., for EU VAT). This represents your central EU VAT registration.
Link member state registrations — When you register in individual EU member states (e.g., Germany, France), pass member_state_registration_id referencing your trade bloc registration. This links the member state to the parent EU registration.
Portal inheritance — Member state registrations automatically inherit the portal configuration from the trade bloc registration. You do not need to specify a portal_id separately.

Example: registering for EU VAT

# Step 1: Find the EU trade bloc jurisdiction
curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/registrations/content/available-jurisdictions' \
  --header 'Authorization: Bearer <your_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": {
      "types": ["TRADEBLOC"]
    }
  }'

# Step 2: Get registration options for the EU jurisdiction
curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/registrations/content/registration-input-options' \
  --header 'Authorization: Bearer <your_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": {
      "jurisdiction_ids": ["TRADEBLOC_EU_3000"]
    }
  }'

# Step 3: Create the trade bloc registration
curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/registrations' \
  --header 'Authorization: Bearer <your_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
    "registration_content_id": "<eu_vat_content_id>",
    "tax_types": ["VAT"],
    "frequency": "QUARTERLY"
  }'

# Step 4: Create a member state registration linked to the trade bloc
curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/registrations' \
  --header 'Authorization: Bearer <your_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
    "registration_content_id": "<member_state_vat_content_id>",
    "tax_types": ["VAT"],
    "frequency": "QUARTERLY",
    "member_state_registration_id": "<trade_bloc_registration_id>"
  }'

The member_state_registration_id must reference an active, non-archived trade bloc registration that belongs to the same corporation. The content system validates that the member state content ID is allowed for the given trade bloc registration.

Registration Lifecycle

Status Fields

Field	Description	Values
`validation_status`	Whether Commenda has verified your registration	`PENDING`, `VALIDATION_IN_PROGRESS`, `VALID`, `INVALID`
`registration_status`	Current stage of the registration	`REGISTRATION_IN_PROGRESS`, `REGISTERED`

Validation Status Flow

PENDING — Default status. Commenda has your registration info but validation hasn’t been requested.
VALIDATION_IN_PROGRESS — You’ve called /request-validation. Commenda is verifying credentials.
VALID — All information verified. Automated filing is ready.
INVALID — Issues found. Check the registration for error details and update accordingly.

Closing a Registration

When you stop selling in a jurisdiction, use the Close Registration endpoint to set an end date:

curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/registrations/7c9e6679-7425-40de-944b-e07fc1f90ae7/close' \
  --header 'Authorization: Bearer <your_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "effective_end_date": "2024-12-31"
  }'

Closed registrations:

Still calculate tax for transactions within the effective_start_date to effective_end_date range
Stop calculating tax for transactions after the effective_end_date
Are preserved for historical records and filing obligations

Archiving a Registration

Use the Archive Registration endpoint to completely disable a registration:

curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/registrations/7c9e6679-7425-40de-944b-e07fc1f90ae7/archive' \
  --header 'Authorization: Bearer <your_token>'

Archived registrations:

Are excluded from list results unless include_archived: true is specified
Do not calculate tax — archived registrations are completely excluded from tax calculations

Deleting a Registration

Use the Delete Registration endpoint to permanently remove a registration. Only registrations in PENDING, VALIDATION_IN_PROGRESS, or INVALID status can be deleted:

curl --request DELETE \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/registrations/7c9e6679-7425-40de-944b-e07fc1f90ae7' \
  --header 'Authorization: Bearer <your_token>'

Registrations with validation_status: VALID cannot be deleted via API. Contact Commenda support for assistance.

Impact on Tax Calculations

The /calculate endpoint uses your active registrations to determine applicable taxes:

No registration → Tax amount is zero for that jurisdiction
Archived registration → Tax amount is zero (not used in calculations)
Closed registration → Tax calculated only for transactions within the effective date range
Active registration → Correct tax rates applied

Sample Registration Object

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
  "registration_content_id": "CCT_US_STATE_CEN_06_RST",
  "jurisdiction_id": "JUR_US_STATE_CA",
  "jurisdiction_type": "STATE_OR_PROVINCE",
  "jurisdiction_name": "California",
  "country": "US",
  "state_or_province": "CA",
  "tax_types": ["RST", "DTT"],
  "frequency": "QUARTERLY",
  "effective_start_date": "2024-01-01",
  "tax_registration_id": "123-456789",
  "member_state_registration_id": null,
  "portal_id": "PORTAL_CA_CDTFA",
  "credential_id": "cred_abc123",
  "registration_status": "REGISTERED",
  "validation_status": "VALID",
  "registration_type": "EXISTING",
  "registered_by": "API",
  "email_alias": "tax-ca@acme.commenda.io",
  "created_at": "2024-01-15T10:30:00Z"
}

The member_state_registration_id field is only populated for registrations linked to a trade bloc registration (e.g., EU member state registrations). For US state registrations, this field is null.

API Endpoints

Registration Content (Discovery)

Endpoint	Method	Description
`/registrations/content/available-jurisdictions`	POST	Discover jurisdictions where you can register
`/registrations/content/registration-input-options`	POST	Get tax types, frequencies for jurisdictions
`/registrations/content/portal-fields`	POST	Get portal credential requirements

Registration Management

Endpoint	Method	Description
`/registrations`	POST	Create a new registration
`/registrations/list`	POST	List registrations with filters
`/registrations/{id}`	GET	Get a single registration
`/registrations/{id}`	POST	Update a registration
`/registrations/{id}`	DELETE	Delete a registration

Registration Lifecycle

Endpoint	Method	Description
`/registrations/{id}/request-validation`	POST	Request Commenda validation
`/registrations/{id}/archive`	POST	Archive a registration (stops calculations)
`/registrations/{id}/close`	POST	Close a registration (sets end date)

Get Started

Registrations

Registrations V2

Corporations

Tax Calculations

Transactions

Address Requirements

Registration Thresholds

Products

Customers

Exemption Certificates

Exemptions

Files

Credentials

Locations

Filings

Webhooks

Documentation Index

​Overview

​Key Concepts

​Registration Content

​Jurisdiction Hierarchy

​Tax Types

​Registration Workflow

​Step 1: Discover Available Jurisdictions

​Step 2: Get Registration Options

​Step 3: Get Portal Credential Requirements

​Step 4: Create the Registration

​Step 5: Add Portal Credentials

​Step 6: Request Validation

​Step 7: Automated Filing Begins

​EU trade bloc registrations

​How it works

​Example: registering for EU VAT

​Registration Lifecycle

​Status Fields

​Validation Status Flow

​Closing a Registration

​Archiving a Registration

​Deleting a Registration

​Impact on Tax Calculations

​Sample Registration Object

​API Endpoints

​Registration Content (Discovery)

​Registration Management

​Registration Lifecycle

Overview

Key Concepts

Registration Content

Jurisdiction Hierarchy

Tax Types

Registration Workflow

Step 1: Discover Available Jurisdictions

Step 2: Get Registration Options

Step 3: Get Portal Credential Requirements

Step 4: Create the Registration

Step 5: Add Portal Credentials

Step 6: Request Validation

Step 7: Automated Filing Begins

EU trade bloc registrations

How it works

Example: registering for EU VAT

Registration Lifecycle

Status Fields

Validation Status Flow

Closing a Registration

Archiving a Registration

Deleting a Registration

Impact on Tax Calculations

Sample Registration Object

API Endpoints

Registration Content (Discovery)

Registration Management

Registration Lifecycle