# This file is automatically generated. Do not edit it directly. Edit the files in /openapi instead
openapi: 3.0.1
info:
  title: Commenda Public APIs
  description: APIs for Commenda entity management, partner incorporation, indirect tax, compliance, and corporate operations.
  license:
    name: NONE
    url: NONE
  version: 1.0.0
servers:
  - url: https://api.prod.commenda.io/api/v1
    description: Commenda platform APIs, including Partner Incorporation and Commenda OS.
  - url: https://transaction-tax.api.in.commenda.io/api/v1
    description: Global Indirect Tax API.
security:
  - bearerAuth: []
paths:
  /webhooks:
    post:
      summary: Create a new webhook.
      description: Register your webhook with Commenda.
      operationId: registerWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '200':
          description: Sales tax registration response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CreateWebhookResponse'
                  message:
                    type: string
                    example: Successfully registered webhook.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: List all webhook.
      description: Get a list of all webhooks registered with Commenda.
      operationId: listAllWebhooks
      responses:
        '200':
          description: Sales tax registration response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      webhooks:
                        $ref: '#/components/schemas/GetWebhookResponse'
                  message:
                    type: string
                    example: Successfully fetched webhooks.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /webhooks/:id:
    post:
      summary: Update a webhook
      description: Update an existing webhook.
      operationId: updateWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookRequest'
      responses:
        '200':
          description: Sales tax registration response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Successfully updated webhook.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: Get a webhook.
      description: Get a webhook registered with Commenda.
      operationId: getWebhook
      responses:
        '200':
          description: Sales tax registration response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/GetWebhookResponse'
                  message:
                    type: string
                    example: Successfully fetched webhook.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a webhook
      description: Delete an existing webhook.
      operationId: deleteWebhook
      responses:
        '204':
          description: Sales tax registration response
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /webhooks/test/trigger/:id:
    post:
      summary: Test your webhook
      description: Trigger a test against your webhook.
      operationId: testWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                event_data:
                  type: object
                  description: Data to inject into event.data. When the webhook will be triggered the event will have this data.
      responses:
        '200':
          description: Sales tax registration response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Successfully triggered webhook.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /products:
    post:
      summary: Add a new product.
      description: Create a new product for a corporation.
      operationId: createProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProduct'
      responses:
        '200':
          description: Create product response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Product'
                  message:
                    type: string
                    example: Successfully created product.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: Get a product by id.
      operationId: getProduct
      parameters:
        - name: corporation_id
          in: query
          description: The unique identifier for a corporation to filter the products by.
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: Cursor for pagination
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Number of items to return per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: Fetch a product response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      products:
                        type: array
                        items:
                          $ref: '#/components/schemas/Product'
                      cursor:
                        type: string
                  message:
                    type: string
                    example: Successfully fetched products.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /products/bulk_upload/csv:
    post:
      summary: Bulk upload products
      description: Submit a CSV file of products for processing
      operationId: submitBulkProducts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - file_id
              properties:
                file_id:
                  type: string
                  description: The ID of a previously uploaded CSV file via the `/files` endpoint.
                corporation_id:
                  type: string
                  description: The unique identifier for a corporation to associate with these products.
      responses:
        '200':
          description: Successful product import job creation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      job:
                        $ref: '#/components/schemas/Job'
                  message:
                    type: string
                    example: Successfully started product import job.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /products/:id:
    post:
      summary: Update a product.
      description: Update an existing product by id.
      operationId: updateProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProduct'
      responses:
        '200':
          description: Create product response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Successfully updated product.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: Get a product by id.
      operationId: getProductById
      responses:
        '200':
          description: Fetch a product response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Product'
                  message:
                    type: string
                    example: Successfully fetched product.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a product by id.
      operationId: deleteProduct
      responses:
        '204':
          description: Delete a product response.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /products/{id}/customs-code:
    post:
      summary: Add or update a customs code for a product.
      description: Manage customs code for each product by jurisdiction.
      operationId: updateProductCustomsCode
      parameters:
        - in: path
          required: true
          name: id
          schema:
            type: string
          description: The unique identifier of the product to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - country
                - customs_code
              properties:
                country:
                  $ref: '#/components/schemas/Country'
      responses:
        '200':
          description: Set product customs code response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Successfully set product customs code.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a customs code for a product.
      operationId: deleteProductCustomsCode
      parameters:
        - in: path
          required: true
          name: id
          schema:
            type: string
          description: The unique identifier of the product to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - country
              properties:
                country:
                  description: ISO 3166 2-letter country code representing the country to remove the country code for.
                  $ref: '#/components/schemas/Country'
      responses:
        '204':
          description: Deleted customs code for product.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /corporations:
    post:
      summary: Add a new corporation.
      description: Create a new corporation for a sales tax partner.
      operationId: createCorporation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCorporation'
      responses:
        '200':
          description: Sales tax registration response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Corporation'
                  message:
                    type: string
                    example: Successfully created corporation.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: Get all corporations.
      description: Get all corporations associated with a sales tax partner.
      operationId: getCorporations
      parameters:
        - name: cursor
          in: query
          description: Cursor for pagination
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Number of items to return per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: Get all corporations response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                      - corporations
                    properties:
                      corporations:
                        type: array
                        items:
                          $ref: '#/components/schemas/Corporation'
                      cursor:
                        type: string
                  message:
                    type: string
                    example: Successfully fetched corporations.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /corporations/{id}:
    get:
      summary: Get corporation.
      description: Get a corporation by id.
      operationId: getCorporation
      parameters:
        - in: path
          required: true
          name: id
          schema:
            type: string
          description: The unique identifier of the corporation to fetch.
      responses:
        '200':
          description: Get one corporation response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Corporation'
                  message:
                    type: string
                    example: Successfully fetched corporation.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Update a corporation.
      description: Update details for a corporation.
      operationId: updateCorporation
      parameters:
        - in: path
          required: true
          name: id
          schema:
            type: string
          description: The unique identifier of the corporation to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCorporation'
      responses:
        '200':
          description: Update one corporation response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Successfully updated corporation.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete corporation.
      description: Delete a corporation by id.
      operationId: deleteCorporation
      parameters:
        - in: path
          required: true
          name: id
          schema:
            type: string
          description: The unique identifier of the corporation to delete.
      responses:
        '204':
          description: Delete one corporation response.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /registrations:
    post:
      summary: Create a registration
      description: Create a new sales tax registration using a registration_content_id obtained from the content/registration-input-options endpoint.
      operationId: createRegistration
      tags:
        - Registrations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRegistrationRequest'
      responses:
        '201':
          description: Registration created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RegistrationResponse'
                  message:
                    type: string
                    example: Successfully created registration.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /registrations/list:
    post:
      summary: List registrations
      description: List all registrations for a corporation with optional filters.
      operationId: listRegistrations
      tags:
        - Registrations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListRegistrationsRequest'
      responses:
        '200':
          description: Registrations retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      registrations:
                        type: array
                        items:
                          $ref: '#/components/schemas/RegistrationResponse'
                  message:
                    type: string
                    example: Successfully fetched registrations.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /registrations/{registration_id}:
    get:
      summary: Get a registration
      description: Retrieve a single registration by its ID.
      operationId: getRegistration
      tags:
        - Registrations
      parameters:
        - in: path
          required: true
          name: registration_id
          schema:
            type: string
            format: uuid
          description: The unique identifier of the registration.
      responses:
        '200':
          description: Registration retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RegistrationResponse'
                  message:
                    type: string
                    example: Successfully fetched registration.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Update a registration
      description: Update an existing registration with new details such as tax types, frequency, or credentials.
      operationId: updateRegistration
      tags:
        - Registrations
      parameters:
        - in: path
          required: true
          name: registration_id
          schema:
            type: string
            format: uuid
          description: The unique identifier of the registration to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRegistrationRequest'
      responses:
        '200':
          description: Registration updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RegistrationResponse'
                  message:
                    type: string
                    example: Successfully updated registration.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a registration
      description: Delete a registration. Only registrations with validation_status of PENDING, INVALID, or VALIDATION_IN_PROGRESS can be deleted. VALID registrations cannot be deleted - use close or archive instead.
      operationId: deleteRegistration
      tags:
        - Registrations
      parameters:
        - in: path
          required: true
          name: registration_id
          schema:
            type: string
            format: uuid
          description: The unique identifier of the registration to delete.
      responses:
        '204':
          description: Registration deleted successfully
        '400':
          description: Bad request - cannot delete VALID registrations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Registration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /registrations/{registration_id}/request-validation:
    post:
      summary: Request validation
      description: Submit a registration for validation by the Commenda team. Ensure all required fields (tax_registration_id, frequency, credentials) are set before calling this endpoint.
      operationId: requestRegistrationValidation
      tags:
        - Registrations
      parameters:
        - in: path
          required: true
          name: registration_id
          schema:
            type: string
            format: uuid
          description: The unique identifier of the registration to validate.
      responses:
        '200':
          description: Validation request submitted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RegistrationResponse'
                  message:
                    type: string
                    example: Successfully started validation process.
        '400':
          description: Bad request - missing required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /registrations/{registration_id}/archive:
    post:
      summary: Archive a registration
      description: Archive a registration to stop tax calculations and hide from default list views. Archived registrations are completely excluded from tax processing. Use include_archived=true when listing to see archived registrations.
      operationId: archiveRegistration
      tags:
        - Registrations
      parameters:
        - in: path
          required: true
          name: registration_id
          schema:
            type: string
            format: uuid
          description: The unique identifier of the registration to archive.
      responses:
        '200':
          description: Registration archived successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RegistrationResponse'
                  message:
                    type: string
                    example: Successfully archived registration.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /registrations/{registration_id}/close:
    post:
      summary: Close a registration
      description: Close a registration when you stop selling in a jurisdiction. The registration remains active for tax calculations within its date range (effective_start_date to effective_end_date). Use this when you have historical obligations to preserve.
      operationId: closeRegistration
      tags:
        - Registrations
      parameters:
        - in: path
          required: true
          name: registration_id
          schema:
            type: string
            format: uuid
          description: The unique identifier of the registration to close.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloseRegistrationRequest'
      responses:
        '200':
          description: Registration closed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RegistrationResponse'
                  message:
                    type: string
                    example: Successfully closed registration.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /registrations/content/available-jurisdictions:
    post:
      summary: List available jurisdictions
      description: Discover jurisdictions where you can create registrations. Use filters to narrow down by country, state, or tax type. Results are paginated using cursor-based pagination.
      operationId: listAvailableJurisdictions
      tags:
        - Registration Content
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JurisdictionsRequest'
      responses:
        '200':
          description: Jurisdictions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/JurisdictionsResponse'
                  message:
                    type: string
                    example: Successfully fetched jurisdictions.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /registrations/content/registration-input-options:
    post:
      summary: Get registration options
      description: Get available tax types, frequencies, and registration_content_ids for specific jurisdictions. The registration_content_id is required when creating a registration.
      operationId: getRegistrationInputOptions
      tags:
        - Registration Content
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OptionsRequest'
      responses:
        '200':
          description: Options retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OptionsResponse'
                  message:
                    type: string
                    example: Successfully fetched registration options.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /registrations/content/portal-fields:
    post:
      summary: Get portal credential fields
      description: Get the credential fields required for a specific registration content. These fields define what information you need to collect for automated tax filing.
      operationId: getPortalFields
      tags:
        - Registration Content
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortalFieldsRequest'
      responses:
        '200':
          description: Portal fields retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PortalFieldsResponse'
                  message:
                    type: string
                    example: Successfully fetched portal fields.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /calculate:
    post:
      summary: Calculate sales tax for a transaction
      operationId: calculateSalesTax
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxCalculationRequest'
      responses:
        '200':
          description: Successful tax calculation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TaxCalculationResponse'
                  message:
                    type: string
                    example: Successfully calculated tax.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /calculate-customs-duty:
    post:
      summary: Calculate customs duty for a transaction
      operationId: calculateCustomsDuty
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomsDutyCalculationRequest'
      responses:
        '200':
          description: Successful customs duty calculation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      customs_rate:
                        type: number
                        description: Numeric value representing the customs duty rate as a percentage (e.g., 6.25 for 6.25%).
                        example: 10.25
                      customs_duty_amount:
                        type: number
                        example: 1.03
                        description: Numeric value representing the total amount of sales tax to be remitted for this particular line item.
                      customs_duty_currency:
                        $ref: '#/components/schemas/Currency'
                        description: ISO 4217 alpha-3 currency code for the customs duty amount.
                  message:
                    type: string
                    example: Successfully calculated tax.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /address-requirements:
    get:
      summary: Get address requirements for a country
      description: Returns the minimum address field requirements for a given country. Use this to determine which address fields are required, optional, or ignored when submitting addresses for tax calculations and transactions.
      operationId: getAddressRequirements
      parameters:
        - name: country
          in: query
          description: A valid 2-letter ISO 3166-1 alpha-2 country code (e.g., US, CA, GB).
          required: true
          schema:
            type: string
            example: US
      responses:
        '200':
          description: Address requirements for the specified country
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AddressRequirementsResponse'
                  message:
                    type: string
                    example: Successfully retrieved address requirements.
        '400':
          description: Bad request — missing or invalid country parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No address requirements found for the specified country
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /transactions:
    post:
      summary: Create a transaction
      description: Submit a completed transaction for processing and filing
      operationId: submitTransaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaxTransactionRequest'
      responses:
        '200':
          description: Transaction creation response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TaxTransactionResponse'
                  message:
                    type: string
                    example: Successfully created transaction.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: List transactions
      description: List all transactions that match this query
      operationId: listTransactions
      parameters:
        - name: corporation_id
          in: query
          description: The unique identifier of the corporation for which to retrieve data.
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: Cursor for pagination
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Number of items to return per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: type
          in: query
          description: Filter by a single transaction type. Superseded by `types` if both are provided.
          required: false
          schema:
            $ref: '#/components/schemas/transaction_type'
        - name: types
          in: query
          description: |-
            Filter by one or more transaction types. Takes priority over `type` when both are provided.
            If neither `types` nor `type` is specified, defaults to `[SALE, REFUND, RETURN]` — PURCHASE and PURCHASE_REFUND are excluded unless explicitly requested.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/transaction_type'
      responses:
        '200':
          description: List of transactions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      transactions:
                        type: array
                        items:
                          $ref: '#/components/schemas/TaxTransactionResponse'
                      cursor:
                        type: string
                        description: Pagination cursor for the next set of results
                  message:
                    type: string
                    example: Successfully fetched transactions.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /transactions/{id}:
    get:
      summary: Get one transaction
      description: Retrieve one transaction by its identifier
      operationId: getTransaction
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of the transaction to fetch.
      responses:
        '200':
          description: Transaction fetch response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TaxTransactionResponse'
                  message:
                    type: string
                    example: Successfully fetched transaction.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a transaction
      description: Deletes a transaction by its identifier
      operationId: deleteTransaction
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of the transaction to delete.
      responses:
        '204':
          description: Transaction successfully deleted
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /transactions/refund-transactions/{parent-transaction-id}:
    post:
      summary: Create a return transaction
      description: |-
        Create a refund transaction linked to an existing invoice. The parent transaction can be a SALE or PURCHASE.
        When the parent is a SALE, the refund type is RETURN. When the parent is a PURCHASE, the refund type is automatically set to PURCHASE_REFUND.
        The resulting transaction will be properly linked to the original transaction.
      operationId: refundTransaction
      parameters:
        - in: path
          name: parent-transaction-id
          required: true
          schema:
            type: string
          description: The unique identifier of the SALE or PURCHASE transaction to generate a return for.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRefundRequest'
      responses:
        '200':
          description: Transaction creation response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The unique identifier for the refund transaction.
                        example: 2535af08-a139-4d0c-9827-1651e46dfbcf
                  message:
                    type: string
                    example: Successfully created refund transaction.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /transactions/bulk:
    post:
      summary: Bulk submit transactions
      description: |-
        Submit a file of completed transactions for processing.
        The CSV file must include required fields for SALE, RETURN, and PURCHASE transactions.
        For RETURN and PURCHASE transactions, all line items must have negative total amounts. RETURN transactions should include parent_invoice_id when available.
      operationId: submitBulkTransactions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The CSV file to upload.
                corporation_id:
                  type: string
                  description: The unique identifier for a corporation associated with this file.
      responses:
        '200':
          description: Transaction creation response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BulkTransactionMetadata'
                  message:
                    type: string
                    example: Successfully uploaded transactions.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /nexus:
    get:
      summary: Get registration threshold exposure
      description: Get registration threshold exposure for a corporation. By default, returns US-state-level data. Pass `v2=true` to get global jurisdiction-level data covering US, Canada, UK, and EU jurisdictions, including support for multiple exposure rules per jurisdiction (for example, EU Union OSS, Non-Union OSS, and IOSS).
      operationId: getNexusDetails
      parameters:
        - name: corporation_id
          in: query
          description: The unique identifier for the corporation to retrieve registration threshold data for.
          required: true
          schema:
            type: string
        - name: v2
          in: query
          description: Set to `true` to use the global registration threshold engine. When enabled, the response uses a `jurisdictions` array with expanded fields including `jurisdiction_id`, `exposure_type`, `exposure_rule_id`, `subdivision`, and `currency`. When omitted or `false`, the legacy response format with a `states` array is returned.
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
      responses:
        '200':
          description: Registration threshold exposure data
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    title: Default response
                    description: Returned when `v2` is not set or `false`.
                    properties:
                      data:
                        $ref: '#/components/schemas/NexusResponse'
                      message:
                        type: string
                        example: Successfully fetched nexus.
                  - type: object
                    title: V2 response
                    description: Returned when `v2=true`.
                    properties:
                      data:
                        $ref: '#/components/schemas/NexusV2Response'
                      message:
                        type: string
                        example: Successfully fetched nexus.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /exposure/sync:
    post:
      summary: Sync registration threshold exposure
      description: |-
        Trigger an on-demand recompute of registration threshold exposure for a corporation. The exposure engine evaluates the corporation's transactions against jurisdiction-level exposure rules and updates the cached breached set used by `GET /nexus?v2=true`.

        As part of every successful run, the engine emits an `INDIRECT_TAX.EXPOSURE.COMPUTED` webhook containing the corporation's full current set of exposed jurisdictions (see [Topics and Events](/engine/indirect-tax/webhooks/event)). Use this endpoint when you need fresh exposure data without waiting for the daily background recompute — for example, immediately after ingesting a backfill of historical transactions, or after a registration is created or archived.
      operationId: syncExposure
      parameters:
        - name: corporation_id
          in: query
          description: The unique identifier for the corporation to recompute exposure for.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Exposure recomputed successfully. The `INDIRECT_TAX.EXPOSURE.COMPUTED` webhook has been dispatched to any subscribers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Exposure engine ran; IndirectTaxExposureComputed webhook dispatched.
        '400':
          description: Missing or invalid `corporation_id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Caller is not authorized to access the corporation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Exposure engine failed to run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /filings:
    get:
      summary: List filings
      description: List state and local sales tax filings for a corporation, filtered by query. Pass `v2=true` to use the V2 filings path, which supports additional filters (such as `registration_tax_type_id`, `jurisdiction_ids`, `filing_statuses`, `filing_frequencies`, `from_due_date`, and `to_due_date`) and opt-in expansions via the `extend` query parameter.
      operationId: listFilings
      parameters:
        - name: corporation_id
          in: query
          description: The unique identifier of the corporation for which to retrieve data.
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: Cursor for pagination
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Number of items to return per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: v2
          in: query
          description: Set to `true` to use the V2 filings path, which returns V2 content metadata (such as `registration_tax_type_id`, `jurisdiction_name`, `jurisdiction_type`, and `filing_content_id`) and enables the additional filters and `extend` parameter documented below. When omitted or `false`, the legacy filings response is returned.
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: extend
          in: query
          description: Opt-in expansion for the V2 path (requires `v2=true`). Comma-separated list of expansion keys. The only supported value today is `filing_contribution`, which inlines the computed tax-return box contributions on each filing via a `contributions` array. When the parameter is omitted, the `contributions` field is not included in the response. Unknown values return a `400`.
          required: false
          schema:
            type: string
            example: filing_contribution
        - name: from_due_date
          in: query
          description: V2 path only (`v2=true`). ISO 8601 date string. Returns only filings whose due date is on or after this value.
          required: false
          schema:
            type: string
            format: date
        - name: to_due_date
          in: query
          description: V2 path only (`v2=true`). ISO 8601 date string. Returns only filings whose due date is on or before this value.
          required: false
          schema:
            type: string
            format: date
        - name: registration_tax_type_id
          in: query
          description: V2 path only (`v2=true`). Filter by V2 registration tax type content identifier (e.g., `REG_STATE_CEN_06_RST`).
          required: false
          schema:
            type: string
        - name: jurisdiction_ids
          in: query
          description: V2 path only (`v2=true`). Comma-separated list of Commenda jurisdiction identifiers to filter by. Maximum 100 values.
          required: false
          schema:
            type: string
            example: COUNTRY_DE_3018,STATE_CEN_06
        - name: filing_statuses
          in: query
          description: V2 path only (`v2=true`). Comma-separated list of filing statuses to filter by. Maximum 100 values.
          required: false
          schema:
            type: string
        - name: filing_frequencies
          in: query
          description: V2 path only (`v2=true`). Comma-separated list of filing frequencies to filter by. Maximum 100 values.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Filing info for all states
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      filings:
                        type: array
                        items:
                          $ref: '#/components/schemas/FilingsForGetAll'
                      cursor:
                        type: string
                        description: Pagination cursor for the next set of results
                  message:
                    type: string
                    example: Successfully fetched filings.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /filings/{id}:
    get:
      summary: Get one filing
      description: Retrieve one filing by its id
      operationId: getFiling
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of the transaction to fetch.
      responses:
        '200':
          description: Transaction fetch response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/FilingsGet'
                  message:
                    type: string
                    example: Successfully fetched filing.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Filing not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /filings/{id}/contributions:
    get:
      summary: List filing contributions
      description: Retrieve the computed tax box values (contributions) for a specific filing. Each contribution represents a value that maps to a box on a tax return form, such as taxable sales or tax due. Contributions are ordered by box order, then by jurisdiction for multi-jurisdiction filings (e.g., EU OSS/IOSS).
      operationId: listFilingContributions
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: The unique identifier of the filing to retrieve contributions for.
      responses:
        '200':
          description: Filing contributions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/FilingContributionsResponse'
                  message:
                    type: string
                    example: Successfully fetched filing contributions.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Filing not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /filings/liability-report:
    post:
      summary: Get liability report
      description: Returns per-filing liability snapshots for a list of filing IDs (max 100). Each entry's `breakdown` object is populated for US and Canadian filings, where liability values live on the filing row itself, and `null` for VAT filings (UK and EU country VAT, Union OSS, Non-Union OSS, IOSS) — fetch the box-level VAT detail for those via `POST /filings/contributions`.
      operationId: getLiabilityReport
      tags:
        - Filings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetLiabilityReportRequest'
      responses:
        '200':
          description: Liability report built successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/GetLiabilityReportResponse'
                  message:
                    type: string
                    example: Successfully built liability report.
        '400':
          description: Bad request — invalid body or filing not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Caller is not authorized to access one or more filings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /filings/contributions:
    post:
      summary: Get filing contributions for a batch of filings
      description: Multi-filing analog of `GET /filings/{id}/contributions`. Returns per-filing contribution boxes for a list of filing IDs (max 100). Each entry's `contributions` array is non-null for VAT filings (UK/EU country VAT and OSS/IOSS variants) — possibly empty if the engine has not computed boxes yet — and `null` for US and Canadian filings whose liability lives on the filing row itself.
      operationId: getFilingContributionsBatch
      tags:
        - Filings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetFilingContributionsBatchRequest'
      responses:
        '200':
          description: Filing contributions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/GetFilingContributionsBatchResponse'
                  message:
                    type: string
                    example: Successfully fetched filing contributions.
        '400':
          description: Bad request — invalid body or filing not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Caller is not authorized to access one or more filings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /filings/liability-report/export:
    post:
      summary: Export liability report as zipped CSVs
      description: Queues an asynchronous export job that produces one CSV per filing, bundles them into a zip, uploads the zip to storage, and emails a signed download link to `delivery_recipients` when complete. All filings in a single request must belong to the same corporation (max 100 filings). Poll job status via the jobs endpoint, filtering by `entity=FILING` and `operation=EXPORT_INDIRECT_TAX_FILINGS_LIABILITY_REPORT`.
      operationId: exportLiabilityReport
      tags:
        - Filings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportLiabilityReportRequest'
      responses:
        '200':
          description: Export job queued successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ExportLiabilityReportResponse'
                  message:
                    type: string
                    example: Successfully queued liability report export.
        '400':
          description: Bad request — invalid body, filing not found, or filings span multiple corporations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Caller is not authorized to access one or more filings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /customers:
    post:
      summary: Create a customer
      description: Create a customer to track their exemption certificates and default values for their addresses.
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerCreate'
      responses:
        '200':
          description: Information about the created customer
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CustomerInfo'
                  message:
                    type: string
                    example: Successfully created customer.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: List customers
      description: List customers associated with a corporation.
      operationId: listCustomers
      parameters:
        - name: corporation_id
          in: query
          description: The unique identifier for a corporation used to filter the relevant customer base.
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: Cursor for pagination
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Number of items to return per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: List of customers associated with the requesting corporation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/GetAllCustomersByCorporation'
                  message:
                    type: string
                    example: Successfully fetched customers.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /customers/{id}:
    get:
      summary: Get customer
      description: Get detailed information about a specific customer, including exemption certificates.
      operationId: getCustomer
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of the customer to fetch.
      responses:
        '200':
          description: Detailed information about a specific customer
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CustomerExtended'
                  message:
                    type: string
                    example: Successfully fetched customer.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Update a customer
      description: Update a customer, including their addresses and exemption certificates.
      operationId: updateCustomer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerUpdate'
      responses:
        '200':
          description: Information about the customer after the update
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Successfully updated customer.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of the transaction to update
    delete:
      summary: Delete a customer
      description: Deletes a customer by its id
      operationId: deleteCustomer
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of the customer to delete.
      responses:
        '204':
          description: Customer successfully deleted
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /exemption-certificates:
    get:
      summary: List all exemption certificates.
      description: Get a list of all exemption certificates.
      operationId: listAllExemptionCertificates
      parameters:
        - in: query
          name: customer_id
          required: true
          schema:
            type: string
          description: The unique identifier of the customer whose exemption certificate you want to fetch.
        - name: cursor
          in: query
          description: Cursor for pagination
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Number of items to return per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: Sales tax exemption certificate response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      exemption_certificates:
                        type: array
                        items:
                          $ref: '#/components/schemas/ExemptionCertificateResponse'
                      cursor:
                        type: string
                        description: Pagination cursor for the next set of results.
                      total_exemptions:
                        type: number
                        description: Total number of exemption certificates.
                  message:
                    type: string
                    example: Successfully fetched exemption certificates.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create an exemption certificate
      description: Create an exemption certificate for a customer
      operationId: createExemptionCertificate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExemptionCertificateRequest'
      responses:
        '200':
          description: Successful exemption certificate creation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ExemptionCertificateResponse'
                  message:
                    type: string
                    example: Successfully created exemption certificate.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /exemption-certificates/{id}:
    get:
      summary: Get exemption certificate.
      description: Get a specific exemption certificate by id.
      operationId: getExemptionCertificate
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of the exemption certificate to fetch.
      responses:
        '200':
          description: Get one exemption certificate response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ExemptionCertificateResponse'
                  message:
                    type: string
                    example: Successfully fetched exemption certificate.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteExemptionCertificate
      summary: Delete exemption certificate
      description: Delete an exemption certificate. This does not delete the associated file.
      parameters:
        - in: path
          required: true
          name: id
          schema:
            type: string
          description: The unique identifier of the exemption certificate to delete.
      responses:
        '204':
          description: Exemption certificate successfully deleted
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Exemption certificate not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /files:
    get:
      summary: List files
      description: List files for one seller
      operationId: listFiles
      parameters:
        - name: corporation_id
          in: query
          description: The unique identifier of the corporation for which to retrieve data.
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: Cursor for pagination
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Number of items to return per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: List of files
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      files:
                        type: array
                        items:
                          $ref: '#/components/schemas/FileInfo'
                      cursor:
                        type: string
                        description: Pagination cursor for the next set of results
                  message:
                    type: string
                    example: Successfully fetched files.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create file
      description: Upload a new file to Commenda's server
      operationId: createFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload
                corporation_id:
                  type: string
                  description: The unique identifier for a corporation associated with this file.
      responses:
        '200':
          description: Information about the created file
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/FileInfo'
                  message:
                    type: string
                    example: Successfully created file.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /files/{id}:
    get:
      summary: Get one file
      description: Retrieve one file by its id, along with a signed URL to download it
      operationId: getFile
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of the file to fetch.
      responses:
        '200':
          description: File along with a download URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    allOf:
                      - $ref: '#/components/schemas/FileInfo'
                      - type: object
                        properties:
                          signed_url:
                            type: string
                            description: Signed URL to download the file. Expires after 20 minutes.
                            example: https://bucket-name.s3.amazonaws.com/example.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20240912%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20240912T120000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
                  message:
                    type: string
                    example: Successfully fetched file.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a file
      description: Deletes a file by its id
      operationId: deleteFile
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of the file to delete.
      responses:
        '204':
          description: File successfully deleted
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /public/companies:
    get:
      summary: List companies
      description: List companies visible to the authenticated legacy affiliate API key.
      operationId: listAffiliateCompanies
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      responses:
        '200':
          description: Companies retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliateListCompaniesResponse'
        '401':
          description: Missing or invalid affiliate API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /public/company:
    post:
      summary: Create a company
      description: Create a new company container for legacy affiliate workflows.
      operationId: createAffiliateCompany
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AffiliateCreateCompanyRequest'
      responses:
        '201':
          description: Company created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliateCreateCompanyResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid affiliate API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /public/services:
    post:
      summary: Create an incorporation service for a company
      description: Start a supported incorporation service for an affiliate-owned company and return the linked payment intent id.
      operationId: createAffiliateService
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AffiliateCreateServiceRequest'
      responses:
        '201':
          description: Service and payment intent created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliateCreateServiceResponse'
        '400':
          description: Unsupported service type or company not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid affiliate API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Company is not accessible to the affiliate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/customers:
    post:
      summary: Create a customer
      description: Create a customer record that scopes later Partner API calls.
      operationId: createPartnerCustomer
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerCreateCustomerRequest'
      responses:
        '201':
          description: Customer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCreateCustomerResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
    get:
      summary: List customers
      description: List customers visible to the authenticated partner API key.
      operationId: listPartnerCustomers
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      responses:
        '200':
          description: Customers retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerListCustomersResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/incorporation/jurisdiction-catalog:
    get:
      summary: List supported incorporation jurisdictions
      description: Retrieve the informational catalog of supported incorporation countries and country-specific options. This endpoint helps clients render valid choices, but the create endpoint remains the source of truth for validation.
      operationId: getPartnerIncorporationJurisdictionCatalog
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      responses:
        '200':
          description: Jurisdiction catalog retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerJurisdictionCatalogResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/incorporation/requirements:
    get:
      summary: Get incorporation requirements
      description: Retrieve the current requirements schema for a selected incorporation jurisdiction and type. This endpoint is informational; intake updates are validated against the current server-side incorporation requirements.
      operationId: getPartnerIncorporationRequirements
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: country
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/PartnerIncorporationCountry'
          description: Incorporation country.
          example: SG
        - name: countryOptions
          in: query
          required: true
          style: deepObject
          explode: true
          schema:
            $ref: '#/components/schemas/PartnerIncorporationCountryOptions'
          description: Country-specific options using deep-object query syntax, for example `countryOptions[corporationType]=PRIVATE_LIMITED_COMPANY`.
      responses:
        '200':
          description: Requirements retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerRequirementsResponse'
        '400':
          description: Unsupported or malformed incorporation selection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Requirements are not available for the requested selection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/incorporation/status-workflow:
    get:
      summary: Get incorporation status workflow
      description: Retrieve the public status workflow for a selected incorporation jurisdiction and type. The response is derived from the active workflow template and includes ordered public stages.
      operationId: getPartnerIncorporationStatusWorkflow
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: country
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/PartnerIncorporationCountry'
          description: Incorporation country.
          example: SG
        - name: countryOptions
          in: query
          required: true
          style: deepObject
          explode: true
          schema:
            $ref: '#/components/schemas/PartnerIncorporationCountryOptions'
          description: Country-specific options using deep-object query syntax, for example `countryOptions[corporationType]=PRIVATE_LIMITED_COMPANY`.
      responses:
        '200':
          description: Status workflow retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationStatusWorkflowResponse'
        '400':
          description: Unsupported or malformed incorporation selection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Status workflow is not available or active for the requested selection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/incorporation/customers/{customerId}/incorporations:
    post:
      summary: Create an incorporation
      description: Begin an incorporation for one of your customers.
      operationId: createPartnerIncorporation
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Customer that should own the incorporation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerCreateCustomerScopedIncorporationRequest'
            examples:
              singaporePrivateLimited:
                summary: Singapore private limited company
                value:
                  country: SG
                  countryOptions:
                    corporationType: PRIVATE_LIMITED_COMPANY
      responses:
        '201':
          description: Incorporation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationResponse'
        '400':
          description: Unsupported country or invalid country options
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Customer is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
    get:
      summary: List incorporations for a customer
      description: List incorporations visible to the authenticated partner for a single customer.
      operationId: listPartnerIncorporations
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Customer whose incorporations should be listed.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
          description: Maximum number of incorporations to return.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Number of matching incorporations to skip.
      responses:
        '200':
          description: Incorporations retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationListResponse'
        '400':
          description: Invalid pagination parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Customer is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/incorporation/{incorporationId}:
    get:
      summary: Get an incorporation
      description: Retrieve one incorporation visible to the authenticated partner. Use this direct route for intake state reads.
      operationId: getPartnerIncorporationById
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
      responses:
        '200':
          description: Incorporation retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Incorporation is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Incorporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/incorporation/{incorporationId}/status:
    get:
      summary: Get incorporation status
      description: Retrieve the current public status projection for an incorporation, including top-level status, ordered stages, and active blocking issue ids.
      operationId: getPartnerIncorporationStatus
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
      responses:
        '200':
          description: Incorporation status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationStatusResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Incorporation is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Incorporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/incorporation/{incorporationId}/validation:
    get:
      summary: Get incorporation validation
      description: Refresh and retrieve validation for the full incorporation, including intake fields, participants, ownership totals, and participant documents.
      operationId: getPartnerIncorporationValidation
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
      responses:
        '200':
          description: Incorporation validation retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationValidationResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Incorporation is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Incorporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/incorporation/{incorporationId}/intake:
    patch:
      summary: Update incorporation intake
      description: Partially update incorporation intake details. Each write returns the updated intake state and incorporation validation summary.
      operationId: updatePartnerIncorporationIntake
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerUpdateIntakeRequest'
      responses:
        '200':
          description: Intake updated and validated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationIntakeResponse'
        '400':
          description: Malformed intake payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Incorporation is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Incorporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/incorporation/{incorporationId}/submit:
    post:
      summary: Submit an incorporation
      description: Submit a currently complete incorporation for Commenda review. The server refreshes validation before accepting the submit request. `incorporationValidation.isComplete` means eligible to submit; `SUBMITTED` or `IN_PROGRESS` is returned only after this endpoint succeeds.
      operationId: submitPartnerIncorporation
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
      responses:
        '200':
          description: Incorporation submitted for review
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationResponse'
        '400':
          description: Incorporation is incomplete or has invalid requirements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationSubmitError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Incorporation is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Incorporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/incorporation/{incorporationId}/participants:
    get:
      summary: List incorporation participants
      description: List reusable Commenda OS people or business entities registered as participants in this incorporation, including their roles and linked documents.
      operationId: listPartnerIncorporationParticipants
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
      responses:
        '200':
          description: Participants retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationParticipantsResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Incorporation is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Incorporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
    post:
      summary: Register an incorporation participant
      description: Register an existing Commenda OS person or business entity as a participant in an incorporation, including details about their role.
      operationId: registerPartnerIncorporationParticipant
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerRegisterParticipantRequest'
      responses:
        '201':
          description: Participant registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationParticipantMutationResponse'
        '400':
          description: Malformed participant registration payload, invalid participant/resource/role combination, missing shareholder ownership percentage, or shareholder ownership exceeding the selected requirements total
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Incorporation is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Incorporation or referenced Commenda OS resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/incorporation/{incorporationId}/participants/{participantId}:
    patch:
      summary: Update an incorporation participant
      description: Partially update an existing incorporation participant. Use this endpoint to correct director/shareholder roles, shareholder ownership percentages, or to re-point the participant at a different Commenda OS person or business entity. Provide `roles`, `resource`, or both. The underlying Commenda OS resource is not modified by this endpoint.
      operationId: updatePartnerIncorporationParticipant
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
        - name: participantId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation-specific participant identifier returned by register, list, or read endpoints.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerPatchParticipantRequest'
      responses:
        '200':
          description: Participant updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationParticipantMutationResponse'
        '400':
          description: Malformed participant update payload, neither `roles` nor `resource` provided, invalid role combination, missing shareholder ownership percentage, shareholder ownership exceeding the selected requirements total, or the supplied resource is already registered as another participant on this incorporation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Incorporation is not accessible to the partner, or the supplied resource is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Incorporation or participant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
    delete:
      summary: Remove an incorporation participant
      description: Remove an incorporation-specific participant registration and its linked participant documents. This does not delete the underlying Commenda OS person or business entity referenced by the participant.
      operationId: removePartnerIncorporationParticipant
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
        - name: participantId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation-specific participant identifier returned by register, list, or read endpoints.
      responses:
        '200':
          description: Participant removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationParticipantRemovalResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Incorporation is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Incorporation or participant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/incorporation/{incorporationId}/participants/{participantId}/documents/{documentKind}:
    put:
      summary: Upsert a participant document
      description: Assign a customer-scoped Commenda file to one participant document slot. This request creates or replaces the typed participant document in one transaction without changing the reusable file. Repeating the request with the same fileId is safe.
      operationId: upsertPartnerIncorporationParticipantDocument
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
        - name: participantId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation-specific participant identifier returned by register, list, or read endpoints.
        - name: documentKind
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/PartnerIncorporationDocumentKind'
          description: Typed document requirement to satisfy for this participant.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerUpsertParticipantDocumentRequest'
      responses:
        '200':
          description: Participant document upserted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationParticipantDocumentMutationResponse'
        '400':
          description: Malformed participant document payload, incompatible file type, or document kind not required for this participant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Incorporation is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Incorporation, participant, or file not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /public/payment-intents:
    get:
      summary: List payment intents for an affiliate
      description: List payment intents visible to the authenticated affiliate, optionally filtered by status or company.
      operationId: listAffiliatePaymentIntents
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/AffiliatePaymentIntentStatus'
        - name: companyId
          in: query
          required: false
          schema:
            type: integer
          description: Filter payment intents to a single company.
      responses:
        '200':
          description: Payment intents retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliateListPaymentIntentsResponse'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid affiliate API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /public/payment-intents/{paymentIntentId}:
    get:
      summary: Get one payment intent
      description: Retrieve a single payment intent and its linked service request handoff URL.
      operationId: getAffiliatePaymentIntent
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: paymentIntentId
          in: path
          required: true
          schema:
            type: string
          description: Payment intent identifier returned by `POST /public/services`.
      responses:
        '200':
          description: Payment intent retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePaymentIntent'
        '401':
          description: Missing or invalid affiliate API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Payment intent is not accessible to the affiliate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Payment intent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /public/payment-intents/{paymentIntentId}/service/status:
    get:
      summary: Get service status for a payment intent
      description: Retrieve the linked service request summary and task-group level status for a payment intent.
      operationId: getAffiliatePaymentIntentServiceStatus
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: paymentIntentId
          in: path
          required: true
          schema:
            type: string
          description: Payment intent identifier returned by `POST /public/services`.
      responses:
        '200':
          description: Service status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePaymentIntentServiceStatusResponse'
        '401':
          description: Missing or invalid affiliate API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Service request is not accessible to the affiliate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Payment intent or linked service request not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /public/documents:
    get:
      summary: List legacy document slots for a company
      description: Deprecated. Use the Commenda OS documents endpoints instead.
      operationId: listAffiliateDocuments
      deprecated: true
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: companyId
          in: query
          required: true
          schema:
            type: integer
          description: Company whose corporation documents should be listed.
        - name: documentType
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/AffiliateDocumentCategory'
        - name: documentSubType
          in: query
          required: false
          schema:
            type: string
          description: Filter by Commenda legacy document subtype.
      responses:
        '200':
          description: Document slots retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliateListDocumentsResponse'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid affiliate API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Company is not accessible to the affiliate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /public/file/{fileId}:
    get:
      summary: Get a file download URL
      description: Return a temporary download URL for a file the authenticated affiliate can access.
      operationId: getAffiliateFileSignedUrl
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: fileId
          in: path
          required: true
          schema:
            type: integer
          description: File identifier returned by Commenda document APIs.
      responses:
        '200':
          description: Signed URL created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliateFileSignedUrlResponse'
        '401':
          description: Missing or invalid affiliate API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: File is not accessible to the affiliate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: File not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/commenda-os/customers/{customerId}/business-entities:
    post:
      summary: Create a business entity
      description: Create a reusable Commenda OS business entity for one of your customers. Use the returned `businessEntity.id` as a `BUSINESS_ENTITY` resource id when registering corporate incorporation participants.
      operationId: createPartnerCommendaOsBusinessEntity
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommendaOsBusinessEntityCreateRequest'
            examples:
              singaporeCorporateShareholder:
                value:
                  incorporationCountry: SG
                  legalName: Acme Holdings Pte. Ltd.
                  jurisdiction: JUR_SG__GENERAL
                  corporationType: PteLtd
                  formationDate: '2020-03-15'
                  isIncorporationInProgress: false
      responses:
        '201':
          description: Business entity created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsBusinessEntityResponse'
        '400':
          description: Malformed business entity create payload or unsupported country/jurisdiction/corporation type combination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
    get:
      summary: List business entities for a customer
      description: List the business entities for one of your customers.
      operationId: listPartnerCommendaOsBusinessEntities
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
      responses:
        '200':
          description: Business entities retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsBusinessEntityListResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/commenda-os/customers/{customerId}/business-entities/{businessEntityId}:
    patch:
      summary: Update a business entity
      description: Partially update a reusable Commenda OS business entity. Omitted fields are left unchanged. Use this endpoint to complete corporate shareholder details before registering or validating incorporation participants.
      operationId: updatePartnerCommendaOsBusinessEntity
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
        - name: businessEntityId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda business-entity identifier for the specified customer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommendaOsBusinessEntityUpdateRequest'
            examples:
              updateBusinessEntity:
                value:
                  legalName: Acme Holdings Pte. Ltd.
                  businessDescription: Investment holding customer.
                  publicFacingWebsiteUrl: https://acme.example
      responses:
        '200':
          description: Business entity updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsBusinessEntityResponse'
        '400':
          description: Malformed business entity update payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Business entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
    get:
      summary: Get a business entity for a customer
      description: Retrieve a single business entity for one of your customers.
      operationId: getPartnerCommendaOsBusinessEntity
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
        - name: businessEntityId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda business-entity identifier for the specified customer.
      responses:
        '200':
          description: Business entity retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsBusinessEntityResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Business entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/commenda-os/customers/{customerId}/business-entities/{businessEntityId}/locations:
    post:
      summary: Create a location
      description: Create a reusable Commenda OS location for a customer's business entity.
      operationId: createPartnerCommendaOsLocation
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
        - name: businessEntityId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda business-entity identifier for the specified customer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommendaOsLocationCreateRequest'
      responses:
        '201':
          description: Location created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsLocationResponse'
        '400':
          description: Invalid location payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Business entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
    get:
      summary: List locations for a business entity
      description: List locations attached to a customer's business entity.
      operationId: listPartnerCommendaOsLocations
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
        - name: businessEntityId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda business-entity identifier for the specified customer.
      responses:
        '200':
          description: Locations retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsLocationsResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Business entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/commenda-os/customers/{customerId}/business-entities/{businessEntityId}/locations/{locationId}:
    get:
      summary: Get a location
      description: Retrieve a single location for a customer's business entity.
      operationId: getPartnerCommendaOsLocation
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
        - name: businessEntityId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda business-entity identifier for the specified customer.
        - name: locationId
          in: path
          required: true
          schema:
            type: string
          description: Commenda location identifier.
      responses:
        '200':
          description: Location retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsLocationResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Location not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
    patch:
      summary: Update a location
      description: Update a reusable Commenda OS location for a customer's business entity.
      operationId: updatePartnerCommendaOsLocation
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
        - name: businessEntityId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda business-entity identifier for the specified customer.
        - name: locationId
          in: path
          required: true
          schema:
            type: string
          description: Commenda location identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommendaOsLocationUpdateRequest'
      responses:
        '200':
          description: Location updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsLocationResponse'
        '400':
          description: Invalid location payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Location not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/commenda-os/customers/{customerId}/business-entities/{businessEntityId}/persons:
    get:
      summary: List persons for a business entity
      description: List people associated with a customer's business entity.
      operationId: listPartnerCommendaOsBusinessEntityPersons
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
        - name: businessEntityId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda business-entity identifier for the specified customer.
      responses:
        '200':
          description: Persons retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsBusinessEntityPersonsResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Business entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/commenda-os/customers/{customerId}/persons:
    get:
      summary: List persons for a customer
      description: List people for one of your customers across their business entities.
      operationId: listPartnerCommendaOsPersons
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
      responses:
        '200':
          description: Persons retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPersonsResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
    post:
      summary: Create a person
      description: Create a reusable Commenda OS person for one of your customers. Use the returned `person.id` as a `KEY_PERSON` resource id when registering incorporation participants. For Singapore residential address requirements, include `residentialAddress`.
      operationId: createPartnerCommendaOsPerson
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommendaOsPersonCreateRequest'
            examples:
              createPerson:
                value:
                  firstName: Jane
                  lastName: Founder
                  email: jane@acme.com
                  dateOfBirth: '1990-04-18'
                  countryOfCitizenship: SG
                  residentialAddress:
                    addressLine1: 1 Raffles Place
                    city: Singapore
                    postalCode: '048616'
                    country: SG
      responses:
        '201':
          description: Person created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPersonMutationResponse'
        '400':
          description: Malformed person create payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/commenda-os/customers/{customerId}/persons/{personId}:
    patch:
      summary: Update a person
      description: Partially update a reusable Commenda OS person. Omitted fields are left unchanged. For Singapore residential address requirements, include `residentialAddress`.
      operationId: updatePartnerCommendaOsPerson
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
        - name: personId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda OS person identifier for the specified customer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommendaOsPersonUpdateRequest'
            examples:
              updatePerson:
                value:
                  firstName: Jane
                  lastName: Founder
                  email: jane@acme.com
                  dateOfBirth: '1990-04-18'
                  countryOfCitizenship: SG
                  residentialAddress:
                    addressLine1: 1 Raffles Place
                    city: Singapore
                    postalCode: '048616'
                    country: SG
      responses:
        '200':
          description: Person updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPersonMutationResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Person not found for this customer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/commenda-os/customers/{customerId}/business-entities/{businessEntityId}/government-identifiers:
    get:
      summary: List government identifiers
      description: List government identifiers attached to a customer's business entity.
      operationId: listPartnerCommendaOsGovernmentIdentifiers
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
        - name: businessEntityId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda business-entity identifier for the specified customer.
      responses:
        '200':
          description: Government identifiers retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsGovernmentIdentifiersResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Business entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/commenda-os/customers/{customerId}/business-entities/{businessEntityId}/government-identifiers/{governmentIdentifierId}:
    get:
      summary: Get a government identifier
      description: Retrieve a single government identifier for a customer's business entity.
      operationId: getPartnerCommendaOsGovernmentIdentifier
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
        - name: businessEntityId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda business-entity identifier for the specified customer.
        - name: governmentIdentifierId
          in: path
          required: true
          schema:
            type: string
          description: Commenda government-identifier identifier.
      responses:
        '200':
          description: Government identifier retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsGovernmentIdentifierResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Business entity not found or government identifier not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/commenda-os/customers/{customerId}/files:
    post:
      summary: Upload a file
      description: Upload a file with multipart/form-data and receive a reusable fileId. Stores bytes only; does not link the file to any other resource. Use the returned fileId with a separate attach call to put the file to work.
      operationId: uploadPartnerCommendaOsCustomerFile
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CommendaOsCustomerFileUploadRequest'
      responses:
        '201':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsCustomerFileResponse'
        '400':
          description: Missing file part or malformed multipart body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Customer does not belong to this partner firm
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '413':
          description: Uploaded file exceeds the 100 MB per-request size limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '415':
          description: Detected MIME type of the uploaded file is not in the accepted list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/commenda-os/customers/{customerId}/business-entities/{businessEntityId}/documents:
    get:
      summary: List documents for a business entity
      description: List documents for a customer's business entity.
      operationId: listPartnerCommendaOsDocuments
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
        - name: businessEntityId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda business-entity identifier for the specified customer.
      responses:
        '200':
          description: Documents retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsDocumentsResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Business entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/commenda-os/customers/{customerId}/business-entities/{businessEntityId}/documents/supported:
    get:
      summary: List supported document types
      description: List the document types Commenda OS supports for a customer's business entity.
      operationId: listPartnerCommendaOsSupportedDocuments
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
        - name: businessEntityId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda business-entity identifier for the specified customer.
      responses:
        '200':
          description: Supported document types retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsSupportedDocumentsResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Business entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/commenda-os/customers/{customerId}/business-entities/{businessEntityId}/registrations:
    get:
      summary: List registrations for a business entity
      description: List registrations for a customer's business entity.
      operationId: listPartnerCommendaOsRegistrations
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
        - name: businessEntityId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda business-entity identifier for the specified customer.
      responses:
        '200':
          description: Registrations retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsRegistrationsResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Business entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/commenda-os/customers/{customerId}/business-entities/{businessEntityId}/registrations/{registrationId}:
    get:
      summary: Get a registration
      description: Retrieve a single registration for a customer's business entity.
      operationId: getPartnerCommendaOsRegistration
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
        - name: businessEntityId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda business-entity identifier for the specified customer.
        - name: registrationId
          in: path
          required: true
          schema:
            type: string
          description: Commenda registration identifier.
      responses:
        '200':
          description: Registration retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsRegistrationResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Business entity not found or registration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/commenda-os/customers/{customerId}/business-entities/{businessEntityId}/registrations/supported:
    get:
      summary: List supported registrations for a business entity
      description: List the registrations Commenda OS supports for a customer's business entity.
      operationId: listPartnerCommendaOsBusinessEntitySupportedRegistrations
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
        - name: businessEntityId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda business-entity identifier for the specified customer.
      responses:
        '200':
          description: Supported registrations retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsSupportedRegistrationsResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '404':
          description: Business entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/commenda-os/registrations/supported:
    get:
      summary: List supported registrations
      description: List the registrations Commenda OS supports globally.
      operationId: listPartnerCommendaOsSupportedRegistrations
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      responses:
        '200':
          description: Supported registrations retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsSupportedRegistrationsResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
  /partner/incorporation/{incorporationId}/issues:
    get:
      summary: List incorporation issues
      description: List partner-visible issues for an incorporation. Active issues are returned by default. Issues are read-only over the Partner API; fix the underlying intake, participant, or document data to resolve them.
      operationId: listPartnerIncorporationIssues
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/PartnerIncorporationIssueStatusFilter'
          description: Filter issues by status. Defaults to `ACTIVE`.
      responses:
        '200':
          description: Issues retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationIssuesResponse'
        '400':
          description: Unsupported status filter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Incorporation is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Incorporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/webhook-subscriptions:
    post:
      summary: Create webhook subscription
      description: Create a partner-level webhook subscription for incorporation issue events. The full signing secret is returned only in this create response.
      operationId: createPartnerWebhookSubscription
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerCreateWebhookSubscriptionRequest'
      responses:
        '201':
          description: Webhook subscription created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCreateWebhookSubscriptionResponse'
        '400':
          description: Malformed request or unsafe webhook URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
    get:
      summary: List webhook subscriptions
      description: List active webhook subscriptions for the authenticated partner. Responses include `secretPreview`, not the full signing secret.
      operationId: listPartnerWebhookSubscriptions
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      responses:
        '200':
          description: Webhook subscriptions retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerWebhookSubscriptionsResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
  /partner/webhook-subscriptions/{subscriptionId}:
    get:
      summary: Get webhook subscription
      description: Retrieve one active webhook subscription for the authenticated partner. Responses include `secretPreview`, not the full signing secret.
      operationId: getPartnerWebhookSubscription
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            type: string
          description: Webhook subscription identifier.
      responses:
        '200':
          description: Webhook subscription retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerWebhookSubscriptionResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Webhook subscription not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
    delete:
      summary: Delete webhook subscription
      description: Delete a webhook subscription for the authenticated partner. Deleted subscriptions stop receiving future webhook events.
      operationId: deletePartnerWebhookSubscription
      servers:
        - url: https://api.prod.commenda.io/api/v1
      security:
        - xApiKeyAuth: []
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            type: string
          description: Webhook subscription identifier.
      responses:
        '204':
          description: Webhook subscription deleted successfully
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Webhook subscription not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
components:
  schemas:
    GetWebhookResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for this webhook. You will need this if you need to update or delete this webhook.
          example: 2535af08-a139-4d0c-9827-1651e46dfbcf
        api_version:
          type: string
          description: The version of the API for which you registered the webhook. This will be 'v1.0' for now. This helps to maintain backward compatibility. If in newer versions the event payload is changed, your webhook will keep receiving the payload from the original api version.
          example: v1.0
        name:
          type: string
          description: Optional name to define the purpose of the webhook.
          example: handle_existing_registrations_validation_failure
        topics:
          type: array
          items:
            type: string
            enum:
              - REGISTRATIONS.EXISTING.VALIDATION_FAILED
              - REGISTRATIONS.EXISTING.VALIDATION_SUCCEEDED
          description: An array of topics to listen to. When any of these topics are triggered, the webhook will be pinged.
        url:
          type: string
          description: Your webhook url that will be hit once a topic is triggered. Only https:// urls will work.
          example: https://bruno-simon.com/
        status:
          type: string
          enum:
            - ENABLED
            - DISABLED
          description: If the webhook is active or not. If a webhook id disabled it won't be called when a topic is triggered.
        created_at:
          type: number
          description: Timestamp in UTC when this webhook was created.
          example: 1727284490
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: 'Specific Error type. Example: CLIENT_INVALID_REQUEST_BODY.'
              example: CLIENT_INVALID_REQUEST_BODY
            doc_url:
              type: string
              description: 'A link to the docs with details about this error. Example: https://sales-tax-docs.commenda.io/'
              example: https://sales-tax-docs.commenda.io/
            title:
              type: string
              description: 'A short title describing the error. Example: Missing query parameters.'
              example: Failed to validate the request body
            detail:
              type: string
              description: A json string with a description on how to fix the error. Example {"description":"Please pass in a valid corporation_id"}
            status:
              type: number
              description: 'The status code. It should be the same as the HTTP protocol status code. Example: 200'
              example: 400
            instance:
              type: string
              description: 'The relative path that was hit by the user. Example: /api/v1/corporations/1'
            Errors:
              type: array
              items:
                type: object
                properties:
                  details:
                    type: string
                    description: More details on how to solve this particular error.
                  pointer:
                    type: string
                    description: Relative reference to missing or invalid piece of passed information.
    CreateWebhookRequest:
      type: object
      required:
        - api_version
        - url
        - key
        - status
        - topics
      properties:
        api_version:
          type: string
          description: The version of the API for which you registered the webhook. This helps to maintain backward compatibility. If in newer versions the event payload is changed, your webhook will keep receiving the payload from this api version. This will be 'v1.0' for now and we will come up with more versions and a changelog later.
        name:
          type: string
          description: Optional name to define the purpose of the webhook.
        topics:
          type: array
          items:
            type: string
            enum:
              - REGISTRATIONS.EXISTING.VALIDATION_FAILED
              - REGISTRATIONS.EXISTING.VALIDATION_SUCCEEDED
          description: An array of topics to listen to. When any of these topics are triggered, the webhook will be pinged.
        url:
          type: string
          description: Your webhook url that will be hit once an event happens. Only HTTPS urls are allowed.
        key:
          type: string
          description: Secure string provided by the user. It will be used during HMCA process to keep the event payloads secure. Make sure to keep it safe as you will need it during validating event payloads. This key won't be returned back by any other endpoint.
        status:
          type: string
          enum:
            - ENABLED
            - DISABLED
          description: If the webhook is active or not. If a webhook is disabled it won't be called when a topic is triggered.
    CreateWebhookResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for this webhook. You will need this if you need to update or delete this webhook.
          example: 2535af08-a139-4d0c-9827-1651e46dfbcf
        api_version:
          type: string
          description: The version of the API for which you registered the webhook. This will be 'v1.0' for now. This helps to maintain backward compatibility. If in newer versions the event payload is changed, your webhook will keep receiving the payload from the original api version.
          example: v1.0
        name:
          type: string
          description: Optional name to define the purpose of the webhook.
          example: handle_existing_registrations_validation_failure
        topics:
          type: array
          items:
            type: string
            enum:
              - REGISTRATIONS.EXISTING.VALIDATION_FAILED
              - REGISTRATIONS.EXISTING.VALIDATION_SUCCEEDED
          description: An array of topics to listen to. When any of these topics are triggered, the webhook will be pinged.
        url:
          type: string
          description: Your webhook url that will be hit once a topic is triggered. Only https:// urls will work.
          example: https://bruno-simon.com/
        key:
          type: string
          description: Use for signing the event payloads. All the event payloads will be signed using this key. Make sure to keep it safe as you will need it during validating event payloads.
          example: couabowugowubfvow2efgofqpifhdiubvafobafou2ee
        status:
          type: string
          enum:
            - ENABLED
            - DISABLED
          description: If the webhook is active or not. If a webhook id disabled it won't be called when a topic is triggered.
        created_at:
          type: number
          description: Timestamp in UTC when this webhook was created.
          example: 1727284490
    UpdateWebhookRequest:
      type: object
      properties:
        api_version:
          type: string
          description: The version of the API for which you registered the webhook. This helps to maintain backward compatibility. If in newer versions the event payload is changed, your webhook will keep receiving the payload from this api version. This will be 'v1.0' for now and we will come up with more versions and a changelog later.
        name:
          type: string
          description: Optional name to define the purpose of the webhook.
        topics:
          type: array
          items:
            type: string
            enum:
              - REGISTRATIONS.EXISTING.VALIDATION_FAILED
              - REGISTRATIONS.EXISTING.VALIDATION_SUCCEEDED
          description: An array of topics to listen to. When any of these topics are triggered, the webhook will be pinged.
        status:
          type: string
          enum:
            - ENABLED
            - DISABLED
          description: If the webhook is active or not. If a webhook is disabled it won't be called when a topic is triggered.
    ProductTaxCode:
      type: string
      example: TPP
      description: Code passed by the caller to determine taxability for this product. Default value, TPP, will be taxable in every jurisdiction. Additional values are available [here](/api-reference/global-indirect-tax/taxcode).
      default: TPP
    ProductSKU:
      type: string
      description: A unique stock keeping unit (SKU) identifier for the product. Must be unique within your corporation and contain at least one character.
      example: PT-1035
      minLength: 1
    Product:
      type: object
      description: A product or service provided by the seller.
      required:
        - id
        - corporation_id
      properties:
        id:
          type: string
          description: Unique identifier assigned by Commenda for this product.
          example: 2535af08-a139-4d0c-9827-1651e46dfbcf
        name:
          type: string
          description: Display name of the product.
          example: SunShield Pro UV-Blocking Sunglasses
        tax_code:
          $ref: '#/components/schemas/ProductTaxCode'
        sku:
          $ref: '#/components/schemas/ProductSKU'
        description:
          type: string
          description: Brief description of the product.
        corporation_id:
          type: string
          description: Unique identifier assigned by Commenda for the corporation associated with this product.
          example: b6d009b0-d174-463f-b030-94643c28e209
    CreateProduct:
      type: object
      properties:
        name:
          type: string
          description: Display name for the new product.
          example: SunShield Pro UV-Blocking Sunglasses
        tax_code:
          $ref: '#/components/schemas/ProductTaxCode'
        sku:
          $ref: '#/components/schemas/ProductSKU'
        description:
          type: string
          description: A brief description of the product.
        corporation_id:
          type: string
          description: Unique identifier assigned by Commenda for the corporation associated with this product.
          example: b6d009b0-d174-463f-b030-94643c28e209
    Job:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the import job
        status:
          type: string
          enum:
            - PENDING
            - IN_PROGRESS
            - COMPLETED
            - FAILED
          description: Current status of the import job
        created_at:
          type: string
          format: date-time
          description: Timestamp when the job was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the job was last updated
    UpdateProduct:
      type: object
      properties:
        name:
          type: string
          description: Display name of the product.
          example: SunShield Pro UV-Blocking Sunglasses
          minLength: 3
        tax_code:
          $ref: '#/components/schemas/ProductTaxCode'
        description:
          type: string
          description: Brief description of the product.
          minLength: 3
    Country:
      type: string
      example: US
      description: 'ISO 3166 2-letter country code. Ex: US, IN, GB.'
    Corporation:
      type: object
      description: A corporation registered with Commenda.
      required:
        - id
        - legal_name
      properties:
        id:
          type: string
          description: The unique identifier for a corporation.
          example: b6d009b0-d174-463f-b030-94643c28e209
        legal_name:
          type: string
          description: The legal name of the corporation.
          example: Acme Corporation
    CreateCorporation:
      type: object
      description: Request body for creating a new corporation.
      required:
        - legal_name
      properties:
        legal_name:
          type: string
          description: The legal name of the corporation.
          example: Acme Corporation
    UpdateCorporation:
      type: object
      description: Request body for updating a corporation.
      properties:
        legal_name:
          type: string
          description: The legal name of the corporation.
          example: Acme Corporation
    TaxType:
      type: string
      enum:
        - RST
        - RUT
        - DTT
        - SST
        - SSUT
        - GRT
        - VUT
        - TPT
        - GET
        - SUT
      description: Tax type codes.
    Frequency:
      type: string
      enum:
        - MONTHLY
        - QUARTERLY
        - SEMI_ANNUALLY
        - ANNUAL_CALENDAR_YEAR
        - FISCAL_YEAR
        - QUARTERLY_PREPAY_MONTHLY
        - MONTHLY_ACCELERATED_PREPAY_EARLY
      description: Filing frequency for the registration.
    CreateRegistrationRequest:
      type: object
      required:
        - corporation_id
        - registration_content_id
        - tax_types
      properties:
        corporation_id:
          type: string
          format: uuid
          description: The unique identifier for the corporation.
          example: 550e8400-e29b-41d4-a716-446655440000
        registration_content_id:
          type: string
          description: Content ID identifying the jurisdiction and tax type. Get this from the registration-input-options endpoint.
          example: CCT_US_STATE_CEN_06_RST
        tax_types:
          type: array
          items:
            $ref: '#/components/schemas/TaxType'
          description: Array of tax types to register for.
          example:
            - RST
            - DTT
        frequency:
          $ref: '#/components/schemas/Frequency'
        effective_start_date:
          type: string
          format: date
          description: ISO date (YYYY-MM-DD) when the registration became effective.
          example: '2024-01-15'
        tax_registration_id:
          type: string
          description: State-issued tax registration ID or permit number.
          example: 123-456789
        credential_id:
          type: string
          description: Reference to stored portal credentials.
        portal_id:
          type: string
          description: Portal ID for the state's tax filing portal.
          example: PORTAL_CA_CDTFA
    jurisdiction_type:
      type: string
      enum:
        - STATE_OR_PROVINCE
        - CITY
        - COUNTY
        - DISTRICT
        - LOCAL
        - COUNTRY
        - TERRITORY
        - TRADEBLOC
      description: Type of tax jurisdiction.
    registration_status:
      type: string
      enum:
        - REGISTRATION_IN_PROGRESS
        - REGISTERED
      description: Reflects the current stage of the registration process.
    registration_validation_status:
      type: string
      enum:
        - PENDING
        - VALIDATION_IN_PROGRESS
        - INVALID
        - VALID
      description: Reflects whether Commenda has validated the seller's registration details.
    registration_type:
      type: string
      enum:
        - EXISTING
        - NEW
      description: Whether this is an existing registration or a new one created through Commenda.
    registered_by:
      type: string
      enum:
        - API
        - USER
        - COMMENDA
      description: Who created the registration.
    RegistrationResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the registration.
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        corporation_id:
          type: string
          format: uuid
          description: The corporation this registration belongs to.
        registration_content_id:
          type: string
          description: Content ID identifying the jurisdiction and tax type.
          example: CCT_US_STATE_CEN_06_RST
        jurisdiction_id:
          type: string
          description: Unique identifier for the jurisdiction.
          example: JUR_US_STATE_CA
        jurisdiction_type:
          $ref: '#/components/schemas/jurisdiction_type'
        jurisdiction_name:
          type: string
          description: Human-readable name of the jurisdiction.
          example: California
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: US
        state_or_province:
          type: string
          description: State or province code.
          example: CA
        tax_types:
          type: array
          items:
            $ref: '#/components/schemas/TaxType'
          example:
            - RST
            - DTT
        frequency:
          $ref: '#/components/schemas/Frequency'
        effective_start_date:
          type: string
          format: date
          example: '2024-01-15'
        effective_end_date:
          type: string
          format: date
          description: Set when registration is closed.
        tax_registration_id:
          type: string
          description: State-issued tax ID or permit number.
        portal_id:
          type: string
          description: Tax portal identifier.
        credential_id:
          type: string
          description: Reference to stored portal credentials.
        registration_status:
          $ref: '#/components/schemas/registration_status'
        validation_status:
          $ref: '#/components/schemas/registration_validation_status'
        registration_type:
          $ref: '#/components/schemas/registration_type'
        registered_by:
          $ref: '#/components/schemas/registered_by'
        email_alias:
          type: string
          description: Email alias for tax correspondence.
          example: tax-ca@acme.commenda.io
        archived_at:
          type: string
          format: date-time
          description: Timestamp if archived, otherwise null.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ListRegistrationsRequest:
      type: object
      required:
        - corporation_id
      properties:
        corporation_id:
          type: string
          format: uuid
          description: The corporation ID to list registrations for.
        countries:
          type: array
          items:
            type: string
          description: Filter by ISO country codes.
          example:
            - US
        states_or_provinces:
          type: array
          items:
            type: string
          description: Filter by state/province codes.
          example:
            - CA
            - NY
            - TX
        jurisdiction_types:
          type: array
          items:
            $ref: '#/components/schemas/jurisdiction_type'
          description: Filter by jurisdiction type.
        jurisdiction_name:
          type: string
          description: Search by jurisdiction name.
        registration_type:
          $ref: '#/components/schemas/registration_type'
        validation_status:
          $ref: '#/components/schemas/registration_validation_status'
        include_archived:
          type: boolean
          default: false
          description: Include archived registrations.
    UpdateRegistrationRequest:
      type: object
      properties:
        tax_types:
          type: array
          items:
            $ref: '#/components/schemas/TaxType'
          description: Array of tax types.
        frequency:
          $ref: '#/components/schemas/Frequency'
        effective_start_date:
          type: string
          format: date
          description: ISO date (YYYY-MM-DD) when the registration became effective.
        tax_registration_id:
          type: string
          description: State-issued tax registration ID or permit number.
        credential_id:
          type: string
          description: Reference to stored portal credentials.
        portal_id:
          type: string
          description: Portal ID for the state's tax filing portal.
    CloseRegistrationRequest:
      type: object
      required:
        - effective_end_date
      properties:
        effective_end_date:
          type: string
          format: date
          description: ISO date (YYYY-MM-DD) when the registration ends.
          example: '2024-12-31'
    JurisdictionsRequest:
      type: object
      properties:
        filters:
          type: object
          properties:
            countries:
              type: array
              items:
                type: string
              example:
                - US
            states:
              type: array
              items:
                type: string
              example:
                - CA
                - TX
            types:
              type: array
              items:
                $ref: '#/components/schemas/jurisdiction_type'
            tax_types:
              type: array
              items:
                $ref: '#/components/schemas/TaxType'
            registerable:
              type: boolean
            covering_registration_id:
              type: string
        search:
          type: string
          description: Free-text search across jurisdiction names.
        cursor:
          type: string
          description: Pagination cursor.
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
    JurisdictionsResponse:
      type: object
      properties:
        jurisdictions:
          type: array
          items:
            type: object
            properties:
              jurisdiction_id:
                type: string
                example: JUR_US_STATE_CA
              jurisdiction_name:
                type: string
                example: California
              jurisdiction_type:
                $ref: '#/components/schemas/jurisdiction_type'
              state_or_province:
                type: string
                example: CA
              country:
                type: string
                example: US
        total:
          type: integer
        cursor:
          type: string
    OptionsRequest:
      type: object
      required:
        - filters
      properties:
        filters:
          type: object
          required:
            - jurisdiction_ids
          properties:
            jurisdiction_ids:
              type: array
              items:
                type: string
              example:
                - JUR_US_STATE_CA
                - JUR_US_STATE_TX
    OptionsResponse:
      type: object
      properties:
        options:
          type: array
          items:
            type: object
            properties:
              jurisdiction_id:
                type: string
              jurisdiction_name:
                type: string
              registrations:
                type: array
                items:
                  type: object
                  properties:
                    registration_content_id:
                      type: string
                      example: CCT_US_STATE_CEN_06_RST
                    tax_type:
                      type: string
                      example: RST
                    frequencies:
                      type: array
                      items:
                        $ref: '#/components/schemas/Frequency'
                    related_tax_types:
                      type: array
                      items:
                        type: object
                        properties:
                          tax_type:
                            type: string
                          optional:
                            type: boolean
    PortalFieldsRequest:
      type: object
      required:
        - filters
      properties:
        filters:
          type: object
          required:
            - registration_content_ids
          properties:
            registration_content_ids:
              type: array
              items:
                type: string
              example:
                - CCT_US_STATE_CEN_06_RST
    PortalFieldsResponse:
      type: object
      properties:
        forms:
          type: array
          items:
            type: object
            properties:
              registration_content_id:
                type: string
              jurisdiction_id:
                type: string
              jurisdiction_name:
                type: string
              tax_type:
                type: string
              portals:
                type: array
                items:
                  type: object
                  properties:
                    portal_id:
                      type: string
                      example: PORTAL_CA_CDTFA
                    portal_name:
                      type: string
                      example: California Department of Tax and Fee Administration
                    portal_url:
                      type: string
                    credential_fields:
                      type: array
                      items:
                        type: object
                        properties:
                          credential_key:
                            type: string
                          credential_name:
                            type: string
                          credential_type:
                            type: string
                          required:
                            type: boolean
                          is_unique_per_registration:
                            type: boolean
                          regex:
                            type: string
                          display_order:
                            type: integer
    Currency:
      type: string
      example: USD
      description: ISO 4217 alpha-3 currency code for the transaction.
    State:
      type: string
      example: CA
      description: '2-letter code for each state. Suffix of the ISO 3166-2 code. Ex: CA, NY, TX.'
    Address:
      type: object
      required:
        - country
      description: |
        Address object. Only `country` is required at the schema level. All other field requirements (including `postal_code` and `state`) vary by country — use the `/address-requirements` endpoint to check which fields are REQUIRED, OPTIONAL, or IGNORED for a given country. When provided, postal codes and state codes are validated against country-specific formats and allowed values.
      properties:
        address_line_1:
          type: string
          example: 1776 Main St
          description: Primary street address. Required for some countries (e.g., US).
        address_line_2:
          type: string
          example: 'Apt. #123'
          description: Secondary address line (apartment, suite, etc.). Optional for most countries.
        address_line_3:
          type: string
          description: Tertiary address line. Ignored for most countries.
        postal_code:
          type: string
          description: |
            Postal or ZIP code. Required for many countries (e.g., US, GB, DE, FR) and optional for others (e.g., CA). Format varies by country. For US addresses, either 5-digit ZIP or 9-digit ZIP+4 is accepted. Use the `/address-requirements` endpoint to check whether this field is required and to get the validation regex for each country.
          example: '90401'
        city:
          type: string
          example: Santa Monica
          description: City name. Required for some countries (e.g., US).
        state:
          $ref: '#/components/schemas/State'
          description: |
            State or province code. Required for some countries (e.g., US) and optional for others (e.g., GB, DE). Must be a valid ISO 3166-2 subdivision code for the given country when provided. Use the `/address-requirements` endpoint to check whether this field is required and to get the list of valid state codes for each country.
        country:
          $ref: '#/components/schemas/Country'
    ExemptionType:
      type: string
      description: Reason for a sales tax exemption.
      enum:
        - PURPOSE_RESALE
        - ENTITY_TYPE_NONPROFIT
        - GOVERNMENT
        - MANUFACTURER
        - AGRICULTURAL
        - EXEMPT_PRODUCT
        - OTHER
        - EXEMPT_PRODUCT
    SourcePlatform:
      type: string
      description: Platform where this entity originated.
      enum:
        - RAZORPAY
        - ZOHO_BOOKS
        - QUICKBOOKS_SANDBOX
        - QUICKBOOKS
        - XERO
        - TALLY
        - SAGE_CLOUD_ACCOUNTING
        - MS_DYNAMICS_365
        - SAGE_ZA_CLOUD_ACCOUNTING
        - MYOB_BUSINESS
        - WAVE
        - ODOO_ACCOUNTING
        - NETSUITE
        - WAFEQ
        - MEKARI_JURNAL
        - BUSY
        - ROOTFI_SANDBOX
        - QOYOD
        - SHOPIFY
        - STRIPE
        - PAYPAL
        - HUBSPOT
        - ZOHO_CRM
        - PIPEDRIVE
        - WOOCOMMERCE
        - BIGCOMMERCE
        - OTHER
    TaxCalculationRequest:
      type: object
      required:
        - corporation_id
        - transaction_date
        - transaction_currency
        - transaction_type
        - addresses
        - customer_details
        - line_items
      properties:
        corporation_id:
          type: string
          description: The unique identifier for the corporation associated with this transaction.
          example: b6d009b0-d174-463f-b030-94643c28e209
        transaction_date:
          type: string
          format: date
          description: ISO 8601 formatted date string indicating date on which the transaction took place.
        transaction_currency:
          $ref: '#/components/schemas/Currency'
          description: |
            ISO 4217 alpha-3 currency code for the transaction. If omitted, defaults to the standard currency of the ship-to country (e.g., USD for the US, CAD for Canada, GBP for the UK). When this differs from the ship-to country's default currency, amounts are automatically converted for tax calculation and converted back in the response.
        transaction_type:
          type: string
          enum:
            - SALE
            - REFUND
            - PURCHASE
          description: |-
            Type of the transaction:
            - SALE: Standard sales transaction.
            - REFUND: Refund/return transaction with negative line item amounts.
            - PURCHASE: Purchase transaction for input tax credit tracking. Line item amounts must be negative.
        discount:
          type: number
          minimum: 0
          example: 0.99
          description: Total discount amount applied to the subtotal.
        addresses:
          type: object
          properties:
            ship_to:
              $ref: '#/components/schemas/Address'
              description: |
                Destination address for the transaction. If omitted, the API falls back to the default shipping address of the customer specified in `customer_details.customer_id`. If neither is available, the request fails with a `MISSING_SHIP_TO_ADDRESS` error. Address fields are validated against per-country requirements — use the `/address-requirements` endpoint to check which fields are required for each country.
            ship_from:
              $ref: '#/components/schemas/Address'
              description: |
                Origin address for the transaction. Required for certain destination countries (e.g., GB). If required but not provided, the request fails with a `MISSING_SHIP_FROM_ADDRESS` error. When the destination is US, the ship-from state must be a valid US state code and the postal code must be a valid US ZIP code.
          description: |
            Shipping origin and destination addresses. The `ship_to` field is optional when a `customer_id` is provided that has a default shipping address on file. The `ship_from` field is required for certain destination countries. All address fields are validated against country-specific requirements — query `/address-requirements` to check which fields are required, optional, or ignored for a given country.
        customer_details:
          type: object
          properties:
            customer_id:
              type: string
              description: Unique identifier for the customer for this transaction. Used for exemptions and for shipping address. If fields on the customer conflict with fields on this calculation, the ones on the calculation will be prioritized.
          description: Customer details for this transaction.
        exemption_reason:
          $ref: '#/components/schemas/ExemptionType'
          description: Optional exemption reason to apply to the entire transaction. When provided, the transaction may be fully or partially exempt from tax based on the exemption type and applicable jurisdiction rules.
        line_items:
          type: object
          required:
            - items
          properties:
            items:
              description: |
                Array of line items representing individual products or services in the transaction.  For each line item either pass the tax_code or the product_id. If the product_id is passed the tax_code will be fetched from the product itself. If no `product_taxaiblity_code` is available, `TPP` will be used as the fallback.
              type: array
              items:
                type: object
                required:
                  - quantity
                  - amount
                properties:
                  line_number:
                    type: integer
                    minimum: 1
                    description: Optional line number for this item.
                  line_item_id:
                    type: string
                    description: Optional identifier to uniquely identify this line item.
                  product_taxability_code:
                    $ref: '#/components/schemas/ProductTaxCode'
                  quantity:
                    type: number
                    description: |
                      Quantity of units. Must not be zero. For REFUND or PURCHASE transactions, negative values are accepted. Cannot be negative simultaneously with `amount`.
                  amount:
                    type: number
                    description: |
                      Total price for the line item. For REFUND or PURCHASE transactions, negative values are accepted. Cannot be negative simultaneously with `quantity`.
                  discount:
                    type: number
                    minimum: 0
                    description: Discount amount for this line item.
                  product_id:
                    type: string
                    description: The unique identifier for the product.
                  product_source_platform:
                    $ref: '#/components/schemas/SourcePlatform'
                  product_source_platform_id:
                    type: string
                    description: The identifier for the product on the source platform.
    TaxCalculationResponse:
      type: object
      properties:
        corporation_id:
          type: string
          description: The unique identifier for the corporation associated with this transaction.
          example: b6d009b0-d174-463f-b030-94643c28e209
        transaction_date:
          type: string
          format: date
          description: ISO 8601 formatted date string indicating date on which the transaction took place.
        transaction_currency:
          $ref: '#/components/schemas/Currency'
        calculation_currency:
          type: string
          description: |
            ISO 4217 alpha-3 currency code representing the currency used internally for the tax computation. This is the default currency of the ship-to country (e.g., USD for the US, CAD for Canada, GBP for the UK).
          example: USD
        exchange_rate:
          type: number
          format: float
          description: |
            The exchange rate applied between the transaction currency and the calculation currency. When no conversion is needed (i.e., the transaction currency matches the ship-to country's default currency), this value is 1.0.
          example: 1
        discount:
          type: number
          format: float
          example: 0.99
          description: Total discount amount applied to the transaction.
        customer_details:
          type: object
          properties:
            customer_id:
              type: string
              description: Unique identifier for the customer for this transaction.
          description: Customer details for this transaction.
        tax_currency:
          $ref: '#/components/schemas/Currency'
          description: ISO 4217 alpha-3 currency code representing the currency in which tax details are reported. This matches the transaction currency.
        addresses:
          type: object
          properties:
            ship_from:
              $ref: '#/components/schemas/Address'
            ship_to:
              $ref: '#/components/schemas/Address'
          description: The addresses for this transaction, including shipping origin and destination.
        line_items:
          type: array
          items:
            type: object
            properties:
              amount:
                type: number
                format: float
                description: Total price for the line item.
              taxable_amount:
                type: number
                format: float
                description: The amount that is considered taxable for this line item.
              quantity:
                type: number
                format: float
                description: Quantity of units purchased.
              tax_code:
                type: string
                description: The tax code used for this line item.
              product_id:
                type: string
                description: The unique identifier for the product.
              effective_tax_rate:
                type: number
                format: float
                description: The effective tax rate applied to this line item.
              tax_breakdown:
                type: array
                items:
                  type: object
                  properties:
                    jurisdiction:
                      type: string
                      description: Name of the taxing jurisdiction.
                      example: California
                    jurisdiction_type:
                      type: string
                      enum:
                        - STATE
                        - COUNTY
                        - CITY
                        - SPECIAL_DISTRICT
                        - TRADEBLOC
                      description: Type of tax jurisdiction.
                    rate:
                      type: number
                      format: float
                      example: 6.25
                      description: Tax rate for this jurisdiction as a percentage.
              total_tax_due:
                type: number
                format: float
                example: 1.03
                description: Total amount of sales tax to charge for line item.
    CustomsDutyCalculationRequest:
      type: object
      required:
        - corporation_id
        - invoice_currency
        - subtotal
        - origin_country
        - destination_country
        - line_items
      properties:
        corporation_id:
          type: string
          description: The unique identifier for the corporation to calculate an import duty rate for.
          example: b6d009b0-d174-463f-b030-94643c28e209
        invoice_currency:
          $ref: '#/components/schemas/Currency'
        subtotal:
          type: number
          example: 10.99
          description: Total amount before tax, shipping, handling, and discounts.
        discount:
          type: number
          example: 0.99
          description: Total discount amount applied to the subtotal.
        shipping_and_handling:
          type: number
          example: 0
          description: Total shipping and handling charges.
        origin_country:
          $ref: '#/components/schemas/Country'
        destination_country:
          $ref: '#/components/schemas/Country'
        line_items:
          type: object
          required:
            - amount
            - quantity
          properties:
            items:
              description: Array of line items representing individual products in the shipment. For each line item, pass exactly one of `customs_code` or the `product_id`. If the `product_id` is passed, the `customs_code` will be fetched from the product itself.
              type: array
              items:
                type: object
                properties:
                  amount:
                    type: number
                    description: Total price for the line item, including any discounts and shipping and handling costs.
                  quantity:
                    type: number
                    description: Quantity of units purchased.
                  product_id:
                    type: string
                    description: The unique identifier for the product getting sold in this line item.
    AddressRequirementsResponse:
      type: object
      properties:
        country_code:
          type: string
          description: The ISO 3166-1 alpha-2 country code.
          example: US
        address_line_1:
          type: string
          enum:
            - REQUIRED
            - OPTIONAL
            - IGNORED
          description: Whether address line 1 is required for this country.
          example: REQUIRED
        address_line_2:
          type: string
          enum:
            - REQUIRED
            - OPTIONAL
            - IGNORED
          description: Whether address line 2 is required for this country.
          example: OPTIONAL
        address_line_3:
          type: string
          enum:
            - REQUIRED
            - OPTIONAL
            - IGNORED
          description: Whether address line 3 is required for this country.
          example: IGNORED
        city:
          type: string
          enum:
            - REQUIRED
            - OPTIONAL
            - IGNORED
          description: Whether the city field is required for this country.
          example: REQUIRED
        state:
          type: string
          enum:
            - REQUIRED
            - OPTIONAL
            - IGNORED
          description: Whether the state or province field is required for this country.
          example: REQUIRED
        postal_code:
          type: string
          enum:
            - REQUIRED
            - OPTIONAL
            - IGNORED
          description: Whether the postal code field is required for this country.
          example: REQUIRED
        postal_code_regex:
          type: string
          nullable: true
          description: A regex pattern for validating postal codes in this country. Null if no specific format is enforced.
          example: ^\d{5}(-\d{4})?$
        valid_state_codes:
          type: array
          nullable: true
          items:
            type: string
          description: The list of accepted state or province codes for this country. Null if no specific codes are enforced.
          example:
            - AL
            - AK
            - AZ
            - AR
            - CA
    transaction_type:
      type: string
      enum:
        - SALE
        - RETURN
        - REFUND
        - PURCHASE
        - PURCHASE_REFUND
      description: |-
        Type of transaction:
        - SALE: Standard sales transaction (new sales, corrections, re-invoicing)
        - RETURN: Return/refund transaction (full or partial returns of previous sales)
        - REFUND: Legacy refund type (use RETURN instead for backward compatibility)
        - PURCHASE: Purchase transaction for input tax credit tracking (EU VAT, UK VAT). Line item amounts must be negative.
        - PURCHASE_REFUND: Auto-derived when creating a refund against a PURCHASE transaction. Cannot be set directly.
    TaxTransactionResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for a transaction.
          example: 9753a999-6d64-4a4f-ad9b-345890d32722
        corporation_id:
          type: string
          description: The unique identifier for the corporation associated with this transaction.
          example: 74df772f-9260-42cf-9c20-3b613b60fecd
        transacted_at:
          type: string
          format: date
          description: ISO 8601 formatted date string indicating the date on which the transaction took place.
          example: '2025-11-30'
        created_at:
          type: integer
          format: int64
          description: Unix timestamp in microseconds indicating when the transaction was created.
          example: 1765177896736899
        reporting_date_override:
          type: string
          format: date
          description: ISO 8601 formatted date string indicating when this transaction should appear in reports, if different from transacted_at.
          example: '2025-11-30'
        invoice_currency:
          $ref: '#/components/schemas/Currency'
        subtotal:
          type: number
          format: float
          description: Total amount before tax, shipping, handling, and discounts.
          example: 46.15
        discount:
          type: number
          format: float
          description: Total discount amount applied to the transaction.
          example: 0
        shipping_and_handling:
          type: number
          format: float
          description: Total shipping and handling charges.
          example: 0
        total:
          type: number
          format: float
          description: The total amount charged to the customer, which includes the subtotal, shipping and handling fees, tax, and reflects any applied discounts.
          example: 48.09
        tax_collected:
          type: number
          format: float
          description: Numeric value representing the amount of sales tax paid by the customer for this transaction.
          example: 1.94
        invoice_status:
          type: string
          enum:
            - LOCKED
            - UNCOMMITTED
            - IGNORED
          description: Status of the invoice/transaction.
          example: LOCKED
        invoice_type:
          type: string
          enum:
            - SALE
            - RETURN
            - REFUND
            - PURCHASE
            - PURCHASE_REFUND
          description: Type of the invoice/transaction.
          example: SALE
        invoice_number:
          type: string
          description: Invoice or receipt number for this transaction.
          example: c85100ab-7c61-4aa6-b207-c4dae0d40d13
        creation_method:
          type: string
          description: Method used to create this transaction.
          example: TRANSACTIONS_API_BULK
        marketplace:
          type: string
          nullable: true
          description: Marketplace name if the transaction originates from a marketplace.
        tax_remitter_type:
          type: string
          nullable: true
          enum:
            - SELLER
            - MARKETPLACE_FACILITATOR
            - BUYER
          description: |-
            Indicates which party is responsible for remitting tax on the transaction.
            - SELLER: The seller collects and remits tax (default).
            - MARKETPLACE_FACILITATOR: A marketplace facilitator collects and remits tax on behalf of the seller.
            - BUYER: The buyer is responsible for remitting tax (reverse-charge mechanism, common in B2B VAT transactions).
        metadata:
          type: object
          nullable: true
          description: Additional metadata associated with the transaction.
        customer_details:
          type: object
          properties:
            shipping_address:
              $ref: '#/components/schemas/Address'
            customer_id:
              type: string
              description: Unique identifier for the customer for this transaction.
        line_items:
          type: object
          properties:
            items:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier for the line item.
                    example: aec197ca-a1fa-4669-8496-f52c82da5d3c
                  amount:
                    type: number
                    format: float
                    description: Total price for the line item.
                    example: 46.15
                  quantity:
                    type: integer
                    description: Quantity of units purchased.
                    example: 1
                  shipping:
                    type: number
                    format: float
                    description: Shipping cost for this line item.
                    example: 0
                  handling:
                    type: number
                    format: float
                    description: Handling cost for this line item.
                    example: 0
                  discount:
                    type: number
                    format: float
                    description: Discount amount applied to this line item.
                    example: 0
                  price_per_unit:
                    type: number
                    format: float
                    description: Price per unit of the product.
                    example: 46.15
                  tax_collected:
                    type: number
                    format: float
                    description: Amount of tax collected for this line item.
                    example: 1.94
                  tax_code:
                    type: string
                    description: The product taxability code for this line item.
                  product_id:
                    type: string
                    description: Unique id in Commenda's system for the product being sold.
                  exemption_certificate_id:
                    type: string
                    description: ID of the exemption certificate applied to this line item.
                    example: 00000000-0000-0000-0000-000000000000
    CreateTaxTransactionRequest:
      type: object
      required:
        - corporation_id
        - transacted_at
        - invoice_currency
        - transaction_type
        - customer_details
        - line_items
      properties:
        corporation_id:
          type: string
          description: The unique identifier for the corporation associated with this transaction.
          example: b6d009b0-d174-463f-b030-94643c28e209
        transacted_at:
          type: string
          format: date
          description: ISO 8601 formatted date string indicating date on which the transaction took place.
        tax_date_override:
          type: string
          format: date
          description: ISO 8601 formatted date string indicating the date on which the tax liability should be recognized for filings and for nexus tracking, if different from the `transacted_at` date.
        calculation_date_override:
          type: string
          format: date
          description: ISO 8601 formatted date string indicating the date to use for tax rate lookups, useful for ensuring returns use the same rates as the original sale.
        reporting_date_override:
          type: string
          format: date
          description: ISO 8601 formatted date string indicating when this transaction should appear in reports, if different from transacted_at.
        invoice_currency:
          $ref: '#/components/schemas/Currency'
        invoice_number:
          type: string
          description: Invoice or receipt number for this transaction.
        subtotal:
          type: number
          format: float
          minimum: 0
          description: Total amount before tax, shipping, handling, and discounts.
        discount:
          type: number
          format: float
          minimum: 0
          example: 0.99
          description: Total discount amount applied to the transaction.
        shipping_and_handling:
          type: number
          format: float
          minimum: 0
          description: Total shipping and handling charges.
        total:
          type: number
          format: float
          minimum: 0
          description: This is the total amount charged to the customer, which includes the subtotal, shipping and handling fees, tax, and reflects any applied discounts.
        tax_collected:
          type: number
          format: float
          minimum: 0
          description: Numeric value representing the amount of sales tax paid by the customer for this transaction.
        transaction_type:
          $ref: '#/components/schemas/transaction_type'
          description: |-
            Type of the transaction. Accepted values for creation: `SALE` or `PURCHASE`.
            - `SALE`: Standard sales transaction.
            - `PURCHASE`: Purchase transaction for input tax credit tracking.
            `RETURN`, `REFUND`, and `PURCHASE_REFUND` types are created via the refund endpoint.
        calculation_id:
          type: string
          description: Optional ID of a previous calculation used for this transaction.
        parent_invoice_id:
          type: string
          description: |-
            Required for RETURN transactions. The ID of the original sale transaction being returned.
            This links the return to the original sale for proper tax accounting.
        refund_type:
          type: string
          enum:
            - FULL
            - PARTIAL
          description: |-
            Required for RETURN transactions. Specifies whether this is a full or partial return.
            - FULL: The entire transaction amount is refunded
            - PARTIAL: Only specific items or amounts are refunded
        customer_details:
          type: object
          required:
            - customer_id
          properties:
            shipping_address:
              $ref: '#/components/schemas/Address'
            customer_id:
              type: string
              description: Unique identifier for the customer for this transaction.
            customer_external_id:
              type: string
              description: External identifier for the customer.
        line_items:
          type: object
          required:
            - items
          properties:
            items:
              type: array
              items:
                type: object
                required:
                  - amount
                  - quantity
                properties:
                  amount:
                    type: number
                    format: float
                    description: |-
                      Total price for the line item. 
                      For SALE transactions: Typically positive, but can be negative for corrections within an invoice.
                      For RETURN transactions: Must be negative (can be achieved through negative quantity or negative price).
                      For PURCHASE transactions: Must be negative (same sign rules as RETURN).
                  line_number:
                    type: string
                    description: |-
                      Identifier for this line item. For RETURN transactions with line-level returns, 
                      this should match the line_number from the original invoice.
                  quantity:
                    type: integer
                    description: |-
                      Quantity of units purchased/returned. 
                      For RETURN transactions: Can be negative if used with positive price_per_unit to achieve a negative amount.
                  price_per_unit:
                    type: number
                    format: float
                    description: |-
                      Price per unit of the product. 
                      For RETURN transactions: Can be negative if used with positive quantity to achieve a negative amount.
                  discount_amount:
                    type: number
                    format: float
                    minimum: 0
                    description: Discount amount applied to this line item.
                  tax_collected:
                    type: number
                    format: float
                    description: Amount of tax collected for this line item.
                  tax_code:
                    type: string
                    description: The product taxability code for this line item.
                  product_id:
                    type: string
                    description: Unique id in Commenda's system for the product being sold. Must match the `id` of a product in Commenda. No more than one of `product_id` and `product_sku` should be set.
                  product_sku:
                    type: string
                    description: The SKU (Stock Keeping Unit) for the product. Must match the `sku` of a product in Commenda. No more than one of `product_id` and `product_sku` should be set.
                  exemption_type:
                    $ref: '#/components/schemas/ExemptionType'
                    description: If this field is present, this line item will be considered exempt.
                  exemption_reason:
                    type: string
                    description: Reason for tax exemption, if applicable.
                  exemption_certificate_id:
                    type: string
                    description: ID of exemption certificate, if applicable.
        marketplace:
          type: string
          description: Marketplace name if the transaction originates from a marketplace.
        tax_remitter_type:
          type: string
          enum:
            - SELLER
            - MARKETPLACE_FACILITATOR
            - BUYER
          description: |-
            Indicates which party is responsible for remitting tax on the transaction.
            - SELLER: The seller collects and remits tax (default).
            - MARKETPLACE_FACILITATOR: A marketplace facilitator collects and remits tax on behalf of the seller.
            - BUYER: The buyer is responsible for remitting tax (reverse-charge mechanism, common in B2B VAT transactions).
        tax_included:
          type: boolean
          description: Whether tax is included in the line item prices.
        exemption_type:
          $ref: '#/components/schemas/ExemptionType'
          description: If this field is present, this transaction will be considered exempt.
    CreateRefundRequest:
      type: object
      required:
        - refund_type
      properties:
        refund_type:
          type: string
          enum:
            - FULL
            - PARTIAL
          description: Whether to refund an entire transaction or only specific line items.
        line_items:
          type: array
          description: The line items to refund. Required if `refund_type` is `PARTIAL`.
          items:
            type: object
            required:
              - line_id
            properties:
              line_id:
                type: string
                description: Unique identifier for the line item to refund.
              quantity:
                type: number
                description: Quantity to refund. Required for partial refunds.
              price_per_unit:
                type: number
                description: Price per unit for the refund. Optional, defaults to the original price.
    BulkTransactionMetadata:
      type: object
      properties:
        upload_id:
          type: string
          description: The unique identifier for the bulk transaction upload.
          example: 2535af08-a139-4d0c-9827-1651e46dfbcf
        file_name:
          type: string
          description: The name of the file uploaded.
          example: example.csv
        transaction_count:
          type: integer
          description: The number of transactions in the file.
          example: 100
        size:
          type: integer
          description: The size of the file in bytes.
          example: 1024
        corporation_id:
          type: string
          description: The unique identifier for a corporation.
          example: 2535af08-a139-4d0c-9827-1651e46dfbcf
        created_at:
          type: number
          description: Timestamp in UTC when this bulk transaction upload was created.
          example: 1727284490
    ThresholdType:
      description: Specifies how a state calculates its economic nexus threshold. This determines which criteria a state uses to establish whether a business has reached nexus and is required to collect and remit sales tax. Some states consider only sales revenue, some only the number of transactions, and others consider both factors.
      type: string
      example: SALES_OR_TRANSACTIONS
      enum:
        - SALES_ONLY
        - SALES_OR_TRANSACTIONS
        - SALES_AND_TRANSACTIONS
    EvaluationPeriod:
      type: string
      description: The time frame over which a state evaluates economic nexus. Transactions within this period are counted towards the nexus threshold.
      enum:
        - PREVIOUS_CALENDAR_YEAR
        - PREVIOUS_OR_CURRENT_CALENDAR_YEAR
        - PRECEDING_12_MONTHS
        - PRECEDING_FISCAL_YEAR
        - PRECEDING_12_MONTHS_ENDING_SEPT_30
    IncludableSalesType:
      type: string
      description: Specifies the type of sales that are included when calculating the nexus threshold. This determines which sales are considered for nexus evaluation.
      enum:
        - ALL_SALES
        - TAXABLE_SALES
        - RETAIL_SALES
        - GROSS
    NexusRule:
      type: object
      required:
        - threshold_type
        - evaluation_period_type
        - includable_sales_type
      properties:
        sales_threshold:
          type: number
          description: The maximum gross sales revenue a business can generate within a state before it must collect and remit sales tax. This threshold is a key determinant in establishing economic nexus.
          example: 100000
        transactions_threshold:
          type: number
          description: The maximum number of sales transactions a business can conduct within a state before it must collect and remit sales tax. This threshold helps determine economic nexus.
          example: 200
        threshold_type:
          $ref: '#/components/schemas/ThresholdType'
          description: Specifies the criteria used by a state to calculate its economic nexus threshold, such as sales revenue or transaction count.
        evaluation_period_type:
          $ref: '#/components/schemas/EvaluationPeriod'
          description: Defines the time frame over which a state evaluates economic nexus, impacting which transactions count towards the threshold.
        includable_sales_type:
          $ref: '#/components/schemas/IncludableSalesType'
          description: Indicates the type of sales included in the nexus calculation, such as all sales, taxable sales, or retail sales.
    CalculationObject:
      type: object
      required:
        - sales_exposure_percentage
        - transactions_exposure_percentage
        - total_sales
        - total_transactions
      properties:
        total_sales:
          type: number
          description: Total sales made by the customer in a state during the current evaluation period.
          example: 0
        total_transactions:
          type: integer
          description: Total number of transactions reported by the entity in a state during the current evaluation period.
          example: 0
        gross_sales:
          type: number
          description: Total gross sales made by the customer in a state during the current evaluation period.
          example: 0
        gross_transactions:
          type: integer
          description: Total number of gross transactions reported by the entity in a state during the current evaluation period.
          example: 0
        taxable_sales:
          type: number
          description: Total taxable sales made by the customer in a state during the current evaluation period.
          example: 0
        taxable_transactions:
          type: integer
          description: Total number of taxable transactions reported by the entity in a state during the current evaluation period.
          example: 0
        retail_sales:
          type: number
          description: Total retail sales made by the customer in a state during the current evaluation period.
          example: 0
        retail_transactions:
          type: integer
          description: Total number of retail transactions reported by the entity in a state during the current evaluation period.
          example: 0
        sales_exposure_percentage:
          type: number
          description: The percentage of the state's sales threshold that the business has reached during the current evaluation period for this state. This metric indicates how close a business is to reaching or exceeding the sales threshold for economic nexus in a given state.
          example: 0
          minimum: 0
          maximum: 1
        transactions_exposure_percentage:
          type: number
          description: The percentage of the state's transaction threshold that the business has reached during the current evaluation period for this state. This metric shows how close a business is to reaching or exceeding the transaction threshold for economic nexus in a given state.
          example: 0
          minimum: 0
          maximum: 1
        includable_sales_type:
          type: string
          description: The type of sales included in the nexus calculation.
          example: GROSS
    EconomicExposure:
      type: object
      required:
        - state
        - rule
        - calculation
      properties:
        state:
          $ref: '#/components/schemas/State'
        rule:
          $ref: '#/components/schemas/NexusRule'
        calculation:
          $ref: '#/components/schemas/CalculationObject'
        is_nexus_breached:
          type: boolean
          description: Indicates whether the nexus threshold has been breached.
        date_of_breach:
          type: string
          format: date
          description: The date when the nexus threshold was breached, if applicable.
    NexusResponse:
      type: object
      description: Default response when `v2` is not set or `false`. Returns US-state-level registration threshold data.
      properties:
        corporation_id:
          type: string
          description: The unique identifier for a corporation associated with this nexus details.
          example: b6d009b0-d174-463f-b030-94643c28e209
        states:
          type: array
          items:
            $ref: '#/components/schemas/EconomicExposure'
    NexusRuleV2:
      type: object
      required:
        - threshold_type
        - evaluation_period_type
        - location_based_scope
        - exclusion_types
        - establishment_types
      properties:
        sales_threshold:
          type: number
          nullable: true
          description: The sales revenue threshold that triggers a registration obligation, in the jurisdiction's currency. Null if the rule does not use a sales threshold.
          example: 100000
        transactions_threshold:
          type: integer
          nullable: true
          description: The transaction count threshold that triggers a registration obligation. Null if the rule does not use a transaction threshold.
          example: 200
        threshold_type:
          $ref: '#/components/schemas/ThresholdType'
        evaluation_period_type:
          $ref: '#/components/schemas/EvaluationPeriod'
        location_based_scope:
          type: string
          description: Defines which transactions count toward the threshold based on the geographic relationship between buyer and seller.
          enum:
            - DESTINATION
            - WORLDWIDE
            - INTRA_COMMUNITY
            - IMPORT
          example: DESTINATION
        exclusion_types:
          type: array
          description: Transaction types automatically excluded from threshold calculations for this rule (e.g., marketplace, B2B, resale).
          items:
            type: string
          example:
            - TRANSACTION.MARKETPLACE
            - CUSTOMER.B2B
        establishment_types:
          type: array
          description: Business establishment types that determine which variant of the rule applies (e.g., resident vs. non-resident).
          items:
            type: string
          example: []
        max_transaction_value:
          type: integer
          nullable: true
          description: Maximum value per transaction for inclusion in threshold calculations. Transactions exceeding this cap are excluded. Used by schemes like IOSS where only consignments at or below €150 are included.
    CalculationObjectV2:
      type: object
      required:
        - included_sales
        - included_transactions
        - gross_sales
        - gross_transactions
        - sales_exposure_percentage
        - transactions_exposure_percentage
      properties:
        included_sales:
          type: number
          description: Sales amount included in the threshold calculation for this rule, based on the rule's includable sales type. Expressed in the jurisdiction's currency.
          example: 75000
        included_transactions:
          type: integer
          description: Number of transactions included in the threshold calculation for this rule.
          example: 150
        gross_sales:
          type: number
          description: Total gross sales in the jurisdiction during the evaluation period.
          example: 80000
        gross_transactions:
          type: integer
          description: Total gross transaction count in the jurisdiction during the evaluation period.
          example: 160
        sales_exposure_percentage:
          type: number
          description: Percentage of the sales threshold reached (0 to 1). Values above 1 indicate the threshold has been exceeded.
          example: 0.75
          minimum: 0
        transactions_exposure_percentage:
          type: number
          description: Percentage of the transaction threshold reached (0 to 1). Values above 1 indicate the threshold has been exceeded.
          example: 0.75
          minimum: 0
    JurisdictionExposure:
      type: object
      required:
        - jurisdiction_id
        - jurisdiction_type
        - jurisdiction_name
        - exposure_type
        - exposure_rule_id
        - currency
        - rule
        - calculation
        - is_nexus_breached
      properties:
        jurisdiction_id:
          type: string
          description: Commenda's internal jurisdiction identifier.
          example: US_CA_1000
        jurisdiction_type:
          type: string
          description: The type of jurisdiction.
          enum:
            - STATE
            - STATE_OR_PROVINCE
            - COUNTRY
            - TRADEBLOC
          example: STATE
        jurisdiction_name:
          type: string
          description: Human-readable name of the jurisdiction (e.g., "California", "United Kingdom", "EU Union OSS").
          example: California
        exposure_type:
          type: string
          description: The type of exposure rule being evaluated.
          enum:
            - EXPOSURE_PHYSICAL
            - EXPOSURE_ECONOMIC
            - EXPOSURE
          example: EXPOSURE
        exposure_rule_id:
          type: string
          description: Unique identifier for the exposure rule being evaluated.
          example: US_CA_ECONOMIC_001
        subdivision:
          type: string
          description: State or province code within the country, if applicable.
          example: CA
        currency:
          type: string
          description: ISO 4217 currency code used for threshold amounts.
          example: USD
        rule:
          $ref: '#/components/schemas/NexusRuleV2'
        calculation:
          $ref: '#/components/schemas/CalculationObjectV2'
        is_nexus_breached:
          type: boolean
          description: Whether the registration threshold has been exceeded for this rule.
        date_of_breach:
          type: string
          format: date
          description: The earliest date the threshold was exceeded, if applicable.
        recommended_registration_content_ids:
          type: array
          nullable: true
          description: Content identifiers of the recommended tax registrations for this jurisdiction and exposure rule. Use these values with the V2 registration content APIs to look up registration details. Null or empty when no specific registrations are recommended.
          items:
            type: string
          example:
            - REG_STATE_CEN_06_1000
    NexusV2Response:
      type: object
      description: Response when `v2=true`. Returns global jurisdiction-level registration threshold data covering US, Canada, UK, and EU jurisdictions.
      properties:
        corporation_id:
          type: string
          description: The unique identifier for the corporation.
          example: b6d009b0-d174-463f-b030-94643c28e209
        jurisdictions:
          type: array
          description: Registration threshold exposure data for each jurisdiction. A single jurisdiction may appear multiple times if multiple exposure rules apply (for example, EU Union OSS and Non-Union OSS).
          items:
            $ref: '#/components/schemas/JurisdictionExposure'
    CountrySpecificDetails:
      type: object
      properties:
        legal_name:
          type: string
          description: The legal name of the entity being registered.
          example: Example Inc.
        state:
          type: string
          description: State or province code.
          example: CA
        state_specific_details:
          type: object
          properties:
            payment_interval:
              type: string
              description: Payment interval for sales tax.
            sales_tax_id:
              type: string
              description: Sales tax ID.
            tax_types:
              type: array
              items:
                type: string
    filing_frequency:
      type: string
      enum:
        - MONTHLY
        - QUARTERLY
        - SEMI_ANNUALLY
        - ANNUAL_CALENDAR_YEAR
        - FISCAL_YEAR
        - MONTHLY_ACCELERATED_PREPAY_EARLY
        - QUARTERLY_PREPAY_MONTHLY
        - ANNUAL_RECONCILIATION
        - BI_MONTHLY
        - TRI_ANNUALLY
        - QUARTERLY_FEB
        - QUARTERLY_MAR
      description: How often the business is required to submit tax returns. V1 registrations typically use MONTHLY, QUARTERLY, SEMI_ANNUALLY, or ANNUAL_CALENDAR_YEAR. V2 registrations may use additional frequencies such as ANNUAL_RECONCILIATION (for jurisdictions requiring a separate annual reconciliation filing alongside periodic returns) or region-specific variants like QUARTERLY_FEB and QUARTERLY_MAR.
    Tax_filing_status:
      type: string
      enum:
        - SCHEDULED
        - ACCRUING
        - ACTIVE
        - FILED
        - OVERDUE
      description: Current status of the filing. SCHEDULED means the filing has been created but the tax period has not yet started. ACCRUING means transactions are being collected for this period. ACTIVE means the filing is ready for review and submission. FILED means the return has been submitted. OVERDUE means the due date has passed without filing.
    FilingContribution:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for this contribution.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        filing_id:
          type: string
          format: uuid
          description: The filing this contribution belongs to.
          example: f1e2d3c4-b5a6-7890-abcd-ef1234567890
        filing_contribution_id:
          type: string
          description: Stable content identifier that links this contribution to its tax return box rule definition.
          example: REG_COUNTRY_DE_3018_VAT_01_01
        filing_through_jurisdiction:
          type: string
          nullable: true
          description: Commenda jurisdiction identifier for the member state this contribution applies to. Present for multi-jurisdiction filings (e.g., EU OSS/IOSS); null for single-jurisdiction filings.
          example: COUNTRY_DE_3018
        value:
          type: integer
          format: int64
          description: The computed monetary amount in minor currency units (e.g., cents). For example, a value of 12345 represents 123.45 in the filing currency.
          example: 12345
        value_type:
          type: string
          description: The type of the value field. Currently always `INTEGER`.
          example: INTEGER
        box_id:
          type: string
          description: Identifier for the tax return form box this contribution maps to.
          example: DE_81
        box_name:
          type: string
          description: Human-readable name of the tax return form box.
          example: Steuerpflichtige Umsätze
        box_order:
          type: integer
          format: int32
          description: Display order of the box on the tax return form.
          example: 1
        box_type:
          type: string
          description: Classification of the box (e.g., input, output, total).
          example: OUTPUT
        created_at:
          type: integer
          format: int64
          description: Timestamp when this contribution was created, in Unix microseconds.
          example: 1713168000000000
        updated_at:
          type: integer
          format: int64
          description: Timestamp when this contribution was last updated, in Unix microseconds.
          example: 1713168000000000
    FilingsForGetAll:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the filing.
        corporation_id:
          type: string
          description: The unique identifier for a corporation associated with this filing.
        form_title:
          type: string
          description: Name of the tax return form for this filing (e.g., "Sales and Use Tax Return").
        description:
          type: string
          description: Additional details about the filing, such as filing variant or deadline type.
        country:
          $ref: '#/components/schemas/Country'
        country_specific_details:
          $ref: '#/components/schemas/CountrySpecificDetails'
        registration_tax_type_id:
          type: string
          nullable: true
          description: The V2 registration content identifier linking this filing to a specific registration tax type. Present for filings created via the V2 path; null for V1 filings.
          example: REG_STATE_CEN_06_RST
        jurisdiction_name:
          type: string
          nullable: true
          description: |-
            Human-readable jurisdiction name derived from V2 registration content
             (e.g., "California", "Germany"). Present for V2 filings; null for V1 filings.
        jurisdiction_type:
          type: string
          nullable: true
          description: Type of jurisdiction for this filing. Present for V2 filings; null for V1 filings.
          enum:
            - STATE_OR_PROVINCE
            - COUNTRY
            - TRADEBLOC
            - CITY_OR_COUNTY
        filing_content_id:
          type: string
          nullable: true
          description: Content identifier linking this filing to its filing calendar entry and contribution box rules. Present for V2 filings with content-driven calendars; null for V1 filings.
          example: FC_DE_3001_VAT
        frequency:
          $ref: '#/components/schemas/filing_frequency'
        period_start_date:
          type: string
          format: date
          description: ISO 8601 date string, identifying the start date of the period period for which the sales tax is being filed (e.g., '2024-09-01' for September 2024). For a quarter 1 filing where the fiscal year starts in March, the period_start_date will be 2024-03-01 and frequency will be QUARTERLY.
        reporting_period_start_date:
          type: string
          format: date
          description: Start date of the reporting period, which may differ from the tax period. For example, a quarterly filing may have a tax period of Jan–Mar but a reporting deadline that references a different window.
        reporting_period_end_date:
          type: string
          format: date
          description: End date of the reporting period.
        due_date:
          type: string
          format: date
          description: ISO 8601 date string, identifying the date when by which the filing must be submitted.
        filing_status:
          $ref: '#/components/schemas/Tax_filing_status'
        filed_on:
          type: string
          format: date
          description: Date when the taxes were filed with the state, in ISO 8601 format.
        registration_id:
          type: string
          description: The unique identifier for the tax registration associated with this filing.
        total_tax_filed:
          type: number
          description: Total amount of sales tax filed with various jurisdictions for this period. May differ slightly from the total tax collected.
          example: 135.92
        payment_details:
          type: object
          properties:
            amount_due:
              type: number
              description: Total amount due for this filing.
            payment_status:
              type: string
              enum:
                - PENDING
                - COMPLETED
                - FAILED
              description: Status of the payment.
            failure_details:
              type: object
              description: This object will be populated if the payment fails for any reason.
              properties:
                failed_at:
                  type: string
                  format: date
                  description: ISO 8601 date string, identifying the date when the payment failed.
                reason:
                  type: string
                  description: Specific information why the payment failed.
        contributions:
          type: array
          nullable: true
          description: Computed tax-return box contributions for this filing. Only populated on the V2 list path (`v2=true`) when called with `extend=filing_contribution`. When the expansion is not requested, this field is omitted from the response. An empty array means the filing has no computed contributions yet.
          items:
            $ref: '#/components/schemas/FilingContribution'
    FilingsGet:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the filing.
        corporation_id:
          type: string
          description: The unique identifier for a corporation associated with this filing.
        form_title:
          type: string
          description: Name of the tax return form for this filing (e.g., "Sales and Use Tax Return").
        description:
          type: string
          description: Additional details about the filing, such as filing variant or deadline type.
        country:
          $ref: '#/components/schemas/Country'
        country_specific_details:
          $ref: '#/components/schemas/CountrySpecificDetails'
        registration_tax_type_id:
          type: string
          nullable: true
          description: The V2 registration content identifier linking this filing to a specific registration tax type. Present for filings created via the V2 path; null for V1 filings.
          example: REG_STATE_CEN_06_RST
        jurisdiction_name:
          type: string
          nullable: true
          description: Human-readable jurisdiction name derived from V2 registration content (e.g., "California", "Germany"). Present for V2 filings; null for V1 filings.
        jurisdiction_type:
          type: string
          nullable: true
          description: Type of jurisdiction for this filing. Present for V2 filings; null for V1 filings.
          enum:
            - STATE_OR_PROVINCE
            - COUNTRY
            - TRADEBLOC
            - CITY_OR_COUNTY
        filing_content_id:
          type: string
          nullable: true
          description: Content identifier linking this filing to its filing calendar entry and contribution box rules. Present for V2 filings with content-driven calendars; null for V1 filings.
          example: FC_DE_3001_VAT
        frequency:
          $ref: '#/components/schemas/filing_frequency'
        period_start_date:
          type: string
          format: date
          description: ISO 8601 date string, identifying the start date of the period period for which the sales tax is being filed (e.g., '2024-09-01' for September 2024). For a quarter 1 filing where the fiscal year starts in March, the period_start_date will be 2024-03-01 and frequency will be QUARTERLY.
        reporting_period_start_date:
          type: string
          format: date
          description: Start date of the reporting period, which may differ from the tax period.
        reporting_period_end_date:
          type: string
          format: date
          description: End date of the reporting period.
        due_date:
          type: string
          format: date
          description: ISO 8601 date string, identifying the date when by which the filing must be submitted.
        filing_status:
          $ref: '#/components/schemas/Tax_filing_status'
        filed_on:
          type: string
          format: date
          description: Date when the taxes were filed with the state, in ISO 8601 format.
        registration_id:
          type: string
          description: The unique identifier for the tax registration associated with this filing.
        total_tax_filed:
          type: number
          description: Total amount of sales tax filed with various jurisdictions for this period. May differ slightly from the total tax collected.
          example: 135.92
        sales_details:
          type: object
          properties:
            total_sales:
              type: number
              description: Total sales amount for the filing period.
              example: 12345.91
            taxable_sales:
              type: number
              description: Total sales amount that was subject to sales tax for the filing period.
              example: 12345.91
            sales_tax_collected:
              type: number
              description: Total sales tax collected during the period.
              example: 771.62
        payment_details:
          type: object
          properties:
            amount_due:
              type: number
              description: Total amount due for this filing.
              example: 771.62
            payment_status:
              type: string
              enum:
                - PENDING
                - COMPLETED
                - FAILED
              description: Status of the payment.
            failure_details:
              type: object
              description: This object will be populated if the payment fails for any reason.
              properties:
                failed_at:
                  type: string
                  description: ISO 8601 date string, identifying the date when the payment failed.
                reason:
                  type: string
                  description: Specific information why the payment failed.
    FilingContributionsResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total number of contributions returned.
          example: 5
        contributions:
          type: array
          items:
            $ref: '#/components/schemas/FilingContribution'
    GetLiabilityReportRequest:
      type: object
      required:
        - filing_ids
      properties:
        filing_ids:
          type: array
          description: List of filing UUIDs to include in the report. Maximum 100 entries.
          minItems: 1
          maxItems: 100
          items:
            type: string
            format: uuid
          example:
            - f1e2d3c4-b5a6-7890-abcd-ef1234567890
            - a2b3c4d5-e6f7-8901-bcde-f23456789012
    LiabilityReportBreakdown:
      type: object
      description: Filing-level liability snapshot. Populated only for filings whose liability values live on the filing row itself (US sales/use tax, Canadian GST/HST/PST). For VAT filings (UK/EU country VAT and OSS/IOSS variants), this object is `null` on the parent entry — fetch box-level values from `POST /filings/contributions` instead. Money fields are major-unit decimals.
      properties:
        transactions_count:
          type: integer
          format: int64
          description: Number of transactions contributing to this filing.
          example: 142
        estimated_taxable_amount:
          type: number
          format: double
          description: Estimated taxable amount in major currency units.
          example: 12500
        estimated_non_taxable_amount:
          type: number
          format: double
          description: Estimated non-taxable amount in major currency units.
          example: 1500.5
        estimated_exempt_amount:
          type: number
          format: double
          description: Estimated exempt amount in major currency units.
          example: 250
        estimated_tax_collected:
          type: number
          format: double
          description: Estimated tax collected in major currency units.
          example: 1031.25
    LiabilityReportFiling:
      type: object
      description: One filing's slot in the liability report response. Common metadata (form title, jurisdiction, period) is always present so the consumer has enough context to render the row even when `breakdown` is `null`.
      properties:
        filing_id:
          type: string
          format: uuid
          description: Unique identifier for the filing.
          example: f1e2d3c4-b5a6-7890-abcd-ef1234567890
        form_title:
          type: string
          description: Display name of the tax return form.
          example: Sales and Use Tax Return
        jurisdiction:
          type: string
          description: Human-readable jurisdiction name.
          example: California
        tax_period_start_date:
          type: string
          format: date
          description: ISO 8601 start date of the tax period.
          example: '2025-01-01'
        tax_period_end_date:
          type: string
          format: date
          description: ISO 8601 end date of the tax period.
          example: '2025-03-31'
        due_date:
          type: string
          format: date
          description: ISO 8601 due date of the filing.
          example: '2025-04-30'
        filing_status:
          type: string
          description: Current status of the filing (e.g., `SCHEDULED`, `UPCOMING`, `OVERDUE`, `FILED`).
          example: UPCOMING
        breakdown:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/LiabilityReportBreakdown'
    GetLiabilityReportResponse:
      type: object
      properties:
        filings:
          type: array
          items:
            $ref: '#/components/schemas/LiabilityReportFiling'
    GetFilingContributionsBatchRequest:
      type: object
      required:
        - filing_ids
      properties:
        filing_ids:
          type: array
          description: List of filing UUIDs to fetch contributions for. Maximum 100 entries.
          minItems: 1
          maxItems: 100
          items:
            type: string
            format: uuid
    FilingContributionsBatchEntry:
      type: object
      description: One filing's slot in the batched contributions response. Common filing metadata is always populated. `contributions` is non-null for filings whose liability is computed from the filing contribution table (UK/EU VAT — country-level VATs and OSS variants); for US/Canada filings whose liability lives on the filing row itself, `contributions` is `null`. An empty array means "this is a contribution-type filing but the engine hasn't computed its boxes yet" — different from `null` ("does not apply").
      properties:
        filing_id:
          type: string
          format: uuid
          example: f1e2d3c4-b5a6-7890-abcd-ef1234567890
        form_title:
          type: string
          example: VAT Return
        jurisdiction:
          type: string
          example: Germany
        tax_period_start_date:
          type: string
          format: date
          example: '2025-01-01'
        tax_period_end_date:
          type: string
          format: date
          example: '2025-03-31'
        due_date:
          type: string
          format: date
          example: '2025-04-30'
        filing_status:
          type: string
          example: UPCOMING
        contributions:
          nullable: true
          type: array
          items:
            $ref: '#/components/schemas/FilingContribution'
    GetFilingContributionsBatchResponse:
      type: object
      properties:
        filings:
          type: array
          items:
            $ref: '#/components/schemas/FilingContributionsBatchEntry'
    ExportLiabilityReportRequest:
      type: object
      required:
        - filing_ids
        - delivery_recipients
      properties:
        filing_ids:
          type: array
          description: List of filing UUIDs to include in the export. Maximum 100 entries.
          minItems: 1
          maxItems: 100
          items:
            type: string
            format: uuid
        delivery_recipients:
          type: array
          description: Email addresses that will receive a signed download link to the generated zip when the export job completes.
          minItems: 1
          items:
            type: string
            format: email
          example:
            - tax-team@example.com
    ExportLiabilityReportResponse:
      type: object
      properties:
        job_id:
          type: string
          description: Identifier of the queued export job. Poll job status via the jobs endpoint, filtering by `entity=FILING` and `operation=EXPORT_INDIRECT_TAX_FILINGS_LIABILITY_REPORT`.
          example: j1a2b3c4-d5e6-7890-abcd-ef1234567890
    CustomerInfo:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for this customer.
          example: b6d009b0-d174-463f-b030-94643c28e209
        corporation_id:
          type: string
          description: The unique identifier for the corporation associated with this customer.
          example: 2535af08-a139-4d0c-9827-1651e46dfbcf
        name:
          type: string
          description: A display name for this customer.
          example: John Doe
        email:
          type: string
          description: Email address of the customer.
          format: email
        shipping_address:
          $ref: '#/components/schemas/Address'
        external_id:
          type: string
          description: External identifier for the customer.
        business_identification_number:
          type: string
          description: Business identification number for the customer (e.g., tax ID, VAT number, or EIN).
    ExemptionMetadata:
      type: object
      properties:
        total_certificates:
          type: integer
          description: Total number of exemption certificates for this customer
        certificate_types:
          type: array
          items:
            type: string
          description: List of unique certificate types held by this customer
        total_exempted_states:
          type: integer
          description: Total number of states where the customer has exemptions
        expired_exemptions_count:
          type: integer
          description: Number of expired exemption certificates
        inactive_exemptions_count:
          type: integer
          description: Number of inactive exemption certificates
        exempted_states:
          type: array
          items:
            type: string
          description: List of states where the customer has exemptions
        active_exemptions_count:
          type: integer
          description: Number of active exemption certificates
        non_expired_exemptions_count:
          type: integer
          description: Number of non-expired exemption certificates
    CustomerExtended:
      allOf:
        - $ref: '#/components/schemas/CustomerInfo'
        - type: object
          properties:
            exemption_metadata:
              $ref: '#/components/schemas/ExemptionMetadata'
    GetAllCustomersByCorporation:
      type: object
      properties:
        customers:
          type: array
          items:
            $ref: '#/components/schemas/CustomerExtended'
        total_customers:
          type: integer
          description: Total number of customers associated with the corporation.
        cursor:
          type: string
          description: Pagination cursor for the next set of results.
    CustomerCreate:
      type: object
      required:
        - name
        - corporation_id
      properties:
        name:
          type: string
          description: A display name for this customer.
          example: John Doe
          minLength: 3
        corporation_id:
          type: string
          description: The unique identifier for a corporation this customer belongs to.
          example: b6d009b0-d174-463f-b030-94643c28e209
        email:
          type: string
          description: Email address of the customer.
          format: email
        shipping_address:
          $ref: '#/components/schemas/Address'
        external_id:
          type: string
          description: External identifier for the customer.
        business_identification_number:
          type: string
          description: Business identification number for the customer (e.g., tax ID, VAT number, or EIN).
    CustomerUpdate:
      type: object
      properties:
        name:
          type: string
          description: A display name for this customer.
          minLength: 3
        email:
          type: string
          description: Email address of the customer.
          format: email
        shipping_address:
          $ref: '#/components/schemas/Address'
        business_identification_number:
          type: string
          description: Business identification number for the customer (e.g., tax ID, VAT number, or EIN).
    ExemptionCertificateType:
      type: string
      enum:
        - SINGLE_STATE
        - SST
        - MTC
      description: Enum representing the type of the exemption certificate (Streamlined Sales Tax, Multistate Tax Commission, or single state). More details [here](/api-reference/global-indirect-tax/exemptions/exemption-certificates/exemption-certificates#certificate-types).
    ExemptionReason:
      type: string
      enum:
        - PURPOSE_RESALE
        - ENTITY_TYPE_NONPROFIT
        - GOVERNMENT
        - MANUFACTURER
        - AGRICULTURAL
        - OTHER
        - EXEMPT_PRODUCT
      description: Enum representing the reason for the exemption.
    IsExemptionActive:
      type: boolean
      description: |
        Indicates whether the exemption should be taken into account when performing tax calculations.  When `true`, applicable transactions will be exempted from tax (unless the certificate is expired).
    ExemptionIdentificationType:
      type: string
      enum:
        - FEIN
        - TIN
        - DL
        - OTHER
      description: Enum representing the type of identification number used for the exemption. Federal EIN, Taxpayer Id Number, or Drivers License are common values for this field. "Other" is also accepted.
    JurisdictionExemption:
      type: object
      properties:
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
        state:
          type: string
          description: ISO 3166-2 subdivision code.
        reason:
          $ref: '#/components/schemas/ExemptionReason'
        is_active:
          $ref: '#/components/schemas/IsExemptionActive'
        end_date:
          type: string
          format: date
          nullable: true
          description: ISO 8601 formatted date string indicating the expiration date of this particular exemption. For multistate exemption certificates, the expiration date can be different in different states..
        identification_type:
          $ref: '#/components/schemas/ExemptionIdentificationType'
        identification_number:
          type: string
          description: Identification number for the exemption.
        is_expired:
          type: boolean
          description: Indicates if the exemption is expired.
        created_at:
          type: integer
          format: int64
          description: Timestamp in UTC when this jurisdiction exemption was created.
    ExemptionCertificateResponse:
      type: object
      properties:
        customer_id:
          type: string
          format: uuid
          description: The unique identifier of the customer.
        file_id:
          type: string
          format: uuid
          nullable: true
          description: Identifier of the file to use as the exemption certificate.
        type:
          $ref: '#/components/schemas/ExemptionCertificateType'
        verification_status:
          type: string
          description: Verification status of the exemption certificate.
        exemption_certificate_number:
          type: string
          description: The exemption certificate number.
        effective_date:
          type: string
          format: date
          description: ISO 8601 formatted date string indicating the effective date.
        created_at:
          type: integer
          format: int64
          description: Timestamp in UTC when this exemption certificate was created.
        jurisdictions:
          type: array
          items:
            $ref: '#/components/schemas/JurisdictionExemption'
          description: List of jurisdictions where the exemption is applicable.
    CreateExemptionRequest:
      type: object
      required:
        - identification_type
        - identification_number
        - country
        - state
        - reason
      properties:
        identification_type:
          $ref: '#/components/schemas/ExemptionIdentificationType'
        identification_number:
          type: string
          description: Identification number for the exemption.
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
        state:
          type: string
          description: ISO 3166-2 subdivision code.
        reason:
          $ref: '#/components/schemas/ExemptionReason'
        end_date:
          type: string
          format: date
          description: ISO 8601 formatted date string indicating the expiration date of this particular exemption. For multistate exemption certificates, the expiration date can be different in different states..
        is_active:
          $ref: '#/components/schemas/IsExemptionActive'
    CreateExemptionCertificateRequest:
      type: object
      required:
        - customer_id
        - effective_date
        - type
        - jurisdictions
      properties:
        customer_id:
          type: string
          description: The unique identifier of the customer.
        file_id:
          type: string
          description: Identifier of the file to use as the exemption certificate.
        effective_date:
          type: string
          format: date
          description: ISO 8601 formatted date string indicating the effective date.
        type:
          $ref: '#/components/schemas/ExemptionCertificateType'
        exemption_certificate_number:
          type: string
          maxLength: 20
          description: The exemption certificate number.
        jurisdictions:
          type: array
          items:
            $ref: '#/components/schemas/CreateExemptionRequest'
    FileInfo:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the file
        name:
          type: string
          example: example.pdf
          description: File name.
        size:
          type: number
          description: File size (bytes)
          example: 102400
        corporation_id:
          type: string
          description: The unique identifier for a corporation associated with this file.
    AffiliateCompany:
      type: object
      required:
        - companyId
        - name
        - createdAt
        - updatedAt
      properties:
        companyId:
          type: integer
          description: Internal Commenda company identifier.
          example: 77
        name:
          type: string
          nullable: true
          description: Display name for the company.
          example: Acme Holdings
        createdAt:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the company container was created.
          example: '2026-04-20T19:35:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the company container was last updated.
          example: '2026-04-20T19:40:00.000Z'
    AffiliateListCompaniesResponse:
      type: object
      required:
        - companies
        - count
      properties:
        companies:
          type: array
          items:
            $ref: '#/components/schemas/AffiliateCompany'
        count:
          type: integer
          example: 1
    AffiliatePublicError:
      type: object
      required:
        - statusCode
        - message
        - error
      properties:
        statusCode:
          type: integer
          example: 403
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: Company does not belong to this affiliate firm
        error:
          type: string
          example: Forbidden
    AffiliateCreateCompanyRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: Email address for the new company owner.
          example: founder@example.com
        name:
          type: string
          description: Optional display name used when creating a new company.
          example: Acme Holdings
    AffiliateCreateCompanyResponse:
      type: object
      required:
        - companyId
      properties:
        companyId:
          type: integer
          description: Internal Commenda company identifier.
          example: 77
    AffiliateServiceCatalog:
      type: string
      description: Incorporation service types currently supported by the legacy affiliate API.
      enum:
        - US_CCORP_INCORPORATION
        - US_LLC_INCORPORATION
        - CA_CORP_INCORPORATION
        - INDIA_PVT_LTD_INCORPORATION
        - INDIA_LLP_INCORPORATION
        - UAE_INCORPORATION
        - UK_INCORPORATION
        - IE_INCORPORATION
        - SG_INCORPORATION
    AffiliateCreateServiceRequest:
      type: object
      required:
        - companyId
        - serviceType
      properties:
        companyId:
          type: integer
          description: Company that the new incorporation service should be attached to.
          example: 77
        serviceType:
          $ref: '#/components/schemas/AffiliateServiceCatalog'
    AffiliateCreateServiceResponse:
      type: object
      required:
        - paymentIntentId
      properties:
        paymentIntentId:
          type: string
          description: Identifier for the newly created payment intent that anchors the current public flow.
          example: pi_123
    PartnerCustomer:
      type: object
      required:
        - id
        - name
        - createdAt
        - updatedAt
      properties:
        id:
          type: integer
          description: Commenda customer identifier.
          example: 77
        name:
          type: string
          nullable: true
          description: Display name for the customer.
          example: Acme Holdings
        createdAt:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the customer record was created.
          example: '2026-04-20T19:35:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the customer record was last updated.
          example: '2026-04-20T19:40:00.000Z'
    PartnerListCustomersResponse:
      type: object
      required:
        - customers
        - count
      properties:
        customers:
          type: array
          items:
            $ref: '#/components/schemas/PartnerCustomer'
        count:
          type: integer
          example: 1
    PartnerCreateCustomerRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: Email address for the customer owner.
          example: founder@example.com
        name:
          type: string
          description: Optional display name for the customer record.
          example: Acme Holdings
    PartnerCreateCustomerResponse:
      type: object
      required:
        - customer
      properties:
        customer:
          $ref: '#/components/schemas/PartnerCustomer'
    PartnerIncorporationCountry:
      type: string
      description: ISO 3166-1 alpha-2 country code for the incorporation jurisdiction.
      example: SG
      enum:
        - AE
        - CA
        - GB
        - IE
        - IN
        - KY
        - NZ
        - SG
        - US
    PartnerJurisdictionCatalogField:
      type: object
      required:
        - key
        - type
        - required
      properties:
        key:
          type: string
          description: Path to send inside `countryOptions`. Simple keys become direct properties, such as `countryOptions.corporationType`; dotted keys represent nested objects, such as `countryOptions.corporationTypeOptions.freeZone`.
          example: corporationType
        type:
          type: string
          enum:
            - select
          example: select
        required:
          type: boolean
          example: true
        options:
          type: array
          description: Accepted values for this field.
          items:
            type: string
          example:
            - CORPORATION
            - LLC
    PartnerJurisdictionCatalogCountry:
      type: object
      required:
        - country
        - fields
      properties:
        country:
          $ref: '#/components/schemas/PartnerIncorporationCountry'
        fields:
          type: array
          items:
            $ref: '#/components/schemas/PartnerJurisdictionCatalogField'
    PartnerJurisdictionCatalogResponse:
      type: object
      required:
        - countries
      properties:
        countries:
          type: array
          items:
            $ref: '#/components/schemas/PartnerJurisdictionCatalogCountry'
    PartnerIncorporationCountryOptions:
      type: object
      description: Country-specific incorporation options. Use the jurisdiction catalog for the currently supported fields and values.
      additionalProperties: true
      example:
        corporationType: PRIVATE_LIMITED_COMPANY
    PartnerIncorporationRequirements:
      type: object
      description: Requirements schema for the selected incorporation. Clients can use this to render their own intake UI, but intake updates are always validated against the current server-side incorporation requirements.
      additionalProperties: true
      example:
        schemaVersion: '2026-04-22'
        dslVersion: mvp-2026-04-22
        key: sg.private_limited_company
        country: SG
        countryOptions:
          corporationType: PRIVATE_LIMITED_COMPANY
        name: Singapore Private Limited Company Incorporation Requirements
        blocks:
          - key: companyNames
            name: Company name options
        participantRequirements:
          - key: directors
            name: Directors
            role: DIRECTOR
            allowedParticipantTypes:
              - INDIVIDUAL
            allowedResourceTypes:
              - KEY_PERSON
            resourceFieldsByParticipantType:
              INDIVIDUAL:
                - kind: resource
                  key: residentialAddress
                  name: Residential address
                  description: The key person's current residential address. Store this on the Commenda OS person as residentialAddress.
                  required: true
                  resourceKind: address
                  commendaOs:
                    entity: keyPerson
                    field: residentialAddress
                  fields:
                    - kind: scalar
                      key: addressLine1
                      name: Address line 1
                      required: true
                      commendaOs:
                        entity: keyPerson
                        field: residentialAddress.addressLine1
                    - kind: scalar
                      key: city
                      name: City
                      required: true
                      commendaOs:
                        entity: keyPerson
                        field: residentialAddress.city
                    - kind: scalar
                      key: country
                      name: Country
                      required: true
                      commendaOs:
                        entity: keyPerson
                        field: residentialAddress.country
            documentRequirements:
              - documentKind: PASSPORT_SCAN
                name: Passport scan
              - documentKind: UTILITY_BILL
                name: Utility bill
    PartnerRequirementsResponse:
      type: object
      required:
        - requirements
      properties:
        requirements:
          $ref: '#/components/schemas/PartnerIncorporationRequirements'
    PartnerIncorporationStatusStageOwner:
      type: string
      description: Party expected to own work in a public status stage.
      enum:
        - PARTNER
        - CUSTOMER
        - COMMENDA
    PartnerIncorporationStatusWorkflowStage:
      type: object
      required:
        - id
        - label
        - description
        - owner
        - position
      properties:
        id:
          type: string
          description: Stable stage identifier. Issue scopes may reference this as `stageId`.
          example: kyc
        label:
          type: string
          example: KYC
        description:
          type: string
          example: Review required identity, ownership, and compliance materials.
        owner:
          $ref: '#/components/schemas/PartnerIncorporationStatusStageOwner'
        position:
          type: integer
          description: One-based display order.
          example: 2
    PartnerIncorporationStatusWorkflow:
      type: object
      required:
        - schemaVersion
        - definitionVersion
        - key
        - country
        - countryOptions
        - name
        - description
        - stages
      properties:
        schemaVersion:
          type: string
          description: Public status workflow schema version.
          example: '2026-04-26'
        definitionVersion:
          type: string
          description: Active workflow definition version used to produce this public workflow.
          example: 1.0.0
        key:
          type: string
          description: Workflow template key.
          example: singapore-incorporation-partner-api
        country:
          $ref: '#/components/schemas/PartnerIncorporationCountry'
        countryOptions:
          $ref: '#/components/schemas/PartnerIncorporationCountryOptions'
        name:
          type: string
          example: Singapore Private Limited Company Incorporation
        description:
          type: string
          example: Track the public progress of a Singapore private limited company incorporation.
        stages:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporationStatusWorkflowStage'
    PartnerIncorporationStatusWorkflowResponse:
      type: object
      required:
        - statusWorkflow
      properties:
        statusWorkflow:
          $ref: '#/components/schemas/PartnerIncorporationStatusWorkflow'
    PartnerIncorporationStatus:
      type: string
      description: Current top-level lifecycle status for the incorporation.
      enum:
        - AWAITING_CUSTOMER_INPUT
        - SUBMITTED
        - IN_PROGRESS
        - BLOCKED
        - COMPLETED
    PartnerIncorporation:
      type: object
      required:
        - id
        - customerId
        - country
        - countryOptions
        - incorporationStatus
        - createdAt
        - updatedAt
        - businessEntityId
      properties:
        id:
          type: string
          description: Incorporation identifier.
          example: 0f9a8f5e-7f7c-4c1b-a60a-b1022f9d8c91
        customerId:
          type: integer
          description: Customer that owns the incorporation.
          example: 77
        country:
          $ref: '#/components/schemas/PartnerIncorporationCountry'
        countryOptions:
          $ref: '#/components/schemas/PartnerIncorporationCountryOptions'
        incorporationStatus:
          $ref: '#/components/schemas/PartnerIncorporationStatus'
        createdAt:
          type: string
          format: date-time
          example: '2026-04-21T17:10:00.000Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-04-21T17:10:00.000Z'
        businessEntityId:
          type: integer
          nullable: true
          description: Target Commenda business entity id for the entity being incorporated. Corporate shareholder business entity ids are separate participant resource ids.
          example: 44
    PartnerIncorporationListResponse:
      type: object
      required:
        - incorporations
        - count
      properties:
        incorporations:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporation'
        count:
          type: integer
          description: Total matching incorporations before pagination.
          example: 1
    PartnerIncorporationRequirementValues:
      type: object
      description: Partner-submitted requirement values keyed by requirements field keys.
      additionalProperties: true
      example:
        companyNameOptions:
          - name: Acme SG Pte Ltd
          - name: Acme Asia Pte Ltd
          - name: Acme Global Pte Ltd
        registeredOfficeAddressSource: commendaService
    PartnerCreateCustomerScopedIncorporationRequest:
      type: object
      required:
        - country
        - countryOptions
      properties:
        country:
          $ref: '#/components/schemas/PartnerIncorporationCountry'
        countryOptions:
          $ref: '#/components/schemas/PartnerIncorporationCountryOptions'
        intake:
          type: object
          description: Optional initial partial intake data.
          properties:
            requirements:
              $ref: '#/components/schemas/PartnerIncorporationRequirementValues'
    PartnerIncorporationDocumentKind:
      type: string
      description: Type of document linked to an incorporation participant.
      enum:
        - PASSPORT_SCAN
        - UTILITY_BILL
    PartnerIncorporationValidationIssue:
      type: object
      required:
        - code
        - path
        - message
      properties:
        code:
          type: string
          description: Stable machine-readable validation issue code.
          example: PARTICIPANT_DOCUMENT_REQUIRED
        path:
          type: string
          description: Dot/bracket path for the missing or invalid requirement.
          example: participants.participant_123.documents.PASSPORT_SCAN
        message:
          type: string
          example: Participant participant_123 requires a PASSPORT_SCAN document
        participantId:
          type: string
          description: Included when the issue belongs to a participant.
          example: participant_123
        documentKind:
          $ref: '#/components/schemas/PartnerIncorporationDocumentKind'
        displayName:
          type: string
          description: Included when available so UIs can render useful labels without joining across responses.
          example: Jane Founder
    PartnerIncorporationValidationSummary:
      type: object
      required:
        - isComplete
        - missingRequirements
        - invalidRequirements
      properties:
        isComplete:
          type: boolean
          description: True when the current intake state satisfies the current incorporation requirements and is eligible to submit for review.
          example: false
        missingRequirements:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporationValidationIssue'
        invalidRequirements:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporationValidationIssue'
    PartnerIncorporationIntakeState:
      type: object
      required:
        - id
        - incorporationId
        - currentState
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: state_123
        incorporationId:
          type: string
          example: 0f9a8f5e-7f7c-4c1b-a60a-b1022f9d8c91
        currentState:
          $ref: '#/components/schemas/PartnerIncorporationRequirementValues'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PartnerIncorporationParticipantType:
      type: string
      description: Type of reusable Commenda OS resource registered to the incorporation.
      enum:
        - INDIVIDUAL
        - CORPORATE
    PartnerIncorporationParticipantResourceType:
      type: string
      description: Commenda OS resource type represented by this participant.
      enum:
        - KEY_PERSON
        - BUSINESS_ENTITY
    PartnerIncorporationParticipantResource:
      type: object
      required:
        - resourceType
        - resourceId
      properties:
        resourceType:
          $ref: '#/components/schemas/PartnerIncorporationParticipantResourceType'
        resourceId:
          type: integer
          description: Numeric Commenda OS identifier. For `KEY_PERSON`, use the person id returned by Commenda OS. For `BUSINESS_ENTITY`, use the business entity id.
          example: 12
    PartnerIncorporationParticipantRoleName:
      type: string
      description: Role the participant holds in this incorporation.
      enum:
        - DIRECTOR
        - SHAREHOLDER
    PartnerIncorporationParticipantRole:
      type: object
      required:
        - role
      properties:
        role:
          $ref: '#/components/schemas/PartnerIncorporationParticipantRoleName'
        ownershipPercentage:
          type: number
          description: Required when the participant has a shareholder role and ownership is represented by percentage. Participant writes are rejected if shareholder ownership would exceed the selected requirements total.
          minimum: 0
          maximum: 100
          example: 100
    PartnerIncorporationParticipantDocumentStatus:
      type: string
      description: Current status of the participant document link.
      enum:
        - SUBMITTED
    PartnerIncorporationParticipantDocument:
      type: object
      required:
        - documentId
        - participantId
        - documentKind
        - fileId
        - status
      properties:
        documentId:
          type: string
          description: Identifier for this participant document link.
          example: document_123
        participantId:
          type: string
          description: Participant this document belongs to.
          example: participant_123
        documentKind:
          $ref: '#/components/schemas/PartnerIncorporationDocumentKind'
        fileId:
          type: integer
          description: Commenda file satisfying this document requirement.
          example: 456
        status:
          $ref: '#/components/schemas/PartnerIncorporationParticipantDocumentStatus'
    PartnerIncorporationParticipant:
      type: object
      required:
        - id
        - participantType
        - resource
        - roles
        - documents
      properties:
        id:
          type: string
          description: Incorporation-specific participant identifier.
          example: participant_123
        participantType:
          $ref: '#/components/schemas/PartnerIncorporationParticipantType'
        resource:
          $ref: '#/components/schemas/PartnerIncorporationParticipantResource'
        roles:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporationParticipantRole'
        documents:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporationParticipantDocument'
      example:
        id: participant_123
        participantType: INDIVIDUAL
        resource:
          resourceType: KEY_PERSON
          resourceId: 12
        roles:
          - role: DIRECTOR
          - role: SHAREHOLDER
            ownershipPercentage: 100
        documents:
          - documentId: document_123
            participantId: participant_123
            documentKind: PASSPORT_SCAN
            fileId: 456
            status: SUBMITTED
          - documentId: document_124
            participantId: participant_123
            documentKind: UTILITY_BILL
            fileId: 789
            status: SUBMITTED
    PartnerIncorporationResponse:
      type: object
      required:
        - incorporation
        - incorporationValidation
        - intakeState
        - participants
      properties:
        incorporation:
          $ref: '#/components/schemas/PartnerIncorporation'
        incorporationValidation:
          $ref: '#/components/schemas/PartnerIncorporationValidationSummary'
        requirements:
          $ref: '#/components/schemas/PartnerIncorporationRequirements'
        intakeState:
          description: Current intake state for the incorporation. Always returned; an empty intake state is initialized automatically when one does not yet exist.
          $ref: '#/components/schemas/PartnerIncorporationIntakeState'
        participants:
          type: array
          description: Participants registered to this incorporation, when requested or available.
          items:
            $ref: '#/components/schemas/PartnerIncorporationParticipant'
    PartnerIncorporationStatusWorkflowSummary:
      type: object
      required:
        - schemaVersion
        - definitionVersion
        - key
      properties:
        schemaVersion:
          type: string
          example: '2026-04-26'
        definitionVersion:
          type: string
          example: 1.0.0
        key:
          type: string
          example: singapore-incorporation-partner-api
    PartnerIncorporationStageStatus:
      type: string
      description: Public progress status for one incorporation workflow stage.
      enum:
        - NOT_STARTED
        - IN_PROGRESS
        - BLOCKED
        - COMPLETED
    PartnerIncorporationStatusStage:
      type: object
      required:
        - id
        - label
        - description
        - owner
        - position
        - status
        - startedAt
        - completedAt
        - blockedByIssueIds
      properties:
        id:
          type: string
          description: Stable stage identifier. Issue scopes reference this value as `scope.stageId`.
          example: kyc
        label:
          type: string
          description: Human-readable stage label.
          example: KYC
        description:
          type: string
          description: Human-readable explanation of the stage.
          example: Review required identity, ownership, and compliance materials.
        owner:
          $ref: '#/components/schemas/PartnerIncorporationStatusStageOwner'
        position:
          type: integer
          description: One-based display order.
          example: 2
        status:
          $ref: '#/components/schemas/PartnerIncorporationStageStatus'
        startedAt:
          type: string
          format: date-time
          nullable: true
          example: '2026-04-26T19:05:00.000Z'
        completedAt:
          type: string
          format: date-time
          nullable: true
          example: null
        blockedByIssueIds:
          type: array
          description: Active issue ids blocking this stage.
          items:
            type: string
          example:
            - issue_123
    PartnerIncorporationStatusResponse:
      type: object
      required:
        - incorporationStatus
        - incorporationId
        - customerId
        - country
        - countryOptions
        - statusWorkflow
        - blockingIssueIds
        - blockingIssueCount
        - stages
        - updatedAt
      properties:
        incorporationStatus:
          $ref: '#/components/schemas/PartnerIncorporationStatus'
        incorporationId:
          type: string
          example: 0f9a8f5e-7f7c-4c1b-a60a-b1022f9d8c91
        customerId:
          type: integer
          example: 77
        country:
          $ref: '#/components/schemas/PartnerIncorporationCountry'
        countryOptions:
          $ref: '#/components/schemas/PartnerIncorporationCountryOptions'
        statusWorkflow:
          $ref: '#/components/schemas/PartnerIncorporationStatusWorkflowSummary'
        blockingIssueIds:
          type: array
          description: Active partner-visible issue ids currently blocking the incorporation.
          items:
            type: string
          example:
            - issue_123
        blockingIssueCount:
          type: integer
          example: 1
        stages:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporationStatusStage'
        updatedAt:
          type: string
          format: date-time
          example: '2026-04-26T19:15:00.000Z'
    PartnerIncorporationValidationResponse:
      type: object
      required:
        - incorporationValidation
      properties:
        incorporationValidation:
          $ref: '#/components/schemas/PartnerIncorporationValidationSummary'
    PartnerUpdateIntakeRequest:
      type: object
      required:
        - requirements
      properties:
        requirements:
          $ref: '#/components/schemas/PartnerIncorporationRequirementValues'
    PartnerIncorporationIntakeResponse:
      type: object
      required:
        - intakeState
        - incorporationValidation
        - requirements
      properties:
        intakeState:
          $ref: '#/components/schemas/PartnerIncorporationIntakeState'
        incorporationValidation:
          $ref: '#/components/schemas/PartnerIncorporationValidationSummary'
        requirements:
          $ref: '#/components/schemas/PartnerIncorporationRequirements'
    PartnerIncorporationSubmitError:
      type: object
      required:
        - statusCode
        - message
        - error
        - incorporationValidation
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          type: string
          example: Incorporation intake is incomplete and cannot be submitted for review
        error:
          type: string
          example: Bad Request
        incorporationValidation:
          $ref: '#/components/schemas/PartnerIncorporationValidationSummary'
    PartnerIncorporationParticipantsResponse:
      type: object
      required:
        - participants
        - count
      properties:
        participants:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporationParticipant'
        count:
          type: integer
          description: Number of participants returned.
          example: 1
    PartnerRegisterParticipantRequest:
      type: object
      required:
        - participantType
        - resource
        - roles
      properties:
        participantType:
          $ref: '#/components/schemas/PartnerIncorporationParticipantType'
        resource:
          $ref: '#/components/schemas/PartnerIncorporationParticipantResource'
        roles:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/PartnerIncorporationParticipantRole'
      example:
        participantType: INDIVIDUAL
        resource:
          resourceType: KEY_PERSON
          resourceId: 12
        roles:
          - role: DIRECTOR
          - role: SHAREHOLDER
            ownershipPercentage: 100
    PartnerIncorporationParticipantMutationResponse:
      type: object
      required:
        - participant
        - incorporationValidation
      properties:
        participant:
          $ref: '#/components/schemas/PartnerIncorporationParticipant'
        incorporationValidation:
          $ref: '#/components/schemas/PartnerIncorporationValidationSummary'
    PartnerIncorporationParticipantRemovalResponse:
      type: object
      required:
        - participantId
        - incorporationValidation
      properties:
        participantId:
          type: string
          description: Incorporation-specific participant identifier that was removed.
          example: participant_123
        incorporationValidation:
          $ref: '#/components/schemas/PartnerIncorporationValidationSummary'
    PartnerPatchParticipantRequest:
      type: object
      description: Partially updates an existing incorporation participant. Provide `roles`, `resource`, or both. At least one of the two fields is required. When `roles` is provided, the supplied array fully replaces the existing roles and any omitted roles are removed. When `resource` is provided, the participant is re-pointed at a different Commenda OS person or business entity.
      properties:
        resource:
          allOf:
            - $ref: '#/components/schemas/PartnerIncorporationParticipantResource'
          description: Reusable Commenda OS resource the participant should reference. Provide this when correcting which person or business entity is registered as this participant. The new resource must not already be registered as another participant on the same incorporation.
        roles:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/PartnerIncorporationParticipantRole'
          description: Full replacement set of roles for the participant. Omitted roles are removed.
      example:
        roles:
          - role: DIRECTOR
          - role: SHAREHOLDER
            ownershipPercentage: 40
    PartnerUpsertParticipantDocumentRequest:
      type: object
      required:
        - fileId
      properties:
        fileId:
          type: integer
          description: Existing customer-scoped Commenda file id to assign to the participant document slot.
          example: 456
      example:
        fileId: 456
    PartnerIncorporationParticipantDocumentMutationResponse:
      type: object
      required:
        - document
        - incorporationValidation
      properties:
        document:
          $ref: '#/components/schemas/PartnerIncorporationParticipantDocument'
        incorporationValidation:
          $ref: '#/components/schemas/PartnerIncorporationValidationSummary'
    AffiliatePaymentIntentStatus:
      type: string
      enum:
        - PENDING
        - COLLECTED
    AffiliatePaymentIntent:
      type: object
      required:
        - paymentIntentId
        - serviceRequestURL
      properties:
        paymentIntentId:
          type: string
          example: pi_123
        serviceRequestURL:
          type: string
          nullable: true
          description: App URL for the linked service request, if one exists.
          example: https://app.commenda.io/service-request/sr_123
    AffiliateListPaymentIntentsResponse:
      type: object
      required:
        - paymentIntents
      properties:
        paymentIntents:
          type: array
          items:
            $ref: '#/components/schemas/AffiliatePaymentIntent'
    AffiliateServiceRequestStep:
      type: object
      required:
        - name
        - status
        - createdAt
        - lastUpdatedAt
      properties:
        name:
          type: string
          example: Formation documents
        status:
          type: string
          enum:
            - NOT_STARTED
            - IN_PROGRESS
            - COMPLETED
            - ISSUE_REPORTED
        createdAt:
          type: string
          format: date-time
          example: '2026-03-01T00:00:00.000Z'
        lastUpdatedAt:
          type: string
          format: date-time
          example: '2026-03-02T00:00:00.000Z'
    AffiliateServiceRequest:
      type: object
      required:
        - id
        - corporationId
        - companyLegalName
        - steps
      properties:
        id:
          type: string
          example: sr_123
        corporationId:
          type: integer
          nullable: true
          example: 44
        companyLegalName:
          type: string
          nullable: true
          example: Acme LLC
        steps:
          type: array
          items:
            $ref: '#/components/schemas/AffiliateServiceRequestStep'
    AffiliatePaymentIntentServiceStatusResponse:
      type: object
      required:
        - paymentIntentId
        - service
      properties:
        paymentIntentId:
          type: string
          example: pi_123
        service:
          $ref: '#/components/schemas/AffiliateServiceRequest'
    AffiliateDocumentCategory:
      type: string
      enum:
        - FORMATION_DOCUMENT
        - SHAREHOLDER_DOCUMENT
        - TAX_AND_COMPLIANCE_DOCUMENT
        - FINANCIAL_RECORDS
        - OFFICE_AND_ADMINISTRATION_DOCUMENT
        - CONTRACTS_AND_AGREEMENTS
        - MISCELLANEOUS
    AffiliateDocument:
      type: object
      required:
        - fileId
        - documentName
        - documentType
        - documentSubType
        - country
        - jurisdiction
        - corporationType
        - corporationId
      properties:
        fileId:
          type: integer
          nullable: true
          description: Latest uploaded file id for this document slot, if available.
          example: 900
        documentName:
          type: string
          example: Operating Agreement
        documentType:
          $ref: '#/components/schemas/AffiliateDocumentCategory'
        documentSubType:
          type: string
          description: Legacy Commenda document subtype used internally for document rules and files.
          example: OperatingAgreement
        country:
          type: string
          example: US
        jurisdiction:
          type: string
          nullable: true
          example: DE
        corporationType:
          type: string
          nullable: true
          example: LLC
        corporationId:
          type: integer
          example: 44
    AffiliateListDocumentsResponse:
      type: object
      required:
        - documents
        - count
      properties:
        documents:
          type: array
          items:
            $ref: '#/components/schemas/AffiliateDocument'
        count:
          type: integer
          example: 2
    AffiliateFileSignedUrlResponse:
      type: object
      required:
        - signedUrl
      properties:
        signedUrl:
          type: string
          format: uri
          description: Temporary signed download URL for the file.
          example: https://bucket.s3.amazonaws.com/file.pdf?X-Amz-Signature=example
    CommendaOsUniqueIdentifierFromJurisdiction:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: EIN
        value:
          type: string
          nullable: true
          example: 12-3456789
    CommendaOsTaxId:
      type: object
      required:
        - type
        - name
        - value
      properties:
        type:
          type: string
          example: US_EIN
        name:
          type: string
          example: Employer Identification Number
        value:
          type: string
          example: 12-3456789
    CommendaOsLocationAddress:
      type: object
      required:
        - addressLine1
        - postalCode
        - country
      properties:
        addressLine1:
          type: string
          example: 548 Market St
        addressLine2:
          type: string
          nullable: true
          example: Suite 21045
        addressLine3:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
          example: San Francisco
        postalCode:
          type: string
          example: '94104'
        state:
          type: string
          nullable: true
          example: CA
        country:
          type: string
          example: US
    CommendaOsLocation:
      type: object
      required:
        - id
        - businessEntityId
        - locationTypes
        - address
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: loc_123
        name:
          type: string
          nullable: true
          example: Delaware HQ
        startDate:
          type: string
          nullable: true
          example: '2025-01-01'
        employeeCount:
          type: integer
          nullable: true
          example: 12
        businessEntityId:
          type: integer
          example: 44
        locationTypes:
          type: array
          items:
            type: string
          example:
            - OPERATIONS
        address:
          $ref: '#/components/schemas/CommendaOsLocationAddress'
        createdAt:
          type: integer
          example: 1735689600000
        updatedAt:
          type: integer
          example: 1735776000000
    CommendaOsGovernmentIdentifierSupportingDocument:
      type: object
      required:
        - id
        - fileName
        - fileUrl
        - type
        - category
        - fileTypeSpecifiers
      properties:
        id:
          type: integer
          nullable: true
          example: 900
        fileName:
          type: string
          example: ein-letter.pdf
        fileUrl:
          type: string
          nullable: true
          format: uri
          example: https://bucket.s3.amazonaws.com/ein-letter.pdf
        type:
          type: string
          example: EINLetter
        category:
          type: string
          example: TAX_AND_COMPLIANCE_DOCUMENT
        fileTypeSpecifiers:
          type: array
          items:
            type: string
          example:
            - .pdf
    CommendaOsLinkedRegistrationOption:
      type: object
      required:
        - internalIdentifier
        - displayName
        - purpose
      properties:
        internalIdentifier:
          type: string
          example: US_EIN
        displayName:
          type: string
          example: Employer Identification Number
        purpose:
          type: string
          example: TAXATION
    CommendaOsGovernmentIdentifier:
      type: object
      required:
        - country
        - businessEntityId
        - corporationType
        - key
        - displayName
        - shortName
        - description
        - purposes
        - supportingDocument
        - isFunctionCritical
        - isCustom
        - linkedRegistrations
      properties:
        id:
          type: string
          nullable: true
          example: gov_123
        country:
          type: string
          example: US
        jurisdiction:
          type: string
          nullable: true
          example: DE
        businessEntityId:
          type: integer
          example: 44
        corporationType:
          type: string
          example: LLC
        key:
          type: string
          example: US_EIN
        value:
          type: string
          nullable: true
          example: 12-3456789
        displayName:
          type: string
          example: Employer Identification Number
        shortName:
          type: string
          example: EIN
        description:
          type: string
          example: US federal tax identifier issued by the IRS.
        purposes:
          type: array
          items:
            type: string
          example:
            - TAXATION
        supportingDocument:
          $ref: '#/components/schemas/CommendaOsGovernmentIdentifierSupportingDocument'
        isFunctionCritical:
          type: boolean
          example: true
        createdAt:
          type: integer
          nullable: true
          example: 1735689600000
        lastUpdatedAt:
          type: integer
          nullable: true
          example: 1735776000000
        regexString:
          type: string
          nullable: true
        isCustom:
          type: boolean
          example: false
        linkedRegistrations:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsLinkedRegistrationOption'
    CommendaOsBusinessEntity:
      type: object
      required:
        - id
        - generalBusinessEntityInfo
        - accountingInfo
        - featureSpecificInfo
        - entityRelationship
        - lastUpdateTime
      properties:
        id:
          type: integer
          example: 44
        generalBusinessEntityInfo:
          type: object
          required:
            - legalName
            - customerId
            - businessEntityType
            - incorporationCountry
            - jurisdiction
            - uniqueIdentifierFromJurisdiction
            - primaryTaxIdType
            - rootfiCompanies
          properties:
            legalName:
              type: string
              example: Acme Holdings LLC
            dbaName:
              type: string
              nullable: true
              example: Acme
            customerId:
              type: integer
              example: 77
            formationDate:
              type: string
              nullable: true
              example: '2025-01-01'
            registeredAddress:
              type: object
              additionalProperties: true
            businessEntityType:
              type: string
              example: LLC
            incorporationCountry:
              type: string
              example: US
            jurisdiction:
              type: string
              example: DE
            contactPhone:
              type: string
              nullable: true
              example: '+14155550123'
            entityEmail:
              type: string
              nullable: true
              format: email
              example: founders@acme.com
            uniqueIdentifierFromJurisdiction:
              $ref: '#/components/schemas/CommendaOsUniqueIdentifierFromJurisdiction'
            taxIds:
              type: array
              items:
                $ref: '#/components/schemas/CommendaOsTaxId'
            primaryTaxIdType:
              type: string
              example: US_EIN
            publicFacingWebsiteUrl:
              type: string
              nullable: true
              format: uri
              example: https://acme.com
            industryCode:
              type: object
              nullable: true
              additionalProperties: true
            businessDescription:
              type: string
              nullable: true
            businessPurpose:
              type: string
              nullable: true
            registeredAgent:
              type: object
              nullable: true
              additionalProperties: true
            dateOfClosure:
              type: string
              nullable: true
            rootfiCompanies:
              type: array
              items:
                type: object
                required:
                  - id
                  - connectionStatus
                  - syncStatus
                properties:
                  id:
                    type: integer
                    example: 1001
                  connectionStatus:
                    type: string
                    example: CONNECTED
                  syncStatus:
                    type: string
                    example: COMPLETED
        locationsInfo:
          type: object
          nullable: true
          additionalProperties: true
        accountingInfo:
          type: object
          properties:
            fiscalYear:
              type: object
              nullable: true
              additionalProperties: true
            accountingBasis:
              type: string
              nullable: true
            accountingFrequency:
              type: string
              nullable: true
            countrySpecificFields:
              type: object
              additionalProperties: true
            bankAccounts:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
            accountingFirm:
              type: object
              nullable: true
              additionalProperties: true
        stakeholderId:
          type: string
          nullable: true
        featureSpecificInfo:
          type: object
          additionalProperties: true
        onboardingInfo:
          type: object
          nullable: true
          additionalProperties: true
        entityRelationship:
          type: object
          additionalProperties: true
        structure:
          type: object
          nullable: true
          properties:
            initialSharesAuthorized:
              type: number
            initialSharePrice:
              type: number
            esopSharePercentage:
              type: number
        locations:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsLocation'
        governmentIdentifiers:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsGovernmentIdentifier'
        lastUpdateTime:
          type: string
          format: date-time
          example: '2026-03-01T00:00:00.000Z'
    CommendaOsBusinessEntityListResponse:
      type: object
      required:
        - businessEntities
        - count
      properties:
        businessEntities:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsBusinessEntity'
        count:
          type: integer
          example: 2
    CommendaOsPartnerError:
      type: object
      required:
        - statusCode
        - message
        - error
      properties:
        statusCode:
          type: integer
          description: HTTP status code for the error response.
        message:
          description: Error message returned by the API. Exact text varies by failure mode.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        error:
          type: string
          description: Standard error label for the response status.
    CommendaOsBusinessEntityCreateRequest:
      type: object
      description: Create a reusable Commenda OS business entity for one of your customers. Use the returned `businessEntity.id` as a `BUSINESS_ENTITY` resource id when registering corporate incorporation participants.
      required:
        - incorporationCountry
        - legalName
        - jurisdiction
        - corporationType
      properties:
        incorporationCountry:
          type: string
          description: ISO country code for the entity's incorporation country.
          example: SG
        legalName:
          type: string
          minLength: 1
          maxLength: 1024
          example: Acme Holdings Pte. Ltd.
        jurisdiction:
          type: string
          description: Commenda jurisdiction enum for the entity. Singapore private limited companies use `JUR_SG__GENERAL`.
          example: JUR_SG__GENERAL
        corporationType:
          type: string
          description: Commenda corporation type enum for the entity.
          example: PteLtd
        formationDate:
          type: string
          format: date
          description: Entity formation date when already known.
          example: '2020-03-15'
        isIncorporationInProgress:
          type: boolean
          description: Whether this entity is still being incorporated in Commenda.
          example: false
      example:
        incorporationCountry: SG
        legalName: Acme Holdings Pte. Ltd.
        jurisdiction: JUR_SG__GENERAL
        corporationType: PteLtd
        formationDate: '2020-03-15'
        isIncorporationInProgress: false
    CommendaOsBusinessEntityResponse:
      type: object
      required:
        - businessEntity
      properties:
        businessEntity:
          $ref: '#/components/schemas/CommendaOsBusinessEntity'
    CommendaOsBusinessEntityUpdateRequest:
      type: object
      description: Partially update a reusable Commenda OS business entity. Omitted fields are left unchanged.
      properties:
        legalName:
          type: string
          minLength: 1
          maxLength: 1024
          example: Acme Holdings Pte. Ltd.
        dbaName:
          type: string
          minLength: 1
          maxLength: 1024
          example: Acme
        businessCode:
          type: string
          maxLength: 128
          example: '64202'
        businessDescription:
          type: string
          maxLength: 4096
          example: Investment holding company.
        dateOfClosure:
          type: string
          format: date-time
          description: ISO 8601 closure date.
          example: '2026-03-01T00:00:00.000Z'
        accountingBasis:
          type: string
          example: CASH
        taxedAs:
          type: string
          example: CORPORATION
        bookkeepingFrequency:
          type: string
          nullable: true
          example: MONTHLY
        nonUSBusinessEntityEIN:
          type: string
          description: Temporary non-US EIN handling field.
          example: 12-3456789
        requestedEIN:
          type: boolean
          description: Temporary non-US EIN handling field.
          example: false
        publicFacingWebsiteUrl:
          type: string
          format: uri
          example: https://acme.example
        fiscalYearDay:
          type: integer
          minimum: 1
          maximum: 31
          example: 31
        fiscalYearMonth:
          type: integer
          minimum: 1
          maximum: 12
          example: 12
        naicsCode:
          type: string
          description: NAICS business code.
          example: '551112'
        isIncorporationInProgress:
          type: boolean
          example: false
        countrySpecificFields:
          type: object
          description: Country-specific update payloads supported by the underlying Commenda OS business entity API.
          additionalProperties: true
      example:
        legalName: Acme Holdings Pte. Ltd.
        businessDescription: Investment holding company.
        publicFacingWebsiteUrl: https://acme.example
    CommendaOsLocationsResponse:
      type: object
      required:
        - locations
        - count
      properties:
        locations:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsLocation'
        count:
          type: integer
          example: 1
    CommendaOsLocationCreateRequest:
      type: object
      description: Create a reusable Commenda OS location for a business entity. The `businessEntityId` is taken from the URL path.
      required:
        - locationTypes
        - address
      properties:
        locationName:
          type: string
          description: Optional display name. Required by some location types such as registered office and mailing address.
          example: Singapore registered office
        startDate:
          type: string
          format: date
          example: '2026-04-27'
        employeeCount:
          type: integer
          description: Employee count for employee work locations.
          example: 12
        locationTypes:
          type: array
          items:
            type: string
          example:
            - REGISTERED_OFFICE_ADDRESS
        address:
          $ref: '#/components/schemas/CommendaOsLocationAddress'
    CommendaOsLocationResponse:
      type: object
      required:
        - location
      properties:
        location:
          $ref: '#/components/schemas/CommendaOsLocation'
    CommendaOsLocationUpdateRequest:
      type: object
      description: Update a reusable Commenda OS location. Omitted fields are left unchanged by the Partner API client, but `locationTypes` and `address` are required by the current location update contract.
      required:
        - locationTypes
        - address
      properties:
        locationName:
          type: string
          description: Optional display name. Required by some location types such as registered office and mailing address.
          example: Singapore registered office
        startDate:
          type: string
          format: date
          nullable: true
          example: '2026-04-27'
        employeeCount:
          type: integer
          description: Employee count for employee work locations.
          example: 12
        locationTypes:
          type: array
          items:
            type: string
          example:
            - REGISTERED_OFFICE_ADDRESS
        address:
          $ref: '#/components/schemas/CommendaOsLocationAddress'
    CommendaOsKycId:
      type: object
      required:
        - type
        - name
      properties:
        type:
          type: string
          example: US_SSN
        name:
          type: string
          example: Social Security Number
        value:
          type: string
          nullable: true
        documentId:
          type: string
          nullable: true
        doesNotHaveKYCId:
          type: boolean
          nullable: true
        decryptedValue:
          type: string
          nullable: true
    CommendaOsPersonAddress:
      type: object
      description: Address fields stored directly on a Commenda OS person.
      required:
        - addressLine1
        - city
        - country
      properties:
        addressLine1:
          type: string
          example: 1 Raffles Place
        addressLine2:
          type: string
          nullable: true
          example: Suite 21045
        addressLine3:
          type: string
          nullable: true
        city:
          type: string
          example: Singapore
        postalCode:
          type: string
          nullable: true
          example: '048616'
        state:
          type: string
          nullable: true
        country:
          type: string
          example: SG
    CommendaOsBusinessEntityPerson:
      type: object
      required:
        - id
        - firstName
        - lastName
        - dateOfBirth
        - email
        - kycIds
        - residentialAddress
        - stakeholderId
        - phoneNumber
        - sharePercentage
        - governanceRelationships
      properties:
        id:
          type: integer
          example: 12
        firstName:
          type: string
          example: Jane
        lastName:
          type: string
          example: Founder
        dateOfBirth:
          type: string
          example: '1990-04-18'
        email:
          type: string
          format: email
          example: jane@acme.com
        gender:
          type: string
          nullable: true
        nationalities:
          type: array
          items:
            type: string
        kycIds:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsKycId'
        residentialAddress:
          type: object
          allOf:
            - $ref: '#/components/schemas/CommendaOsPersonAddress'
          nullable: true
          description: Person residential address, used for participant resource requirements such as `participants.{participantId}.resource.residentialAddress`.
        onboardingInfo:
          type: object
          nullable: true
          additionalProperties: true
        stakeholderId:
          type: string
          example: stk_123
        phoneNumber:
          type: string
          example: '+14155550123'
        employmentStartDate:
          type: string
          nullable: true
        directorIdentificationNumber:
          type: string
          nullable: true
          description: Director Identification Number (DIN) assigned to Indian directors.
          example: '00012345'
        sharePercentage:
          type: number
          example: 75
        governanceRelationships:
          type: object
          description: |
            Map of governance roles this person holds at the business entity, keyed by role name. The value carries role-specific flags. The set of keys present is a subset of `DIRECTOR`, `AUTHORIZED_SIGNATORY`, and `BENEFICIAL_OWNER`. `BENEFICIAL_OWNER` is included when the person is currently recorded as an ultimate beneficial owner (UBO) of the business entity by Commenda's ownership engine.
          additionalProperties: true
          example:
            DIRECTOR:
              startDate: '2020-01-15'
              endDate: null
              isResidentDirector: true
            BENEFICIAL_OWNER:
              isBeneficialOwner: true
        jobTitle:
          type: array
          items:
            type: string
        startDateOfEmployment:
          type: string
          nullable: true
          example: '2025-01-01'
        isResidentDirector:
          type: boolean
          nullable: true
          description: Whether this director is a resident director of the business entity. Applicable to jurisdictions that require at least one locally resident director (e.g. India).
    CommendaOsBusinessEntityPersonsResponse:
      type: object
      required:
        - persons
        - count
      properties:
        persons:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsBusinessEntityPerson'
        count:
          type: integer
          example: 2
    CommendaOsPerson:
      type: object
      required:
        - id
        - firstName
        - lastName
        - dateOfBirth
        - email
        - kycIds
        - residentialAddress
        - stakeholderId
        - phoneNumber
        - businessEntitiesInfo
      properties:
        id:
          type: integer
          example: 12
        firstName:
          type: string
          example: Jane
        lastName:
          type: string
          example: Founder
        dateOfBirth:
          type: string
          example: '1990-04-18'
        email:
          type: string
          format: email
          example: jane@acme.com
        gender:
          type: string
          nullable: true
        nationalities:
          type: array
          items:
            type: string
        kycIds:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsKycId'
        residentialAddress:
          type: object
          allOf:
            - $ref: '#/components/schemas/CommendaOsPersonAddress'
          nullable: true
          description: Person residential address, used for participant resource requirements such as `participants.{participantId}.resource.residentialAddress`.
        onboardingInfo:
          type: object
          nullable: true
          additionalProperties: true
        stakeholderId:
          type: string
          example: stk_123
        phoneNumber:
          type: string
          example: '+14155550123'
        employmentStartDate:
          type: string
          nullable: true
          example: '2025-01-01'
        directorIdentificationNumber:
          type: string
          nullable: true
          description: Director Identification Number (DIN) assigned to Indian directors.
          example: '00012345'
        businessEntitiesInfo:
          type: array
          items:
            type: object
            required:
              - businessEntityId
              - businessEntityName
              - sharePercentage
              - governanceRelationships
            properties:
              businessEntityId:
                type: integer
                example: 44
              businessEntityName:
                type: string
                example: Acme Holdings LLC
              sharePercentage:
                type: number
                example: 75
              governanceRelationships:
                type: object
                description: |
                  Map of governance roles this person holds at the business entity, keyed by role name. The value carries role-specific flags. The set of keys present is a subset of `DIRECTOR`, `AUTHORIZED_SIGNATORY`, and `BENEFICIAL_OWNER`. `BENEFICIAL_OWNER` is included when the person is currently recorded as an ultimate beneficial owner (UBO) of the business entity by Commenda's ownership engine.
                additionalProperties: true
                example:
                  DIRECTOR:
                    startDate: '2020-01-15'
                    endDate: null
                    isResidentDirector: true
                  BENEFICIAL_OWNER:
                    isBeneficialOwner: true
              jobTitle:
                type: array
                items:
                  type: string
              startDateOfEmployment:
                type: string
                nullable: true
                example: '2025-01-01'
              isResidentDirector:
                type: boolean
                nullable: true
                description: Whether this director is a resident director of the business entity. Applicable to jurisdictions that require at least one locally resident director (e.g. India).
    CommendaOsPersonsResponse:
      type: object
      required:
        - persons
        - count
      properties:
        persons:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsPerson'
        count:
          type: integer
          example: 2
    CommendaOsPersonCreateRequest:
      type: object
      description: Create a reusable Commenda OS person for one of your customers. The `customerId` is taken from the URL path.
      required:
        - firstName
      properties:
        firstName:
          type: string
          example: Jane
        lastName:
          type: string
          example: Founder
        email:
          type: string
          format: email
          example: jane@acme.com
        phoneNumber:
          type: string
          example: '+14155550123'
        residentialAddress:
          $ref: '#/components/schemas/CommendaOsPersonAddress'
          description: Person residential address. Use this for participant resource requirements such as `participants.{participantId}.resource.residentialAddress`.
        employmentStartDate:
          type: string
          format: date
          example: '2025-01-01'
        dateOfBirth:
          type: string
          format: date
          example: '1990-04-18'
        countryOfCitizenship:
          type: string
          example: SG
        ssn:
          type: string
          description: SSN or ITIN, when applicable.
          example: 123-45-6789
        hasNoSSN:
          type: boolean
          example: false
        directorIdentificationNumber:
          type: string
          description: Director Identification Number (DIN) assigned to Indian directors.
          example: '00012345'
    CommendaOsPersonMutationResponse:
      type: object
      required:
        - person
      properties:
        person:
          $ref: '#/components/schemas/CommendaOsPerson'
    CommendaOsPersonUpdateRequest:
      type: object
      description: Partial update payload for a reusable Commenda OS person. Omitted fields are left unchanged.
      properties:
        firstName:
          type: string
          example: Jane
        lastName:
          type: string
          example: Founder
        email:
          type: string
          format: email
          example: jane@acme.com
        phoneNumber:
          type: string
          example: '+14155550123'
        residentialAddress:
          $ref: '#/components/schemas/CommendaOsPersonAddress'
          description: Person residential address. Use this for participant resource requirements such as `participants.{participantId}.resource.residentialAddress`.
        employmentStartDate:
          type: string
          format: date
          example: '2025-01-01'
        dateOfBirth:
          type: string
          format: date
          example: '1990-04-18'
        countryOfCitizenship:
          type: string
          example: SG
        ssn:
          type: string
          description: SSN or ITIN, when applicable.
          example: 123-45-6789
        hasNoSSN:
          type: boolean
          example: false
        directorIdentificationNumber:
          type: string
          description: Director Identification Number (DIN) assigned to Indian directors.
          example: '00012345'
    CommendaOsGovernmentIdentifiersResponse:
      type: object
      required:
        - governmentIdentifiers
        - count
      properties:
        governmentIdentifiers:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsGovernmentIdentifier'
        count:
          type: integer
          example: 2
    CommendaOsGovernmentIdentifierResponse:
      type: object
      required:
        - governmentIdentifier
      properties:
        governmentIdentifier:
          $ref: '#/components/schemas/CommendaOsGovernmentIdentifier'
    CommendaOsCustomerFileUploadRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          description: Binary file part. The part filename and detected MIME type are recorded on the file. No other multipart fields are accepted.
    CommendaOsCustomerFile:
      type: object
      required:
        - fileId
        - fileName
        - mimeType
        - fileSize
        - customerId
      properties:
        fileId:
          type: integer
          description: Commenda file id. Pass to a downstream attach call (for example, create a customer document or upsert a participant document) to put the file to work.
          example: 456
        fileName:
          type: string
          example: passport.pdf
        mimeType:
          type: string
          example: application/pdf
        fileSize:
          type: integer
          nullable: true
          example: 382144
        customerId:
          type: integer
          example: 77
    CommendaOsCustomerFileResponse:
      type: object
      required:
        - file
      properties:
        file:
          $ref: '#/components/schemas/CommendaOsCustomerFile'
    CommendaOsDocument:
      type: object
      required:
        - documentType
        - documentSubType
        - supportsDataStorage
        - isTimeSensitive
        - isUnique
      properties:
        id:
          type: integer
          nullable: true
          example: 900
        fileName:
          type: string
          nullable: true
          example: operating-agreement.pdf
        fileUrl:
          type: string
          nullable: true
          format: uri
          example: https://bucket.s3.amazonaws.com/operating-agreement.pdf
        documentType:
          type: string
          example: FORMATION_DOCUMENT
        documentSubType:
          type: string
          example: OperatingAgreement
        complianceTag:
          type: string
          nullable: true
        compliancePurpose:
          type: string
          nullable: true
        dateOfIssuance:
          type: string
          nullable: true
        dateOfExpiration:
          type: string
          nullable: true
        effectiveStartDate:
          type: string
          nullable: true
        effectiveEndDate:
          type: string
          nullable: true
        supportsDataStorage:
          type: boolean
          example: false
        data:
          type: object
          nullable: true
          additionalProperties: true
        createdAt:
          type: integer
          nullable: true
          example: 1735689600000
        updatedAt:
          type: integer
          nullable: true
          example: 1735776000000
        deprecatedFieldsForFrontend:
          type: object
          nullable: true
          additionalProperties: true
        explicitDocumentType:
          type: string
          nullable: true
        isTimeSensitive:
          type: boolean
          example: false
        isUnique:
          type: boolean
          example: true
    CommendaOsDocumentsResponse:
      type: object
      required:
        - documents
        - count
      properties:
        documents:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsDocument'
        count:
          type: integer
          example: 3
    CommendaOsSupportedDocumentType:
      type: object
      required:
        - documentName
        - documentType
        - documentSubType
        - supportsDataStorage
        - country
        - isTimeSensitive
        - isUnique
      properties:
        documentName:
          type: string
          example: Operating Agreement
        documentType:
          type: string
          example: FORMATION_DOCUMENT
        documentSubType:
          type: string
          example: OperatingAgreement
        supportsDataStorage:
          type: boolean
          example: false
        data:
          type: object
          additionalProperties: true
        country:
          type: string
          example: US
        jurisdiction:
          type: string
          nullable: true
          example: DE
        corporationType:
          type: string
          nullable: true
          example: LLC
        isTimeSensitive:
          type: boolean
          example: false
        isUnique:
          type: boolean
          example: true
        canBeAddedByAddDocument:
          type: boolean
          nullable: true
    CommendaOsSupportedDocumentsResponse:
      type: object
      required:
        - supportedDocumentTypes
        - count
      properties:
        supportedDocumentTypes:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsSupportedDocumentType'
        count:
          type: integer
          example: 5
    CommendaOsRegistration:
      type: object
      required:
        - country
        - businessEntityId
        - corporationType
        - effectiveStartDate
        - registeredBy
        - displayName
        - description
        - purpose
        - isFunctionCritical
        - status
        - registrationStatus
        - internalIdentifier
        - isCustom
      properties:
        id:
          type: string
          nullable: true
          example: reg_123
        country:
          type: string
          example: US
        jurisdiction:
          type: string
          nullable: true
          example: DE
        businessEntityId:
          type: integer
          example: 44
        corporationType:
          type: string
          example: LLC
        effectiveStartDate:
          type: string
          example: '2025-01-01'
        effectiveEndDate:
          type: string
          nullable: true
        registeredBy:
          type: string
          example: COMMENDA
        displayName:
          type: string
          example: Delaware LLC Registration
        description:
          type: string
          example: Corporate registry registration for a Delaware LLC.
        purpose:
          type: string
          example: CORPORATE_REGISTRY
        acknowledgements:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/CommendaOsDocument'
        isFunctionCritical:
          type: boolean
          example: true
        status:
          type: string
          example: VALID
        registrationStatus:
          type: string
          example: ACTIVE
        createdAt:
          type: integer
          nullable: true
          example: 1735689600000
        lastUpdatedAt:
          type: integer
          nullable: true
          example: 1735776000000
        internalIdentifier:
          type: string
          example: US_DE_CORP_REGISTRY
        isCustom:
          type: boolean
          example: false
        governmentIdentifiers:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/CommendaOsGovernmentIdentifier'
    CommendaOsRegistrationsResponse:
      type: object
      required:
        - registrations
        - count
      properties:
        registrations:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsRegistration'
        count:
          type: integer
          example: 2
    CommendaOsRegistrationResponse:
      type: object
      required:
        - registration
      properties:
        registration:
          $ref: '#/components/schemas/CommendaOsRegistration'
    CommendaOsSupportedRegistration:
      type: object
      required:
        - displayName
        - description
        - purpose
        - isExpirable
        - isFunctionCritical
        - internalIdentifier
        - corporationType
        - country
      properties:
        displayName:
          type: string
          example: Delaware LLC Registration
        description:
          type: string
          example: Corporate registry registration for a Delaware LLC.
        purpose:
          type: string
          example: CORPORATE_REGISTRY
        jurisdiction:
          type: string
          nullable: true
          example: DE
        isExpirable:
          type: boolean
          example: false
        isFunctionCritical:
          type: boolean
          example: true
        internalIdentifier:
          type: string
          example: US_DE_CORP_REGISTRY
        corporationType:
          type: string
          example: LLC
        governmentIdentifierInternalIdentifier:
          type: string
          nullable: true
          description: Linked government-identifier rule when one is required for this registration.
          example: US_EIN
        country:
          type: string
          example: US
    CommendaOsSupportedRegistrationsResponse:
      type: object
      required:
        - supportedRegistrations
        - count
      properties:
        supportedRegistrations:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsSupportedRegistration'
        count:
          type: integer
          example: 12
    PartnerIncorporationIssueStatusFilter:
      type: string
      enum:
        - ACTIVE
        - RESOLVED
        - ALL
    PartnerIncorporationIssueCode:
      type: string
      description: Current partner-visible issue code. Commenda may add additional issue codes in future API updates.
      enum:
        - MISSING_INFORMATION
        - INVALID_INFORMATION
        - DOCUMENT_REQUIRED
        - DOCUMENT_INVALID
        - COMPANY_NAME_REJECTED
        - OTHER
    PartnerIncorporationIssueStatus:
      type: string
      enum:
        - ACTIVE
        - RESOLVED
    PartnerIncorporationIssueScope:
      type: object
      description: Location the issue applies to. The `type` field determines which additional fields are present.
      required:
        - type
      additionalProperties: false
      properties:
        type:
          type: string
          enum:
            - INCORPORATION
            - INTAKE_FIELD
            - PARTICIPANT
            - PARTICIPANT_DOCUMENT
            - FILE
        path:
          type: string
          description: Intake field path for `INTAKE_FIELD` scopes.
          example: companyNames.companyNameOptions
        stageId:
          type: string
          description: Optional status workflow stage id this issue blocks.
          example: kyc
        participantId:
          type: string
          description: Incorporation participant id for participant-scoped issues.
          example: participant_123
        resource:
          type: object
          description: Reusable Commenda OS resource for participant-scoped issues.
          properties:
            resourceType:
              type: string
              enum:
                - KEY_PERSON
                - BUSINESS_ENTITY
            resourceId:
              type: integer
              example: 12
        documentKind:
          type: string
          description: Participant document kind for participant-document issues.
          example: PASSPORT_SCAN
        fileId:
          type: integer
          description: Commenda file id for file or participant-document issues.
          example: 456
      example:
        type: PARTICIPANT_DOCUMENT
        stageId: kyc
        participantId: participant_123
        documentKind: PASSPORT_SCAN
        fileId: 456
    PartnerIncorporationIssue:
      type: object
      required:
        - id
        - code
        - message
        - status
        - scope
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: Stable identifier for one remediation episode.
          example: issue_123
        code:
          $ref: '#/components/schemas/PartnerIncorporationIssueCode'
        message:
          type: string
          example: The passport scan for Jane Founder is unreadable. Please upload a clearer scan.
        status:
          $ref: '#/components/schemas/PartnerIncorporationIssueStatus'
        scope:
          $ref: '#/components/schemas/PartnerIncorporationIssueScope'
        createdAt:
          type: string
          format: date-time
          example: '2026-04-25T20:58:00.000Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-04-25T20:59:00.000Z'
        resolvedAt:
          type: string
          format: date-time
          description: Present when `status` is `RESOLVED`.
          example: '2026-04-25T21:15:00.000Z'
    PartnerIncorporationIssuesResponse:
      type: object
      required:
        - issues
        - count
      properties:
        issues:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporationIssue'
        count:
          type: integer
          example: 1
    PartnerWebhookEventType:
      type: string
      description: Partner webhook event type. Commenda may add additional event types in future API updates.
      enum:
        - INCORPORATION_ISSUE_CREATED
        - INCORPORATION_ISSUE_RESOLVED
    PartnerWebhookSubscriptionStatus:
      type: string
      enum:
        - ACTIVE
    PartnerWebhookSubscription:
      type: object
      required:
        - id
        - url
        - eventTypes
        - status
        - secretPreview
        - createdAt
      properties:
        id:
          type: string
          example: whsub_123
        url:
          type: string
          format: uri
          example: https://partner.example.com/commenda/webhooks
        eventTypes:
          type: array
          items:
            $ref: '#/components/schemas/PartnerWebhookEventType'
        status:
          $ref: '#/components/schemas/PartnerWebhookSubscriptionStatus'
        secretPreview:
          type: string
          description: Redacted signing secret preview returned by read/list endpoints.
          example: whsec_...c123
        createdAt:
          type: string
          format: date-time
          example: '2026-04-25T21:00:00.000Z'
    PartnerWebhookSubscriptionsResponse:
      type: object
      required:
        - webhookSubscriptions
        - count
      properties:
        webhookSubscriptions:
          type: array
          items:
            $ref: '#/components/schemas/PartnerWebhookSubscription'
        count:
          type: integer
          example: 1
    PartnerCreateWebhookSubscriptionRequest:
      type: object
      required:
        - url
        - eventTypes
      properties:
        url:
          type: string
          format: uri
          description: HTTPS webhook URL reachable on a public address.
          example: https://partner.example.com/commenda/webhooks
        eventTypes:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/PartnerWebhookEventType'
      example:
        url: https://partner.example.com/commenda/webhooks
        eventTypes:
          - INCORPORATION_ISSUE_CREATED
          - INCORPORATION_ISSUE_RESOLVED
    PartnerCreatedWebhookSubscription:
      allOf:
        - $ref: '#/components/schemas/PartnerWebhookSubscription'
        - type: object
          required:
            - secret
          properties:
            secret:
              type: string
              description: Full signing secret. Returned only when the subscription is created.
              example: whsec_abc123
    PartnerCreateWebhookSubscriptionResponse:
      type: object
      required:
        - webhookSubscription
      properties:
        webhookSubscription:
          $ref: '#/components/schemas/PartnerCreatedWebhookSubscription'
    PartnerWebhookSubscriptionResponse:
      type: object
      required:
        - webhookSubscription
      properties:
        webhookSubscription:
          $ref: '#/components/schemas/PartnerWebhookSubscription'
    PartnerIncorporationParticipantResponse:
      type: object
      required:
        - participant
      properties:
        participant:
          $ref: '#/components/schemas/PartnerIncorporationParticipant'
    PartnerIncorporationParticipantDocumentResponse:
      type: object
      required:
        - document
      properties:
        document:
          $ref: '#/components/schemas/PartnerIncorporationParticipantDocument'
    PartnerIncorporationIssueWebhookPayload:
      type: object
      required:
        - eventId
        - eventType
        - createdAt
        - data
      properties:
        eventId:
          type: string
          description: Stable event id. Use this for idempotency.
          example: evt_incorporation_issue_created_issue_123
        eventType:
          $ref: '#/components/schemas/PartnerWebhookEventType'
        createdAt:
          type: string
          format: date-time
          example: '2026-04-25T21:00:00.000Z'
        data:
          type: object
          required:
            - customerId
            - incorporationId
            - issue
          properties:
            customerId:
              type: integer
              example: 77
            incorporationId:
              type: string
              example: 0f9a8f5e-7f7c-4c1b-a60a-b1022f9d8c91
            issue:
              $ref: '#/components/schemas/PartnerIncorporationIssue'
    transaction_status:
      type: string
      enum:
        - LOCKED
        - UNCOMMITTED
        - IGNORED
      description: Status of the transaction. More details [here](/api-reference/global-indirect-tax/transaction/transaction#filing-status).
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    xApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key