Skip to content
Docs
APISign inStart free

Mark a registration application submitted

The registrations.mark_application_submitted operation: POST /api/v1/registrations/{id}/mark_application_submitted in the REST API and the registrations_mark_application_submitted tool in the MCP server.

POST/api/v1/registrations/{id}/mark_application_submitted

Records that the registration application for a regime in grace was filed with the tax authority, with proof (the submission receipt). The deadline is then satisfied: no more escalations, and new consumer sales are not stopped automatically while the registration number is awaited (spec §10.2). Mark it registered when the number arrives.

Needs grace, once. proof lists at least one document of the receipt: a file uploaded to the registration (registrations.documents.upload, then its file_… ID), the authority's receipt or application number, or a link to the document in your own storage.

Compliance tier (spec §41.4): tax managers, owners and admins. If the organization's approval policy lists this operation, the call answers approval_required and runs once a second person approves it. Returns the registration.

At a glance

  • REST: POST /api/v1/registrations/{id}/mark_application_submitted
  • MCP tool: registrations_mark_application_submitted
  • Operation ID: registrations.mark_application_submitted
  • Scope: Legal entity
  • Permission: registrations:write
  • Risk tier: compliance
  • Dry run: Supported (send Ownrecord-Dry-Run: true)
  • Idempotency: Idempotency-Key required
  • Modes: Test and live
  • Authentication: API key with the registrations:write scope
  • Since: M3

Request

Path parameters

FieldTypeDescription
idstringThe registration (regn_…) or its regime's ID, e.g. EU_OSS_UNION or US_SALES_TAX:TX.

Body

A JSON object (Content-Type: application/json):

FieldTypeRequiredDescription
proofarray of objectYesProof: at least one document (uploaded file_… or a reference) of the submission receipt or the registration confirmation.
proof[].referencestringYesA document uploaded to this registration (file_…), or the authority's receipt or application number, or a link to the document.
proof[].labelstringNoWhat the document is, e.g. OSS registration confirmation.
notestringNoWhy, or anything the team should know; kept in the registration's history and the audit log.

Response

200 OK with a JSON object:

FieldTypeDescription
idregn_… ID
object"registration"
entityIdent_… ID
livemodeboolean
regimeIdstring
regimeNamestring or null
jurisdictionIdsarray of string
stateone of not_applicable, monitored, pre_registration, grace, registered, blocked_b2c, deregistered
stateReasonone of 18 values, e.g. home_country, below_threshold, zero_threshold (all in the OpenAPI document)
stateChangedAtdate-time
armedboolean
triggeredAtdate-time or null
deadlineAtdate-time or null
autoBlockAtdate-time or null
applicationSubmittedAtdate-time or null
escalationLevelinteger (0 to 3)
registrationNumberstring or null
effectiveFromdate-time or null
registeredAtdate-time or null
prerequisitesDoneboolean
prerequisitesProgressobject
prerequisitesProgress.doneinteger
prerequisitesProgress.totalinteger
thresholdobject or null
timeZonesarray of string
createdAtdate-time
updatedAtdate-time
prerequisitesarray of object
prerequisites[].codestring
prerequisites[].descriptionstring or null
prerequisites[].leadTimeDaysinteger or null
prerequisites[].statusone of todo, in_progress, done
prerequisites[].doneAtdate-time or null
prerequisites[].notesstring
prerequisites[].ownerstring or null
prerequisites[].attachmentsarray of object
prerequisites[].attachments[].kindone of file, reference
prerequisites[].attachments[].refstring
prerequisites[].attachments[].labelstring or null
prerequisites[].attachments[].addedAtdate-time
prerequisites[].attachments[].addedBystring
prerequisites[].updatedAtdate-time or null
prerequisites[].updatedBystring or null
evidenceFilesarray of object
evidenceFiles[].kindone of file, reference
evidenceFiles[].refstring
evidenceFiles[].labelstring or null
evidenceFiles[].addedAtdate-time
evidenceFiles[].addedBystring
historyarray of object
history[].fromone of not_applicable, monitored, pre_registration, grace, registered, blocked_b2c, deregistered or null
history[].toone of not_applicable, monitored, pre_registration, grace, registered, blocked_b2c, deregistered
history[].atdate-time
history[].bystring
history[].reasonone of 18 values, e.g. home_country, below_threshold, zero_threshold (all in the OpenAPI document)
history[].notestring or null
countersarray of object
counters[].windowKeystring
counters[].amountmoney
counters[].transactionCountinteger
counters[].lastEventAtdate-time
regimeobject or null
playbooksarray of object
playbooks[].keystring
playbooks[].kindone of registration, filing, deregistration, other
playbooks[].markdownstring
officialLinksarray of object
officialLinks[].labelstring
officialLinks[].urlstring
actionsobject
actions.armobject
actions.arm.allowedboolean
actions.arm.codestring or null
actions.arm.messagestring or null
actions.markApplicationSubmittedobject
actions.markApplicationSubmitted.allowedboolean
actions.markApplicationSubmitted.codestring or null
actions.markApplicationSubmitted.messagestring or null
actions.markRegisteredobject
actions.markRegistered.allowedboolean
actions.markRegistered.codestring or null
actions.markRegistered.messagestring or null
actions.deregisterobject
actions.deregister.allowedboolean
actions.deregister.codestring or null
actions.deregister.messagestring or null
safetyBufferHoursinteger
knowledgeCommitstring

Examples

The OSS application was filed

HTTP
POST /api/v1/registrations/EU_OSS_UNION/mark_application_submitted
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "proof": [
    {
      "reference": "ePorezna receipt 2026-OSS-118274",
      "label": "Submission receipt"
    }
  ]
}

Response (200):

JSON
{
  "id": "regn_01m4tx5nj8emwbyf7y9vcf47xk",
  "object": "registration",
  "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "livemode": true,
  "regimeId": "EU_OSS_UNION",
  "regimeName": "EU One-Stop Shop, Union scheme",
  "jurisdictionIds": ["AT", "DE", "FR", "HR", "IT", "NL"],
  "state": "grace",
  "stateReason": "application_submitted",
  "stateChangedAt": "2026-10-20T08:15:00.000Z",
  "armed": false,
  "triggeredAt": "2026-10-14T09:30:00.000Z",
  "deadlineAt": "2026-11-10T22:59:59.000Z",
  "autoBlockAt": null,
  "applicationSubmittedAt": "2026-10-20T08:15:00.000Z",
  "escalationLevel": 0,
  "registrationNumber": null,
  "effectiveFrom": null,
  "registeredAt": null,
  "prerequisitesDone": true,
  "prerequisitesProgress": {
    "done": 1,
    "total": 1
  },
  "threshold": {
    "status": "over",
    "window": "calendar_year_current_or_previous",
    "measure": "eu_cross_border_b2c",
    "currentWindow": "2026",
    "previousWindow": "2025",
    "threshold": {
      "amount": "10000000000",
      "currency": "EUR"
    },
    "current": {
      "amount": "8500000000",
      "currency": "EUR"
    },
    "previous": {
      "amount": "0",
      "currency": "EUR"
    },
    "transactionThreshold": null,
    "currentTransactions": null,
    "previousTransactions": null,
    "worldwideTurnoverDeclared": null,
    "ratioPpm": "1004500",
    "percent": 100,
    "detail": "8500.00 EUR counted (earlier window 0.00) against 10000.00 EUR"
  },
  "timeZones": ["Europe/Zagreb"],
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-20T08:15:00.000Z",
  "prerequisites": [
    {
      "code": "portal_access",
      "description": "Access to the tax portal of the member state of identification",
      "leadTimeDays": 7,
      "status": "done",
      "doneAt": "2026-10-13T12:00:00.000Z",
      "notes": "ePorezna access for the finance team",
      "owner": "Ana (finance)",
      "attachments": [],
      "updatedAt": "2026-10-13T12:00:00.000Z",
      "updatedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa"
    }
  ],
  "evidenceFiles": [
    {
      "kind": "reference",
      "ref": "ePorezna receipt 2026-OSS-118274",
      "label": "Submission receipt",
      "addedAt": "2026-10-20T08:15:00.000Z",
      "addedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa"
    }
  ],
  "history": [
    {
      "from": null,
      "to": "monitored",
      "at": "2026-10-13T12:00:00.000Z",
      "by": "system",
      "reason": "below_threshold",
      "note": null
    },
    {
      "from": "monitored",
      "to": "pre_registration",
      "at": "2026-10-13T12:00:00.000Z",
      "by": "system",
      "reason": "pre_registration_ratio_reached",
      "note": null
    },
    {
      "from": "pre_registration",
      "to": "grace",
      "at": "2026-10-14T09:30:00.000Z",
      "by": "system",
      "reason": "threshold_crossed",
      "note": null
    },
    {
      "from": "grace",
      "to": "grace",
      "at": "2026-10-20T08:15:00.000Z",
      "by": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
      "reason": "application_submitted",
      "note": null
    }
  ],
  "counters": [
    {
      "windowKey": "2026",
      "amount": {
        "amount": "8500000000",
        "currency": "EUR"
      },
      "transactionCount": 412,
      "lastEventAt": "2026-10-13T12:00:00.000Z"
    }
  ],
  "regime": {
    "id": "EU_OSS_UNION",
    "name": "EU One-Stop Shop, Union scheme",
    "version": "3f2a9c41d07e88b1",
    "jurisdictionIds": ["AT", "DE", "FR", "HR", "IT", "NL"],
    "sellerEstablishment": "in_eu_other_ms",
    "customerType": "b2c",
    "threshold": {
      "amount": {
        "amount": "10000000000",
        "currency": "EUR"
      },
      "measure": "eu_cross_border_b2c",
      "window": "calendar_year_current_or_previous",
      "transactionCount": null,
      "whatCounts": "B2C electronically supplied services to consumers in other member states, net of VAT.",
      "amountInclusive": false
    },
    "zeroThreshold": false,
    "grace": {
      "rule": "nth_day_of_following_month",
      "days": null,
      "nthDay": 10
    },
    "collectBeforeRegistration": true,
    "b2bReverseChargeNoRegistration": true,
    "b2bChargeWhenRegistered": false,
    "requiresFiscalRepresentative": false,
    "requiresLocalAgent": false,
    "securityDeposit": null,
    "registration": {
      "method": "online",
      "portalUrl": "https://e-porezna.porezna-uprava.hr",
      "identityRequirements": null,
      "typicalProcessingDays": 7
    },
    "status": "verified",
    "unverified": false,
    "fixture": false,
    "validFrom": "2021-07-01",
    "validTo": null
  },
  "playbooks": [
    {
      "key": "EU/playbooks/EU_OSS_UNION-registration.md",
      "kind": "registration",
      "markdown": "# Registering for the Union OSS\n\n1. Sign in to the portal of your member state …"
    }
  ],
  "officialLinks": [
    {
      "label": "EU One-Stop Shop, Union scheme: registration portal",
      "url": "https://e-porezna.porezna-uprava.hr"
    }
  ],
  "actions": {
    "arm": {
      "allowed": false,
      "code": "registration_transition_invalid",
      "message": "EU_OSS_UNION is grace, so \"arm\" isn't possible."
    },
    "markApplicationSubmitted": {
      "allowed": false,
      "code": "registration_transition_invalid",
      "message": "The application for EU_OSS_UNION is already marked submitted (2026-10-20T08:15:00.000Z)."
    },
    "markRegistered": {
      "allowed": true,
      "code": null,
      "message": null
    },
    "deregister": {
      "allowed": false,
      "code": "registration_transition_invalid",
      "message": "EU_OSS_UNION is grace, so \"deregister\" isn't possible."
    }
  },
  "safetyBufferHours": 72,
  "knowledgeCommit": "1c14b2ec912aca347dd518b2044096f3b5d8eef1"
}

Errors

CodeHTTP statusWhenWhat to do
registration_transition_invalid409The registration isn't in grace, or the application is already marked submitted.Check the registration's state (details.state): details.allowed_from lists the states the action needs. Reload the registration and try the action that fits its state.
registration_details_invalid400No proof was given (param: proof).Fill in the field named in param: the registration number, the date it is effective from, or at least one proof file.
validation_failed400A field is malformed, or a file_… proof isn't a document of this registration (param: proof.0.reference).Fix the fields listed in details.issues and send the request again.
resource_not_found404This entity has no such registration in this mode.Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
jurisdiction_blocked422The tax knowledge no longer has a usable regime for this registration, so it can't change now.This jurisdiction isn't covered by usable tax knowledge for this seller. Contact support if you need to sell there.
approval_required202The organization's approval policy needs a second person for this action; nothing changed yet.Nothing ran yet. An approver reviews approval.summary and the dry-run result in the console (approval.approveUrl). Poll GET /approvals/{id} or watch for the approval.resolved event; sending the same request again with the same Idempotency-Key returns the same approval.
approval_rejected409The same request was sent again after it was rejected.Read the reason in details.approval.rejection. To try again, send a new request with a new Idempotency-Key.
approval_expired409The same request was sent again after its approval request expired.Send the request again with a new Idempotency-Key to create a new approval request. Requests expire after 72 hours.
stale_approval409The approved request could no longer run as requested.Check the current state (details.approval.failure says what failed), then send a new request with a new Idempotency-Key.
idempotency_key_reused409The idempotency key was used before with another input.Use a new Idempotency-Key for a different request, or resend the original request unchanged.
livemode_not_allowed403You have no live-mode access, so you can't change live registrations.Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.
scope_required400The request names no legal entity (an org key without Ownrecord-Entity).Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (details.required_scope).
permission_denied403You can't change this entity's registrations (tax managers, owners and admins can).Ask an organization owner or admin for a role or scope that allows this action.
version_conflict409The registration changed at the same moment (a sale or the deadline job); reload and retry.Fetch the object again and retry the change.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_required, idempotency_in_progress, approval_policy_denied, rate_limited, internal_error.