Skip to main content
POST
/
api
/
v1
/
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"
  }'

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

​
corporation_id
string
required
The unique identifier for the corporation. Must be a valid UUID.
​
registration_content_id
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)
​
tax_types
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.
​
frequency
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.
​
effective_start_date
string
ISO date (YYYY-MM-DD) when the registration became or becomes effective. Optional for new registrations where the date isn’t yet known.
​
tax_registration_id
string
Your state-issued tax registration ID, permit number, or account number. Required for validation but can be added later via update.
​
member_state_registration_id
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.
​
credential_id
string
Reference to stored portal credentials. Can be added later via update before requesting validation.
​
portal_id
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

  1. 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.
  2. Create the registration — Call this endpoint with required fields. At minimum: corporation_id, registration_content_id, and tax_types.
  3. Complete the registration — Use POST /registrations/{id} to add tax_registration_id, credential_id, and other fields.
  4. 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:
RequirementDetails
Trade bloc registration requiredThe member_state_registration_id must reference an existing registration
Same corporationThe trade bloc registration must belong to the same corporation
Active registrationThe trade bloc registration must not be archived or closed
Allowed content IDThe 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.):
RequirementDetails
Parent state requiredMust have an active state-level registration first
Parent must be configuredParent state must have tax_types and frequency set
InheritanceIf you omit tax_types or frequency, they are inherited from the parent state
MatchingIf 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"
  }'

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