Create 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": "CCT_US_STATE_CEN_06_RST",
    "tax_types": ["RST", "DTT"],
    "frequency": "QUARTERLY",
    "effective_start_date": "2024-01-15"
  }'

{
  "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
  "registration_content_id": "CCT_US_STATE_CEN_48_RST",
  "tax_types": ["RST"]
}

{
  "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-15"
}

{
  "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-15",
  "tax_registration_id": "123-456789-00",
  "portal_id": "PORTAL_CA_CDTFA",
  "credential_id": "cred_abc123def456"
}

{
  "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
  "registration_content_id": "<member_state_vat_content_id>",
  "tax_types": ["VAT"],
  "frequency": "QUARTERLY",
  "effective_start_date": "2024-01-01",
  "member_state_registration_id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789"
}

{
  "message": "Successfully created registration.",
  "data": {
    "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-15",
    "registration_status": "REGISTERED",
    "validation_status": "PENDING",
    "registration_type": "EXISTING",
    "registered_by": "API",
    "email_alias": "tax-ca@acme.commenda.io",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

{
  "message": "Failed to parse request body.",
  "error": {
    "type": "CLIENT_INVALID_REQUEST_BODY",
    "title": "Failed to validate the request body",
    "detail": "corporation_id is required; registration_content_id is required",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "REGISTRATION_CONTENT_NOT_FOUND",
    "title": "Registration content not found.",
    "detail": "The registration_content_id 'INVALID_ID' does not exist.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "DUPLICATE_REGISTRATIONS_FOUND",
    "title": "A registration already exists for this jurisdiction.",
    "detail": "You already have an active registration in California. Update the existing registration instead.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "REGISTRATION_INVALID_TAX_TYPE",
    "title": "Invalid tax type for this jurisdiction.",
    "detail": "Tax type 'XYZ' is not valid for California. Valid options: RST, RUT, DTT.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "REGISTRATION_PARENT_REQUIRED",
    "title": "State-level registration required.",
    "detail": "You must have an active California state registration before registering for Los Angeles County.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "REGISTRATION_PARENT_NOT_CONFIGURED",
    "title": "Parent state registration not configured.",
    "detail": "The parent state registration does not have tax_types configured. Please configure the state registration first.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "REGISTRATION_PARENT_NOT_CONFIGURED",
    "title": "Parent state registration not configured.",
    "detail": "The parent state registration does not have frequency configured. Please configure the state registration first.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "FREQUENCY_MISMATCH_WITH_PARENT",
    "title": "Frequency must match parent state.",
    "detail": "Frequency 'MONTHLY' does not match the parent state registration frequency 'QUARTERLY'.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "TAX_TYPE_MISMATCH_WITH_PARENT",
    "title": "Tax type not registered at state level.",
    "detail": "Tax type 'RUT' is not registered at the state level. State tax types: [RST, DTT].",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "TAX_TYPE_MISMATCH_WITH_PARENT",
    "title": "Missing required tax type from state.",
    "detail": "Tax type 'DTT' from the state registration must be included.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "CLIENT_INVALID_REQUEST_BODY",
    "title": "Invalid effective_start_date format.",
    "detail": "Date must be in ISO format (YYYY-MM-DD).",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "MEMBER_STATE_REGISTRATION_REQUIRED",
    "title": "Member state registration required.",
    "detail": "A member state registration is required for this registration content.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "INVALID_MEMBER_STATE_REGISTRATION",
    "title": "Invalid member state registration.",
    "detail": "The selected member state registration is not allowed for this registration content.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "MEMBER_STATE_REGISTRATION_NOT_ALLOWED",
    "title": "Member state registration not accepted.",
    "detail": "This registration content does not accept a member state registration.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

POST

api

registrations

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-15"
  }'

{
  "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
  "registration_content_id": "CCT_US_STATE_CEN_48_RST",
  "tax_types": ["RST"]
}

{
  "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-15"
}

{
  "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-15",
  "tax_registration_id": "123-456789-00",
  "portal_id": "PORTAL_CA_CDTFA",
  "credential_id": "cred_abc123def456"
}

{
  "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
  "registration_content_id": "<member_state_vat_content_id>",
  "tax_types": ["VAT"],
  "frequency": "QUARTERLY",
  "effective_start_date": "2024-01-01",
  "member_state_registration_id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789"
}

{
  "message": "Successfully created registration.",
  "data": {
    "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-15",
    "registration_status": "REGISTERED",
    "validation_status": "PENDING",
    "registration_type": "EXISTING",
    "registered_by": "API",
    "email_alias": "tax-ca@acme.commenda.io",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

{
  "message": "Failed to parse request body.",
  "error": {
    "type": "CLIENT_INVALID_REQUEST_BODY",
    "title": "Failed to validate the request body",
    "detail": "corporation_id is required; registration_content_id is required",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "REGISTRATION_CONTENT_NOT_FOUND",
    "title": "Registration content not found.",
    "detail": "The registration_content_id 'INVALID_ID' does not exist.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "DUPLICATE_REGISTRATIONS_FOUND",
    "title": "A registration already exists for this jurisdiction.",
    "detail": "You already have an active registration in California. Update the existing registration instead.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "REGISTRATION_INVALID_TAX_TYPE",
    "title": "Invalid tax type for this jurisdiction.",
    "detail": "Tax type 'XYZ' is not valid for California. Valid options: RST, RUT, DTT.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "REGISTRATION_PARENT_REQUIRED",
    "title": "State-level registration required.",
    "detail": "You must have an active California state registration before registering for Los Angeles County.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "REGISTRATION_PARENT_NOT_CONFIGURED",
    "title": "Parent state registration not configured.",
    "detail": "The parent state registration does not have tax_types configured. Please configure the state registration first.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "REGISTRATION_PARENT_NOT_CONFIGURED",
    "title": "Parent state registration not configured.",
    "detail": "The parent state registration does not have frequency configured. Please configure the state registration first.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "FREQUENCY_MISMATCH_WITH_PARENT",
    "title": "Frequency must match parent state.",
    "detail": "Frequency 'MONTHLY' does not match the parent state registration frequency 'QUARTERLY'.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "TAX_TYPE_MISMATCH_WITH_PARENT",
    "title": "Tax type not registered at state level.",
    "detail": "Tax type 'RUT' is not registered at the state level. State tax types: [RST, DTT].",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "TAX_TYPE_MISMATCH_WITH_PARENT",
    "title": "Missing required tax type from state.",
    "detail": "Tax type 'DTT' from the state registration must be included.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "CLIENT_INVALID_REQUEST_BODY",
    "title": "Invalid effective_start_date format.",
    "detail": "Date must be in ISO format (YYYY-MM-DD).",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "MEMBER_STATE_REGISTRATION_REQUIRED",
    "title": "Member state registration required.",
    "detail": "A member state registration is required for this registration content.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "INVALID_MEMBER_STATE_REGISTRATION",
    "title": "Invalid member state registration.",
    "detail": "The selected member state registration is not allowed for this registration content.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "MEMBER_STATE_REGISTRATION_NOT_ALLOWED",
    "title": "Member state registration not accepted.",
    "detail": "This registration content does not accept a member state registration.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

Create a registration to enable tax calculations and automated filing for a jurisdiction. Before calling this endpoint, use the content endpoints to discover available jurisdictions and get the required registration_content_id.

Request Body

string

required

The unique identifier for the corporation. Must be a valid UUID.

string

required

The content ID identifying the jurisdiction and tax type combination. Obtain this from the /registrations/content/registration-input-options endpoint.Example: CCT_US_STATE_CEN_06_RST (California Retail Sales Tax)

array

Array of tax types to register for. Must be valid for the selected registration_content_id.Common values:

RST — Retail Sales Tax
RUT — Retailer’s Use Tax
DTT — District Transaction Tax
SST — Simplified Sellers Use Tax

For state registrations: Required. Check related_tax_types from the registration options endpoint for required combinations.For local registrations: Optional. If not provided, inherited from parent state. If provided, must exactly match the parent state’s tax types.

string

Filing frequency for this registration.Values: MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUAL_CALENDAR_YEAR, FISCAL_YEAR, QUARTERLY_PREPAY_MONTHLY, MONTHLY_ACCELERATED_PREPAY_EARLYFor state registrations: Can be set later before validation.For local registrations: Optional. If not provided, inherited from parent state. If provided, must exactly match the parent state’s frequency.

string

ISO date (YYYY-MM-DD) when the registration became or becomes effective. Optional for new registrations where the date isn’t yet known.

string

Your state-issued tax registration ID, permit number, or account number. Required for validation but can be added later via update.

string

The ID of an existing trade bloc registration to link this registration to. Required when creating a registration for an EU member state or any jurisdiction that belongs to a trade bloc.The referenced registration must:

Belong to the same corporation
Be active (not archived or closed)
Have a registration_content_id that is listed as an allowed member state for the target content

When provided, the portal configuration is automatically inherited from the trade bloc registration.

string

Reference to stored portal credentials. Can be added later via update before requesting validation.

string

The portal ID for the state’s tax filing portal. Must be a valid portal for the selected registration content. Get available portals from the /registrations/content/portal-fields endpoint.For member state registrations linked to a trade bloc, the portal is inherited automatically and does not need to be specified.

Workflow

Get the registration_content_id — Use /registrations/content/available-jurisdictions to find jurisdictions, then /registrations/content/registration-input-options to get content IDs and valid tax types.
Create the registration — Call this endpoint with required fields. At minimum: corporation_id, registration_content_id, and tax_types.
Complete the registration — Use POST /registrations/{id} to add tax_registration_id, credential_id, and other fields.
Request validation — Once complete, call POST /registrations/{id}/request-validation to begin automated filing.

Validation Rules

Tax types: Must be valid for the jurisdiction. Invalid combinations return REGISTRATION_INVALID_TAX_TYPE.
Frequency: Must be one of the frequencies allowed for the jurisdiction.
Portal ID: If provided, must be a valid portal for the registration content.
Duplicate prevention: Only one registration per jurisdiction per corporation is allowed.

Trade bloc registration rules

When creating a registration that requires a member state link:

Requirement	Details
Trade bloc registration required	The `member_state_registration_id` must reference an existing registration
Same corporation	The trade bloc registration must belong to the same corporation
Active registration	The trade bloc registration must not be archived or closed
Allowed content ID	The trade bloc registration’s content ID must be listed as an allowed member state for the target content

Local registration rules

When creating a local registration (CITY, COUNTY, DISTRICT, etc.):

Requirement	Details
Parent state required	Must have an active state-level registration first
Parent must be configured	Parent state must have `tax_types` and `frequency` set
Inheritance	If you omit `tax_types` or `frequency`, they are inherited from the parent state
Matching	If you provide `tax_types` or `frequency`, they must exactly match the parent state

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-15"
  }'

{
  "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
  "registration_content_id": "CCT_US_STATE_CEN_48_RST",
  "tax_types": ["RST"]
}

{
  "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-15"
}

{
  "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-15",
  "tax_registration_id": "123-456789-00",
  "portal_id": "PORTAL_CA_CDTFA",
  "credential_id": "cred_abc123def456"
}

{
  "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
  "registration_content_id": "<member_state_vat_content_id>",
  "tax_types": ["VAT"],
  "frequency": "QUARTERLY",
  "effective_start_date": "2024-01-01",
  "member_state_registration_id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789"
}

{
  "message": "Successfully created registration.",
  "data": {
    "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-15",
    "registration_status": "REGISTERED",
    "validation_status": "PENDING",
    "registration_type": "EXISTING",
    "registered_by": "API",
    "email_alias": "tax-ca@acme.commenda.io",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

{
  "message": "Failed to parse request body.",
  "error": {
    "type": "CLIENT_INVALID_REQUEST_BODY",
    "title": "Failed to validate the request body",
    "detail": "corporation_id is required; registration_content_id is required",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "REGISTRATION_CONTENT_NOT_FOUND",
    "title": "Registration content not found.",
    "detail": "The registration_content_id 'INVALID_ID' does not exist.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "DUPLICATE_REGISTRATIONS_FOUND",
    "title": "A registration already exists for this jurisdiction.",
    "detail": "You already have an active registration in California. Update the existing registration instead.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "REGISTRATION_INVALID_TAX_TYPE",
    "title": "Invalid tax type for this jurisdiction.",
    "detail": "Tax type 'XYZ' is not valid for California. Valid options: RST, RUT, DTT.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "REGISTRATION_PARENT_REQUIRED",
    "title": "State-level registration required.",
    "detail": "You must have an active California state registration before registering for Los Angeles County.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "REGISTRATION_PARENT_NOT_CONFIGURED",
    "title": "Parent state registration not configured.",
    "detail": "The parent state registration does not have tax_types configured. Please configure the state registration first.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "REGISTRATION_PARENT_NOT_CONFIGURED",
    "title": "Parent state registration not configured.",
    "detail": "The parent state registration does not have frequency configured. Please configure the state registration first.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "FREQUENCY_MISMATCH_WITH_PARENT",
    "title": "Frequency must match parent state.",
    "detail": "Frequency 'MONTHLY' does not match the parent state registration frequency 'QUARTERLY'.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "TAX_TYPE_MISMATCH_WITH_PARENT",
    "title": "Tax type not registered at state level.",
    "detail": "Tax type 'RUT' is not registered at the state level. State tax types: [RST, DTT].",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "TAX_TYPE_MISMATCH_WITH_PARENT",
    "title": "Missing required tax type from state.",
    "detail": "Tax type 'DTT' from the state registration must be included.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "CLIENT_INVALID_REQUEST_BODY",
    "title": "Invalid effective_start_date format.",
    "detail": "Date must be in ISO format (YYYY-MM-DD).",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "MEMBER_STATE_REGISTRATION_REQUIRED",
    "title": "Member state registration required.",
    "detail": "A member state registration is required for this registration content.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "INVALID_MEMBER_STATE_REGISTRATION",
    "title": "Invalid member state registration.",
    "detail": "The selected member state registration is not allowed for this registration content.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

{
  "error": {
    "type": "MEMBER_STATE_REGISTRATION_NOT_ALLOWED",
    "title": "Member state registration not accepted.",
    "detail": "This registration content does not accept a member state registration.",
    "status": 400,
    "instance": "/api/v1/registrations"
  }
}

Registration Content API — Discover jurisdictions and get content IDs
Update Registration — Add credentials before validation
Request Validation — Enable automated filing
Tax Registrations Overview — Full workflow

Get Started

Registrations

Registrations V2

Corporations

Tax Calculations

Transactions

Address Requirements

Registration Thresholds

Products

Customers

Exemption Certificates

Exemptions

Files

Credentials

Locations

Filings

Webhooks

Request Body

Workflow

Validation Rules

Trade bloc registration rules

Local registration rules

​Request Body

​Workflow

​Validation Rules

​Trade bloc registration rules

​Local registration rules

​Related

Request Body

Workflow

Validation Rules

Trade bloc registration rules

Local registration rules

Related