openapi: 3.0.3
info:
  title: MVMNT API
  version: 1.0.0
  description: |
    The MVMNT API enables you to automate freight brokerage workflows by integrating
    directly with our Transportation Management System.

    Postman setup guide: [API Clients](/getting-started/api-clients).

    ## Authentication

    OAuth 2.0 client credentials flow. See [Authentication Guide](/getting-started/authentication)
    for details.

    ### Token Endpoint

    ```
    POST https://api.mvmnt.io/oauth2/token
    ```

    #### Request

    **Headers:**
    ```http
    Content-Type: application/x-www-form-urlencoded
    ```

    **Body Parameters:**
    ```
    grant_type=client_credentials
    client_id=YOUR_CLIENT_ID
    client_secret=YOUR_CLIENT_SECRET
    ```

    #### Example Request

    ```bash
    curl -X POST https://api.mvmnt.io/oauth2/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials" \
      -d "client_id=YOUR_CLIENT_ID" \
      -d "client_secret=YOUR_CLIENT_SECRET"
    ```

    #### Success Response

    **Status:** `200 OK`

    ```json
    {
      "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
      "token_type": "Bearer",
      "expires_in": 3600
    }
    ```

    **Response Fields:**
    - `access_token`: JWT Bearer token to use for API requests
    - `token_type`: Always `Bearer`
    - `expires_in`: Token lifetime in seconds (3600 = 1 hour)

    ## Idempotency

    Mutating requests (POST, PATCH, DELETE) accept an optional `Idempotency-Key`
    header (up to 255 characters). Retrying a request with the same key and the
    same body returns the original result instead of repeating the operation;
    reusing a key with a different body fails. Keys are scoped to your
    organization — keys chosen by other tenants can never collide with yours.
    Use a stable identifier from your system (for example your own record id
    plus the action) rather than a random value per attempt.
  contact:
    name: MVMNT Support
    email: support@mvmnt.io
    url: https://docs.mvmnt.io
  license:
    name: Proprietary
    url: https://mvmnt.io/legal/terms
  x-parsed-md-description:
    result:
      - $$mdtype: Node
        errors: []
        lines:
          - 0
          - 2
        inline: false
        attributes: {}
        children:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 2
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 2
                inline: true
                attributes:
                  content: The MVMNT API enables you to automate freight brokerage workflows by integrating
                children: []
                type: text
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 2
                inline: true
                attributes: {}
                children: []
                type: softbreak
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 2
                inline: true
                attributes:
                  content: directly with our Transportation Management System.
                children: []
                type: text
                annotations: []
                slots: {}
            type: inline
            annotations: []
            slots: {}
        type: paragraph
        annotations: []
        slots: {}
      - $$mdtype: Node
        errors: []
        lines:
          - 3
          - 4
        inline: false
        attributes:
          level: 2
        children:
          - $$mdtype: Node
            errors: []
            lines:
              - 3
              - 4
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: true
                attributes:
                  content: Authentication
                children: []
                type: text
                annotations: []
                slots: {}
            type: inline
            annotations: []
            slots: {}
        type: heading
        annotations: []
        slots: {}
      - $$mdtype: Node
        errors: []
        lines:
          - 5
          - 6
        inline: false
        attributes: {}
        children:
          - $$mdtype: Node
            errors: []
            lines:
              - 5
              - 6
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 5
                  - 6
                inline: true
                attributes:
                  content: 'OAuth 2.0 client credentials flow. See '
                children: []
                type: text
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 5
                  - 6
                inline: true
                attributes:
                  href: /getting-started/authentication
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 5
                      - 6
                    inline: true
                    attributes:
                      content: Authentication Guide
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: link
                annotations: []
                slots: {}
                redocly:::linkOriginal:href: /getting-started/authentication
              - $$mdtype: Node
                errors: []
                lines:
                  - 5
                  - 6
                inline: true
                attributes:
                  content: ' for details.'
                children: []
                type: text
                annotations: []
                slots: {}
            type: inline
            annotations: []
            slots: {}
        type: paragraph
        annotations: []
        slots: {}
servers:
  - url: https://api.mvmnt.io/v1
    description: Production
  - url: https://api.demo.mvmnt.io/v1
    description: Demo (non-production)
security:
  - BearerAuth: []
tags:
  - name: Carriers
    description: Carrier management operations
  - name: Carrier Contacts
    description: Carrier contact management operations
  - name: Carrier Factors
    description: Carrier factor (factoring company) management operations
  - name: Carrier Payment Methods
    description: Carrier payment method management operations
  - name: Companies
    description: Company management operations
  - name: Credit Memos
    description: |
      AR credit memo management operations.
      Credit memos represent customer credits that can be applied to invoices.
  - name: Bills
    description: |
      AP bill management operations.
      Bills represent carrier and vendor invoices to be paid.
  - name: Bill Payments
    description: |
      AP bill payment management operations.
      Bill payments record payments made to carriers and vendors.
  - name: Customers
    description: Customer management operations
  - name: Customer Contacts
    description: Customer contact management operations
  - name: Documents
    description: |
      Document management operations.
      Documents are files (PDFs, images) that can be attached to orders, loads, or services.
  - name: Invoices
    description: |
      AR invoice management operations.
      Invoices represent customer billing for shipment services.
  - name: Loads
    description: |
      Load management operations.
      Loads represent carrier execution - which carrier is moving the freight.
  - name: Locations
    description: Location management operations
  - name: Location Contacts
    description: Location contact management operations
  - name: Payment Terms
    description: Payment term management operations
  - name: Reference Data
    description: |
      Read-only catalogs (equipment, charge codes, special requirements)
      referenced by id from other resources.

      Every catalog also answers on its short top-level path, so
      `GET /v1/charge-codes` and `GET /v1/reference-data/charge-codes` are
      the same endpoint. The documented `/reference-data/*` form is canonical
      — it keeps the catalogs grouped here as more are added (port codes,
      cities, zip codes) — and the short form is a convenience alias.
  - name: Payments
    description: |
      AR payment management operations.
      Payments represent received customer payments applied to invoices.
  - name: Quotes
    description: |
      Quote management operations.
      Quotes are pricing requests/responses that can be converted to shipments.
  - name: Saved Searches
    description: Saved search management operations
  - name: Search
    description: Global search operations
  - name: Services
    description: |
      Service (vended service) management operations.
      Services represent non-carrier vendor work (drayage, customs, warehousing).
  - name: Shipments
    description: |
      Shipment tracking and management operations.
      Shipments contain orders, loads, and services.
  - name: Teams
    description: Team management operations
  - name: Users
    description: User management operations
  - name: Vendors
    description: Vendor management operations
  - name: Vendor Contacts
    description: Vendor contact management operations
  - name: Vendor Payment Methods
    description: Vendor payment method management operations
paths:
  /companies/filter:
    post:
      tags:
        - Companies
      summary: Filter companies
      description: |
        Query companies using flexible filter criteria with AND/OR logic.

        By default, only non-deleted companies are returned (deletedAt: { isNull: true }).
        Override this by explicitly setting deletedAt filter criteria.
      operationId: filterCompanies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyFilterRequest'
      responses:
        '200':
          description: Filtered companies with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Company'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /companies:
    post:
      tags:
        - Companies
      summary: Create a new company
      description: Create a new company within an organization
      operationId: createCompany
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyInput'
      responses:
        '201':
          description: Company created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /companies/{id}:
    get:
      tags:
        - Companies
      summary: Get a company by ID
      description: Retrieve a single company by its unique identifier
      operationId: getCompanyById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Company found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Companies
      summary: Update a company
      description: |
        Partially update a company. Only provided fields will be updated.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateCompany
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyPatch'
      responses:
        '200':
          description: Company updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Companies
      summary: Delete a company
      description: |
        Soft delete a company (sets deletedAt timestamp).

        The company will no longer appear in default queries but can be retrieved
        by explicitly filtering for deleted records.
      operationId: deleteCompany
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Company deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-contacts/filter:
    post:
      tags:
        - Carrier Contacts
      summary: Filter carrier contacts
      description: |
        Query carrier contacts using flexible filter criteria with AND/OR logic.

        By default, only non-deleted carrier contacts are returned (deletedAt: { isNull: true }).
        Override this by explicitly setting deletedAt filter criteria.
      operationId: filterCarrierContacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierContactFilterRequest'
      responses:
        '200':
          description: Filtered carrier contacts with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CarrierContact'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-contacts:
    post:
      tags:
        - Carrier Contacts
      summary: Create carrier contact
      description: |
        Create a new carrier contact. The contactInfo will create a new Contact record,
        and the CarrierContact will reference it via contactId (managed internally).
      operationId: createCarrierContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierContactInput'
      responses:
        '201':
          description: Carrier contact created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-contacts/{id}:
    get:
      tags:
        - Carrier Contacts
      summary: Get carrier contact
      description: Retrieve a single carrier contact by its unique identifier
      operationId: getCarrierContactById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Carrier contact found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Carrier Contacts
      summary: Update carrier contact
      description: |
        Partially update a carrier contact. Only provided fields will be updated.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable

        When updating contactInfo, the underlying Contact record is updated.
      operationId: updateCarrierContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierContactPatch'
      responses:
        '200':
          description: Carrier contact updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Carrier Contacts
      summary: Delete carrier contact
      description: |
        Soft delete a carrier contact (sets deletedAt timestamp).

        The contact will no longer appear in default queries but can be retrieved
        by explicitly filtering for deleted records.
      operationId: deleteCarrierContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Carrier contact deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carriers/filter:
    post:
      tags:
        - Carriers
      summary: Filter carriers
      description: |
        Query carriers using flexible filter criteria with AND/OR logic.

        By default, only non-deleted carriers are returned (deletedAt: { isNull: true }).
        Override this by explicitly setting deletedAt filter criteria.

        Returns carriers of all types (TRUCKLOAD, AIR, CARTAGE, LINEHAUL, LTL, OCEAN, RAIL)
        with type-specific fields included based on carrier type.
      operationId: filterCarriers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierFilterRequest'
      responses:
        '200':
          description: Filtered carriers with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Carrier'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carriers:
    post:
      tags:
        - Carriers
      summary: Create a new carrier
      description: |
        Create a new carrier within an organization.

        The carrier type must be specified and determines which fields are available:
        - **TRUCKLOAD**: Includes insurance, safety rating, and FMCSA inspection fields
        - **AIR, CARTAGE, LINEHAUL, LTL, OCEAN, RAIL**: Include only base carrier fields

        Note: In the backend, null carrier type is represented as TRUCKLOAD in the public API.
      operationId: createCarrier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierInput'
            examples:
              truckload:
                summary: Truckload carrier with insurance
                value:
                  name: Swift Transportation Co
                  type: TRUCKLOAD
                  email: dispatch@swifttrans.com
                  phone: +1-555-987-6543
                  status: ACTIVE
                  mcNumber: MC-123456
                  dotNumber: '1234567'
                  insuranceCompany: State Farm Insurance
                  insuranceAutoLiabilityLimit: 1000000
                  rating: SATISFACTORY
                  inFmcsa: true
              air:
                summary: Air carrier
                value:
                  name: FedEx Express
                  type: AIR
                  email: cargo@fedex.com
                  phone: +1-555-123-4567
                  status: ACTIVE
                  iataCode: FX
              ltl:
                summary: LTL carrier
                value:
                  name: XPO Logistics
                  type: LTL
                  email: dispatch@xpo.com
                  phone: +1-555-456-7890
                  status: ACTIVE
                  scac: XPOL
      responses:
        '201':
          description: Carrier created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Carrier'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carriers/{id}:
    get:
      tags:
        - Carriers
      summary: Get a carrier by ID
      description: |
        Retrieve a single carrier by its unique identifier.

        The response will include type-specific fields based on the carrier's type:
        - **TRUCKLOAD**: Includes insurance, safety rating, and FMCSA inspection fields
        - **AIR, CARTAGE, LINEHAUL, LTL, OCEAN, RAIL**: Include only base carrier fields
      operationId: getCarrierById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Carrier found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Carrier'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Carriers
      summary: Update a carrier
      description: |
        Partially update a carrier. Only provided fields will be updated.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable

        The carrier type determines which fields can be updated:
        - **TRUCKLOAD**: Can update insurance, safety rating, and FMCSA fields
        - **AIR, CARTAGE, LINEHAUL, LTL, OCEAN, RAIL**: Can only update base carrier fields

        Changing the carrier type will affect which specialized fields are available.
      operationId: updateCarrier
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierPatch'
      responses:
        '200':
          description: Carrier updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Carrier'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Carriers
      summary: Delete a carrier
      description: |
        Soft delete a carrier (sets deletedAt timestamp).

        The carrier will no longer appear in default queries but can be retrieved
        by explicitly filtering for deleted records.
      operationId: deleteCarrier
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Carrier deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carriers/search:
    post:
      summary: Search carriers
      description: |
        Search carriers using OpenSearch-powered full-text and field-specific search.

        This endpoint searches both:
        - **ONBOARDED carriers**: Carriers with profiles in your organization
        - **FMCSA carriers**: Public carrier records from FMCSA database

        Features:
        - Full-text search across multiple fields
        - Field-specific filtering with various operators
        - Sorting and pagination
        - Saved search preferences

        **Note:** Only active (non-deleted) carriers are searchable. Soft-deleted records are automatically excluded from all search results.

        **Response Formats:**
        - `flat` (default): Returns indexed fields only for faster performance
        - `full`: Returns complete carrier objects with all relationships
      operationId: searchCarriers
      tags:
        - Carriers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierSearchRequest'
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /carrier-factors/filter:
    post:
      tags:
        - Carrier Factors
      summary: Filter carrier factors
      description: |
        Query carrier factors (factoring companies) using flexible filter criteria with AND/OR logic.

        By default, only non-deleted carrier factors are returned (deletedAt: { isNull: true }).
        Override this by explicitly setting deletedAt filter criteria.

        Carrier factors represent factoring companies that provide payment services for carriers.
      operationId: filterCarrierFactors
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierFactorFilterRequest'
      responses:
        '200':
          description: Filtered carrier factors with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CarrierFactor'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-factors:
    post:
      tags:
        - Carrier Factors
      summary: Create carrier factor
      description: |
        Create a new carrier factor (factoring company).

        Factoring companies provide payment services for carriers, allowing them to receive
        immediate payment for invoices.
      operationId: createCarrierFactor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierFactorInput'
            examples:
              basic:
                summary: Basic carrier factor
                value:
                  companyName: Capital Factoring Services Inc
                  email: accounting@capitalfactoring.com
                  phoneNumber: +1-555-234-5678
                  addressLine1: 789 Finance Ave
                  city: Dallas
                  state: TX
                  country: USA
                  zipCode: '75201'
              withBanking:
                summary: Carrier factor with banking details
                value:
                  companyName: Capital Factoring Services Inc
                  email: accounting@capitalfactoring.com
                  phoneNumber: +1-555-234-5678
                  addressLine1: 789 Finance Ave
                  city: Dallas
                  state: TX
                  country: USA
                  zipCode: '75201'
                  bankName: Chase Bank
                  accountName: Capital Factoring Services Inc
                  accountNumber: '1234567890'
                  abaAch: '021000021'
                  swiftCode: CHASUS33
                  currency: USD
      responses:
        '201':
          description: Carrier factor created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierFactor'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-factors/{id}:
    get:
      tags:
        - Carrier Factors
      summary: Get carrier factor
      description: |
        Retrieve a single carrier factor by its unique identifier.

        Carrier factors represent factoring companies that provide payment services.
      operationId: getCarrierFactorById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Carrier factor found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierFactor'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Carrier Factors
      summary: Update carrier factor
      description: |
        Partially update a carrier factor. Only provided fields will be updated.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateCarrierFactor
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierFactorPatch'
            examples:
              updateContact:
                summary: Update contact information
                value:
                  email: newemail@capitalfactoring.com
                  phoneNumber: +1-555-999-8888
              updateBanking:
                summary: Update banking details
                value:
                  bankName: Bank of America
                  accountNumber: '9876543210'
                  abaAch: '026009593'
      responses:
        '200':
          description: Carrier factor updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierFactor'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Carrier Factors
      summary: Delete carrier factor
      description: |
        Soft delete a carrier factor (sets deletedAt timestamp).

        The carrier factor will no longer appear in default queries but can be retrieved
        by explicitly filtering for deleted records.
      operationId: deleteCarrierFactor
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Carrier factor deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-payment-methods/filter:
    post:
      tags:
        - Carrier Payment Methods
      summary: Filter carrier payment methods
      description: |
        Query carrier payment methods using flexible filter criteria with AND/OR logic.

        By default, only non-deleted payment methods are returned (deletedAt: { isNull: true }).
        Override this by explicitly setting deletedAt filter criteria.

        Carrier payment methods define how and where payments are sent for a specific carrier.
      operationId: filterCarrierPaymentMethods
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierPaymentMethodFilterRequest'
      responses:
        '200':
          description: Filtered carrier payment methods with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CarrierPaymentMethod'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-payment-methods:
    post:
      tags:
        - Carrier Payment Methods
      summary: Create carrier payment method
      description: |
        Create a new carrier payment method.

        **Payment Recipient Type Constraints:**
        - **DIRECT**: Payment goes to carrier directly. `carrierFactorId` must be null or omitted.
        - **FACTOR**: Payment goes to factoring company. `carrierFactorId` is required.

        **Important**: The `carrierId` cannot be changed after creation.
      operationId: createCarrierPaymentMethod
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierPaymentMethodInput'
            examples:
              directPayment:
                summary: Direct ACH payment to carrier
                value:
                  carrierId: 770e8400-e29b-41d4-a716-446655440000
                  paymentRecipientType: DIRECT
                  paymentMethodType: ACH
                  isPreferred: true
                  bankName: Chase Bank
                  accountName: Carrier Transport Inc
                  accountNumber: '1234567890'
                  abaAch: '021000021'
                  currency: USD
              factorPayment:
                summary: Payment through factoring company
                value:
                  carrierId: 770e8400-e29b-41d4-a716-446655440000
                  paymentRecipientType: FACTOR
                  paymentMethodType: ACH_WIRE
                  carrierFactorId: 550e8400-e29b-41d4-a716-446655440000
                  isPreferred: false
              zelle:
                summary: Zelle payment
                value:
                  carrierId: 770e8400-e29b-41d4-a716-446655440000
                  paymentRecipientType: DIRECT
                  paymentMethodType: ZELLE
                  email: payments@carrier.com
                  phone: +1-555-123-4567
                  username: carrier_payments
      responses:
        '201':
          description: Carrier payment method created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierPaymentMethod'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-payment-methods/{id}:
    get:
      tags:
        - Carrier Payment Methods
      summary: Get carrier payment method
      description: |
        Retrieve a single carrier payment method by its unique identifier.

        Returns full details including banking information and associated carrier/factor references.
      operationId: getCarrierPaymentMethodById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Carrier payment method found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierPaymentMethod'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Carrier Payment Methods
      summary: Update carrier payment method
      description: |
        Partially update a carrier payment method. Only provided fields will be updated.

        **IMPORTANT**: The `carrierId` field cannot be changed after creation.

        **Payment Recipient Type Constraints:**
        - When changing to **DIRECT**: `carrierFactorId` must be set to null
        - When changing to **FACTOR**: `carrierFactorId` is required

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateCarrierPaymentMethod
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierPaymentMethodPatch'
            examples:
              updateBanking:
                summary: Update banking details
                value:
                  bankName: Bank of America
                  accountNumber: '9876543210'
                  abaAch: '026009593'
              changeToFactor:
                summary: Change from direct to factor payment
                value:
                  paymentRecipientType: FACTOR
                  carrierFactorId: 550e8400-e29b-41d4-a716-446655440000
              makePreferred:
                summary: Set as preferred payment method
                value:
                  isPreferred: true
      responses:
        '200':
          description: Carrier payment method updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierPaymentMethod'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Carrier Payment Methods
      summary: Delete carrier payment method
      description: |
        Soft delete a carrier payment method (sets deletedAt timestamp).

        The payment method will no longer appear in default queries but can be retrieved
        by explicitly filtering for deleted records.
      operationId: deleteCarrierPaymentMethod
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Carrier payment method deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /customer-contacts/filter:
    post:
      tags:
        - Customer Contacts
      summary: Filter customer contacts
      description: |
        Query customer contacts using flexible filter criteria with AND/OR logic.

        By default, only non-deleted customer contacts are returned (deletedAt: { isNull: true }).
        Override this by explicitly setting deletedAt filter criteria.
      operationId: filterCustomerContacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerContactFilterRequest'
      responses:
        '200':
          description: Filtered customer contacts with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerContact'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /customer-contacts:
    post:
      tags:
        - Customer Contacts
      summary: Create customer contact
      description: |
        Create a new customer contact. The contact details are provided inline
        via contactInfo; no internal identifiers are required or exposed.
      operationId: createCustomerContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerContactInput'
      responses:
        '201':
          description: Customer contact created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /customer-contacts/{id}:
    get:
      tags:
        - Customer Contacts
      summary: Get customer contact
      description: Retrieve a single customer contact by its unique identifier
      operationId: getCustomerContactById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Customer contact found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Customer Contacts
      summary: Update customer contact
      description: |
        Partially update a customer contact. Only provided fields will be updated.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable

        When updating contactInfo, the underlying Contact record is updated.
      operationId: updateCustomerContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerContactPatch'
      responses:
        '200':
          description: Customer contact updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Customer Contacts
      summary: Delete customer contact
      description: |
        Soft delete a customer contact (sets deletedAt timestamp).

        The contact will no longer appear in default queries but can be retrieved
        by explicitly filtering for deleted records.
      operationId: deleteCustomerContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Customer contact deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /customers/filter:
    post:
      summary: Filter customers
      description: |
        Filter customers using comprehensive query criteria with AND/OR logic and multiple operators.
        Supports complex filtering similar to GraphQL capabilities.
        Note: Soft-deleted customers are excluded by default (deletedAt defaults to { isNull: true }).
      operationId: filterCustomers
      tags:
        - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerFilterRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 3
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: Filter customers using comprehensive query criteria with AND/OR logic and multiple operators.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: Supports complex filtering similar to GraphQL capabilities.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: 'Note: Soft-deleted customers are excluded by default (deletedAt defaults to { isNull: true }).'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
  /customers:
    post:
      summary: Create customer
      description: Create a new customer in your organization
      operationId: createCustomer
      tags:
        - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '201':
          description: Customer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /customers/{id}:
    get:
      summary: Get customer
      description: Retrieve a customer by ID or client key
      operationId: getCustomer
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    patch:
      summary: Update customer
      description: Partially update a customer. Only provided fields will be updated.
      operationId: updateCustomer
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerPatch'
      responses:
        '200':
          description: Customer updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      summary: Delete customer
      description: Soft delete a customer (sets deletedAt timestamp)
      operationId: deleteCustomer
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: Customer deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /customers/search:
    post:
      summary: Search customers
      description: |
        Search customers using OpenSearch-powered full-text and field-specific search.

        This endpoint provides fast, indexed search across customer data with support for:
        - Full-text search across multiple fields
        - Field-specific filtering with various operators
        - Sorting and pagination
        - Saved search preferences

        **Note:** Only active (non-deleted) customers are searchable. Soft-deleted records are automatically excluded from all search results.

        **Response Formats:**
        - `flat` (default): Returns indexed fields only for faster performance
        - `full`: Returns complete customer objects with all relationships
      operationId: searchCustomers
      tags:
        - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerSearchRequest'
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /locations/filter:
    post:
      tags:
        - Locations
      summary: Filter locations
      description: |
        Query locations using flexible filter criteria with AND/OR logic.

        By default, only non-deleted locations are returned (deletedAt: { isNull: true }).
        Override this by explicitly setting deletedAt filter criteria.
      operationId: filterLocations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationFilterRequest'
      responses:
        '200':
          description: Filtered locations with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Location'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /locations:
    post:
      tags:
        - Locations
      summary: Create a new location
      description: |
        Create a new location for a customer.

        Locations represent pickup or delivery points (warehouses, distribution centers, etc.).
      operationId: createLocation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationInput'
            examples:
              warehouse:
                summary: Warehouse location
                value:
                  customerId: 550e8400-e29b-41d4-a716-446655440000
                  address:
                    line1: 2100 Ross Ave
                    city: Dallas
                    state: TX
                    zipCode: '75201'
                    country: US
                  name: ABC Warehouse - Dallas
                  key: ERP-LOC-DALLAS-01
                  type: SHIPPER
                  isAppointmentRequired: true
                  notes: Call 24 hours ahead for appointment
              distribution_center:
                summary: Distribution center
                value:
                  customerId: 550e8400-e29b-41d4-a716-446655440000
                  address:
                    line1: 500 Commerce St
                    city: Fort Worth
                    state: TX
                    zipCode: '76102'
                    country: US
                  name: XYZ Distribution Center
                  type: BOTH
                  isAppointmentRequired: false
      responses:
        '201':
          description: Location created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Location'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /locations/{id}:
    get:
      tags:
        - Locations
      summary: Get a location by ID
      description: |
        Retrieve a single location by its unique identifier.
      operationId: getLocationById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Location found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Location'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Locations
      summary: Update a location
      description: |
        Partially update a location. Only provided fields will be updated.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateLocation
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationPatch'
            examples:
              updateNotes:
                summary: Update notes
                value:
                  notes: Updated appointment requirements
              updateType:
                summary: Update location type
                value:
                  type: BOTH
      responses:
        '200':
          description: Location updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Location'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Locations
      summary: Delete a location
      description: |
        Soft delete a location (sets deletedAt timestamp).

        The location will no longer appear in default queries but can be retrieved
        by explicitly filtering for deleted records.
      operationId: deleteLocation
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Location deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /locations/search:
    post:
      summary: Search locations
      description: |
        Search locations using OpenSearch-powered full-text and field-specific search.

        This endpoint provides fast, indexed search across location data with support for:
        - Full-text search across multiple fields
        - Field-specific filtering with various operators
        - Geographic search capabilities
        - Sorting and pagination
        - Saved search preferences

        **Note:** Only active (non-deleted) locations are searchable. Soft-deleted records are automatically excluded from all search results.

        **Response Formats:**
        - `flat` (default): Returns indexed fields only for faster performance
        - `full`: Returns complete location objects with all relationships
      operationId: searchLocations
      tags:
        - Locations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationSearchRequest'
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /location-contacts/filter:
    post:
      tags:
        - Location Contacts
      summary: Filter location contacts
      description: |
        Query location contacts using flexible filter criteria with AND/OR logic.

        By default, only non-deleted location contacts are returned (deletedAt: { isNull: true }).
        Override this by explicitly setting deletedAt filter criteria.
      operationId: filterLocationContacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationContactFilterRequest'
      responses:
        '200':
          description: Filtered location contacts with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LocationContact'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /location-contacts:
    post:
      tags:
        - Location Contacts
      summary: Create a new location contact
      description: |
        Link a customer contact to a location with specific contact types/roles.

        Location contacts represent the relationship between a customer contact
        and a specific location, defining what role the contact has at that location.
      operationId: createLocationContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationContactInput'
            examples:
              primary_manager:
                summary: Primary location manager
                value:
                  locationId: 770e8400-e29b-41d4-a716-446655440000
                  customerContactId: 660e8400-e29b-41d4-a716-446655440000
                  isPrimary: true
                  contactTypes:
                    - LOCATION_MANAGER
                    - SHIPPING
                  key: ERP-LOC-CONTACT-001
              billing_contact:
                summary: Billing contact
                value:
                  locationId: 770e8400-e29b-41d4-a716-446655440000
                  customerContactId: 660e8400-e29b-41d4-a716-446655440001
                  isPrimary: false
                  contactTypes:
                    - BILLING
      responses:
        '201':
          description: Location contact created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /location-contacts/{id}:
    get:
      tags:
        - Location Contacts
      summary: Get a location contact by ID
      description: |
        Retrieve a single location contact by its unique identifier.
      operationId: getLocationContactById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Location contact found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Location Contacts
      summary: Update a location contact
      description: |
        Partially update a location contact. Only provided fields will be updated.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateLocationContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationContactPatch'
            examples:
              updateContactTypes:
                summary: Update contact types
                value:
                  contactTypes:
                    - LOCATION_MANAGER
                    - SHIPPING
                    - RECEIVING
              updatePrimary:
                summary: Set as primary
                value:
                  isPrimary: true
      responses:
        '200':
          description: Location contact updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Location Contacts
      summary: Delete a location contact
      description: |
        Soft delete a location contact (sets deletedAt timestamp).

        The location contact will no longer appear in default queries but can be retrieved
        by explicitly filtering for deleted records.
      operationId: deleteLocationContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Location contact deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /payment-terms/filter:
    post:
      summary: Filter payment terms
      description: |
        Filter payment terms using comprehensive query criteria with AND/OR logic and multiple operators.
        Supports complex filtering similar to GraphQL capabilities.
        Note: Soft-deleted payment terms are excluded by default (deletedAt defaults to { isNull: true }).
      operationId: filterPaymentTerms
      tags:
        - Payment Terms
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentTermFilterRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentTerm'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 3
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: Filter payment terms using comprehensive query criteria with AND/OR logic and multiple operators.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: Supports complex filtering similar to GraphQL capabilities.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: 'Note: Soft-deleted payment terms are excluded by default (deletedAt defaults to { isNull: true }).'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
  /payment-terms:
    post:
      summary: Create payment term
      description: Create a new payment term configuration in your organization
      operationId: createPaymentTerm
      tags:
        - Payment Terms
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentTermInput'
      responses:
        '201':
          description: Payment term created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentTerm'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /payment-terms/{id}:
    get:
      summary: Get payment term
      description: Retrieve a payment term by ID or client key
      operationId: getPaymentTerm
      tags:
        - Payment Terms
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentTerm'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    patch:
      summary: Update payment term
      description: Partially update a payment term. Only provided fields will be updated.
      operationId: updatePaymentTerm
      tags:
        - Payment Terms
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentTermPatch'
      responses:
        '200':
          description: Payment term updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentTerm'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      summary: Delete payment term
      description: Soft delete a payment term (sets deletedAt timestamp)
      operationId: deletePaymentTerm
      tags:
        - Payment Terms
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: Payment term deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /reference-data/equipment:
    get:
      summary: List equipment
      description: |
        Read-only catalog of equipment types. The ids are what order and load
        `equipment` arrays reference. The list is system-managed and small —
        fetch it once and cache it, or hardcode the ids your integration uses.

        The catalog is global and organization-independent: every
        authenticated organization sees the same rows.
      operationId: listReferenceEquipment
      tags:
        - Reference Data
      parameters:
        - name: categoryId
          in: query
          required: false
          description: Only return equipment in this category
          schema:
            type: string
            format: uuid
        - name: groupId
          in: query
          required: false
          description: Only return equipment in this top-level group
          schema:
            type: string
            format: uuid
        - name: subcategoryId
          in: query
          required: false
          description: Only return equipment in this subcategory
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Equipment'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /reference-data/charge-codes:
    get:
      summary: List charge codes
      description: |
        Read-only catalog of charge codes. The integer ids are what charge
        `chargeCodeId` fields reference. The list is system-managed — fetch it
        once and cache it.

        The catalog is global and organization-independent: every
        authenticated organization sees the same rows.
      operationId: listReferenceChargeCodes
      tags:
        - Reference Data
      parameters:
        - name: code
          in: query
          required: false
          description: Only return the charge code with this exact accounting code
          schema:
            type: string
            example: LH
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChargeCode'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /reference-data/special-requirements:
    get:
      summary: List special requirements
      description: |
        Read-only catalog of special requirements (equipment accessories,
        driver services, freight handling, location constraints). The ids are
        what order and load `specialRequirements` arrays reference. Filter by
        `type` to get one category.

        The catalog is global and organization-independent: every
        authenticated organization sees the same rows.
      operationId: listReferenceSpecialRequirements
      tags:
        - Reference Data
      parameters:
        - name: type
          in: query
          required: false
          description: Only return requirements of this type
          schema:
            $ref: '#/components/schemas/SpecialRequirementType'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SpecialRequirement'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /teams/filter:
    post:
      summary: Filter teams
      description: |
        Filter teams using comprehensive query criteria with AND/OR logic and multiple operators.
        Supports complex filtering similar to GraphQL capabilities.
        Note: Soft-deleted teams are excluded by default (deletedAt defaults to { isNull: true }).
      operationId: filterTeams
      tags:
        - Teams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamFilterRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 3
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: Filter teams using comprehensive query criteria with AND/OR logic and multiple operators.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: Supports complex filtering similar to GraphQL capabilities.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: 'Note: Soft-deleted teams are excluded by default (deletedAt defaults to { isNull: true }).'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
  /teams:
    post:
      summary: Create team
      description: Create a new team in your organization
      operationId: createTeam
      tags:
        - Teams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamInput'
      responses:
        '201':
          description: Team created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /teams/{id}:
    get:
      summary: Get team
      description: Retrieve a team by ID or client key
      operationId: getTeam
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    patch:
      summary: Update team
      description: Partially update a team. Only provided fields will be updated.
      operationId: updateTeam
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamPatch'
      responses:
        '200':
          description: Team updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      summary: Delete team
      description: Soft delete a team (sets deletedAt timestamp)
      operationId: deleteTeam
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: Team deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /users/filter:
    post:
      summary: Filter users
      description: |
        Filter users using comprehensive query criteria with AND/OR logic and multiple operators.
        Supports complex filtering similar to GraphQL capabilities.
        Note: Soft-deleted users are excluded by default (deletedAt defaults to { isNull: true }).
      operationId: filterUsers
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserFilterRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 3
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: Filter users using comprehensive query criteria with AND/OR logic and multiple operators.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: Supports complex filtering similar to GraphQL capabilities.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: 'Note: Soft-deleted users are excluded by default (deletedAt defaults to { isNull: true }).'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
  /users:
    post:
      summary: Create user
      description: Create a new user in your organization
      operationId: createUser
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /users/{id}:
    get:
      summary: Get user
      description: Retrieve a user by ID or client key
      operationId: getUser
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    patch:
      summary: Update user
      description: Partially update a user. Only provided fields will be updated.
      operationId: updateUser
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPatch'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      summary: Delete user
      description: Soft delete a user (sets deletedAt timestamp)
      operationId: deleteUser
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: User deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /users/search:
    post:
      summary: Search users
      description: |
        Search users using OpenSearch-powered full-text and field-specific search.

        This endpoint provides fast, indexed search across user data with support for:
        - Full-text search across multiple fields
        - Field-specific filtering with various operators
        - Sorting and pagination
        - Saved search preferences

        **Note:** Only active (non-deleted) users are searchable. Soft-deleted records are automatically excluded from all search results.

        **Response Formats:**
        - `flat` (default): Returns indexed fields only for faster performance
        - `full`: Returns complete user objects with all relationships
      operationId: searchUsers
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSearchRequest'
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /vendors/filter:
    post:
      tags:
        - Vendors
      summary: Filter vendors
      description: |
        Query vendors using flexible filter criteria with AND/OR logic.

        By default, only non-deleted vendors are returned (deletedAt: { isNull: true }).
        Override this by explicitly setting deletedAt filter criteria.
      operationId: filterVendors
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorFilterRequest'
      responses:
        '200':
          description: Filtered vendors with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Vendor'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendors:
    post:
      tags:
        - Vendors
      summary: Create a new vendor
      description: |
        Create a new vendor within an organization.

        Vendors represent service providers (warehousing, storage, etc.) that are not carriers.
      operationId: createVendor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorInput'
            examples:
              warehouse:
                summary: Warehouse vendor
                value:
                  name: ABC Warehouse Services
                  email: billing@abcwarehouse.com
                  phone: +1-555-123-4567
                  status: ACTIVE
                  currency: USD
                  taxId: 12-3456789
              storage:
                summary: Storage facility
                value:
                  name: SecureStore Facilities
                  email: accounts@securestore.com
                  phone: +1-555-987-6543
                  status: ACTIVE
                  currency: USD
      responses:
        '201':
          description: Vendor created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vendor'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendors/{id}:
    get:
      tags:
        - Vendors
      summary: Get a vendor by ID
      description: |
        Retrieve a single vendor by its unique identifier.
      operationId: getVendorById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Vendor found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vendor'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Vendors
      summary: Update a vendor
      description: |
        Partially update a vendor. Only provided fields will be updated.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateVendor
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorPatch'
            examples:
              updateContact:
                summary: Update contact information
                value:
                  email: newemail@abcwarehouse.com
                  phone: +1-555-999-8888
              updateStatus:
                summary: Update vendor status
                value:
                  status: INACTIVE
                  notes: Contract ended
      responses:
        '200':
          description: Vendor updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vendor'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Vendors
      summary: Delete a vendor
      description: |
        Soft delete a vendor (sets deletedAt timestamp).

        The vendor will no longer appear in default queries but can be retrieved
        by explicitly filtering for deleted records.
      operationId: deleteVendor
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Vendor deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendors/search:
    post:
      summary: Search vendors
      description: |
        Search vendors using OpenSearch-powered full-text and field-specific search.

        This endpoint provides fast, indexed search across vendor data with support for:
        - Full-text search across multiple fields
        - Field-specific filtering with various operators
        - Sorting and pagination
        - Saved search preferences

        **Note:** Only active (non-deleted) vendors are searchable. Soft-deleted records are automatically excluded from all search results.

        **Response Formats:**
        - `flat` (default): Returns indexed fields only for faster performance
        - `full`: Returns complete vendor objects with all relationships
      operationId: searchVendors
      tags:
        - Vendors
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorSearchRequest'
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /vendor-contacts/filter:
    post:
      tags:
        - Vendor Contacts
      summary: Filter vendor contacts
      description: |
        Query vendor contacts using flexible filter criteria with AND/OR logic.

        By default, only non-deleted contacts are returned (deletedAt: { isNull: true }).
        Override this by explicitly setting deletedAt filter criteria.
      operationId: filterVendorContacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorContactFilterRequest'
      responses:
        '200':
          description: Filtered vendor contacts with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/VendorContact'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendor-contacts:
    post:
      tags:
        - Vendor Contacts
      summary: Create a new vendor contact
      description: |
        Create a new contact for a vendor.

        Contacts represent individuals at the vendor who can be reached for various purposes.
      operationId: createVendorContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorContactInput'
            examples:
              billing:
                summary: Billing contact
                value:
                  vendorId: 550e8400-e29b-41d4-a716-446655440001
                  name: Dana Reyes
                  email: billing@abcwarehouse.com
                  phone: +1-555-123-4567
                  roles:
                    - BILLING
              operations:
                summary: Operations contact
                value:
                  vendorId: 550e8400-e29b-41d4-a716-446655440001
                  name: Sam Okafor
                  email: ops@abcwarehouse.com
                  phone: +1-555-987-6543
                  roles:
                    - OPERATION
                    - AGENT
      responses:
        '201':
          description: Vendor contact created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendor-contacts/{id}:
    get:
      tags:
        - Vendor Contacts
      summary: Get a vendor contact by ID
      description: |
        Retrieve a single vendor contact by its unique identifier.
      operationId: getVendorContactById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Vendor contact found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Vendor Contacts
      summary: Update a vendor contact
      description: |
        Partially update a vendor contact. Only provided fields will be updated.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateVendorContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorContactPatch'
            examples:
              updateEmail:
                summary: Update email address
                value:
                  email: newemail@abcwarehouse.com
              updateRoles:
                summary: Update contact roles
                value:
                  roles:
                    - BILLING
                    - OWNER
      responses:
        '200':
          description: Vendor contact updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Vendor Contacts
      summary: Delete a vendor contact
      description: |
        Soft delete a vendor contact (sets deletedAt timestamp).

        The contact will no longer appear in default queries but can be retrieved
        by explicitly filtering for deleted records.
      operationId: deleteVendorContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Vendor contact deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendor-payment-methods/filter:
    post:
      tags:
        - Vendor Payment Methods
      summary: Filter vendor payment methods
      description: |
        Query vendor payment methods using flexible filter criteria with AND/OR logic.

        By default, only non-deleted payment methods are returned (deletedAt: { isNull: true }).
        Override this by explicitly setting deletedAt filter criteria.

        Vendor payment methods define how and where payments are sent for a specific vendor.
      operationId: filterVendorPaymentMethods
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorPaymentMethodFilterRequest'
      responses:
        '200':
          description: Filtered vendor payment methods with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/VendorPaymentMethod'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendor-payment-methods:
    post:
      tags:
        - Vendor Payment Methods
      summary: Create vendor payment method
      description: |
        Create a new vendor payment method.

        **Important**: The `vendorId` cannot be changed after creation.
      operationId: createVendorPaymentMethod
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorPaymentMethodInput'
            examples:
              achPayment:
                summary: ACH payment to vendor
                value:
                  vendorId: 770e8400-e29b-41d4-a716-446655440000
                  paymentMethodType: ACH
                  isPreferred: true
                  bankName: Chase Bank
                  accountName: Vendor Services Inc
                  accountNumber: '1234567890'
                  abaAch: '021000021'
                  currency: USD
              zelle:
                summary: Zelle payment
                value:
                  vendorId: 770e8400-e29b-41d4-a716-446655440000
                  paymentMethodType: ZELLE
                  email: payments@vendor.com
                  phone: +1-555-123-4567
                  username: vendor_payments
              check:
                summary: Check payment
                value:
                  vendorId: 770e8400-e29b-41d4-a716-446655440000
                  paymentMethodType: CHECK
                  companyName: Vendor Services Inc
                  isPreferred: false
      responses:
        '201':
          description: Vendor payment method created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorPaymentMethod'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendor-payment-methods/{id}:
    get:
      tags:
        - Vendor Payment Methods
      summary: Get vendor payment method
      description: |
        Retrieve a single vendor payment method by its unique identifier.

        Returns full details including banking information and associated vendor references.
      operationId: getVendorPaymentMethodById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Vendor payment method found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorPaymentMethod'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Vendor Payment Methods
      summary: Update vendor payment method
      description: |
        Partially update a vendor payment method. Only provided fields will be updated.

        **IMPORTANT**: The `vendorId` field cannot be changed after creation.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateVendorPaymentMethod
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorPaymentMethodPatch'
            examples:
              updateBanking:
                summary: Update banking details
                value:
                  bankName: Bank of America
                  accountNumber: '9876543210'
                  abaAch: '026009593'
              makePreferred:
                summary: Set as preferred payment method
                value:
                  isPreferred: true
              updateContact:
                summary: Update contact information
                value:
                  email: newemail@vendor.com
                  phone: +1-555-999-8888
      responses:
        '200':
          description: Vendor payment method updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorPaymentMethod'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Vendor Payment Methods
      summary: Delete vendor payment method
      description: |
        Soft delete a vendor payment method (sets deletedAt timestamp).

        The payment method will no longer appear in default queries but can be retrieved
        by explicitly filtering for deleted records.
      operationId: deleteVendorPaymentMethod
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Vendor payment method deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /saved-searches/filter:
    post:
      summary: Filter saved searches
      description: |
        Filter saved searches using comprehensive query criteria with AND/OR logic and multiple operators.
        Supports complex filtering similar to GraphQL capabilities.
        Returns only saved searches accessible to the authenticated user (either owned by them or public).
      operationId: filterSavedSearches
      tags:
        - Saved Searches
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedSearchFilterRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SavedSearch'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /saved-searches:
    post:
      summary: Create saved search
      description: |
        Create a new saved search configuration in your organization.
        The saved search can be used to quickly apply predefined search criteria, sorting, and display preferences.

        The saved search will be owned by the authenticated user unless otherwise specified.
      operationId: createSavedSearch
      tags:
        - Saved Searches
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedSearchInput'
      responses:
        '201':
          description: Saved search created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearch'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /saved-searches/{id}:
    get:
      summary: Get saved search
      description: |
        Retrieve a saved search by ID.
        You can only retrieve saved searches that you own or that are public in your organization.
      operationId: getSavedSearch
      tags:
        - Saved Searches
      parameters:
        - name: id
          in: path
          required: true
          description: Saved search UUID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearch'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    patch:
      summary: Update saved search
      description: |
        Partially update a saved search. Only provided fields will be updated.
        You can only update saved searches that you own.
      operationId: updateSavedSearch
      tags:
        - Saved Searches
      parameters:
        - name: id
          in: path
          required: true
          description: Saved search UUID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedSearchPatch'
      responses:
        '200':
          description: Saved search updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearch'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      summary: Delete saved search
      description: |
        Permanently delete a saved search.
        You can only delete saved searches that you own.
      operationId: deleteSavedSearch
      tags:
        - Saved Searches
      parameters:
        - name: id
          in: path
          required: true
          description: Saved search UUID
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Saved search deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /shipments/track:
    post:
      summary: Get tracking link
      description: |
        Search for shipments by reference field values (BOL #, PRO #, MAWB #, etc.)
        and return tracking information.

        ## Usage

        1. Provide an array of search queries in the `searches` field
        2. Optionally filter which reference field types to search using `referenceFields`
        3. Results are returned in the same order as input searches
        4. If no match is found, the result contains only the original `query` (other fields are null)

        ## Matching Behavior

        - Searches are case-insensitive
        - If multiple shipments match a query, the most recently created shipment is returned
        - If `referenceFields` is omitted, all reference field types are searched

        ## Example Use Cases

        - **Customer portal**: Look up shipment status by BOL or PRO number
        - **EDI integration**: Validate shipment references before sending updates
        - **Bulk status check**: Query multiple shipments in a single request

        ## Rate Limits

        - Maximum 100 searches per request
        - Standard API rate limits apply (see Rate Limiting documentation)
      operationId: trackShipments
      tags:
        - Shipments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentTrackRequest'
            examples:
              singleSearch:
                summary: Single shipment lookup
                description: Look up a single shipment by reference value
                value:
                  searches:
                    - query: MAWB123456
              multipleSearches:
                summary: Multiple shipments with field filter
                description: Look up multiple shipments, limiting search to specific reference field types
                value:
                  searches:
                    - query: MAWB123456
                    - query: BOL789
                    - query: PRO-001
                  referenceFields:
                    - MASTER_AIRWAYBILL_NUMBER
                    - BOL_NUMBER
                    - PRO_NUMBER
              bulkLookup:
                summary: Bulk BOL lookup
                description: Look up multiple shipments by BOL number only
                value:
                  searches:
                    - query: BOL-2025-001
                    - query: BOL-2025-002
                    - query: BOL-2025-003
                    - query: BOL-2025-004
                  referenceFields:
                    - BOL_NUMBER
      responses:
        '200':
          description: Track results returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentTrackResponse'
              examples:
                allFound:
                  summary: All shipments found
                  description: All search queries returned matching shipments
                  value:
                    results:
                      - query: MAWB123456
                        id: 550e8400-e29b-41d4-a716-446655440000
                        key: SHIP-001
                        friendlyId: SHP-12345
                        status: IN_TRANSIT
                        field: MASTER_AIRWAYBILL_NUMBER
                        value: MAWB123456
                        origin: Los Angeles, CA 90210
                        destination: New York, NY 10001
                        pickUpDate: '2025-01-15'
                        deliveryDate: '2025-01-20'
                        trackingUrl: https://app.mvmnt.io/shipments/550e8400-e29b-41d4-a716-446655440000
                      - query: BOL789012
                        id: 660e8400-e29b-41d4-a716-446655440001
                        key: SHIP-002
                        friendlyId: SHP-12346
                        status: DELIVERED
                        field: BOL_NUMBER
                        value: BOL-789012
                        origin: Chicago, IL 60601
                        destination: Miami, FL 33101
                        pickUpDate: '2025-01-16'
                        deliveryDate: '2025-01-21'
                        trackingUrl: https://app.mvmnt.io/shipments/660e8400-e29b-41d4-a716-446655440001
                mixedResults:
                  summary: Some found, some not found
                  description: Mix of found and not-found results
                  value:
                    results:
                      - query: MAWB123456
                        id: 550e8400-e29b-41d4-a716-446655440000
                        key: SHIP-001
                        friendlyId: SHP-12345
                        status: PICKED_UP
                        field: MASTER_AIRWAYBILL_NUMBER
                        value: MAWB123456
                        origin: Los Angeles, CA 90210
                        destination: New York, NY 10001
                        pickUpDate: '2025-01-15'
                        deliveryDate: '2025-01-20'
                        trackingUrl: https://app.mvmnt.io/shipments/550e8400-e29b-41d4-a716-446655440000
                      - query: NOTFOUND123
                        id: null
                        key: null
                        friendlyId: null
                        status: null
                        field: null
                        value: null
                        origin: null
                        destination: null
                        pickUpDate: null
                        deliveryDate: null
                        trackingUrl: null
                noneFound:
                  summary: No shipments found
                  description: No matching shipments for any query
                  value:
                    results:
                      - query: UNKNOWN-REF-1
                        id: null
                        key: null
                        friendlyId: null
                        status: null
                        field: null
                        value: null
                        origin: null
                        destination: null
                        pickUpDate: null
                        deliveryDate: null
                        trackingUrl: null
                      - query: UNKNOWN-REF-2
                        id: null
                        key: null
                        friendlyId: null
                        status: null
                        field: null
                        value: null
                        origin: null
                        destination: null
                        pickUpDate: null
                        deliveryDate: null
                        trackingUrl: null
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /documents/filter:
    post:
      summary: Filter documents
      description: |
        Search for documents using filter criteria.

        ## Usage

        Documents are typically associated with other entities (orders, loads, services).
        Use filters to find documents by type, status, or date range.

        ## Example Filters

        - Find all invoices: `{ "filter": { "type": { "equalTo": "INVOICE" } } }`
        - Find uploaded documents: `{ "filter": { "status": { "equalTo": "UPLOADED" } } }`
        - Find documents created today: `{ "filter": { "createdAt": { "greaterThanOrEqualTo": "2025-01-15T00:00:00Z" } } }`
      operationId: filterDocuments
      tags:
        - Documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentFilterRequest'
            examples:
              filterByType:
                summary: Filter by document type
                value:
                  filter:
                    type:
                      equalTo: INVOICE
                  pageSize: 50
              filterByStatus:
                summary: Filter by upload status
                value:
                  filter:
                    status:
                      equalTo: UPLOADED
              filterByDateRange:
                summary: Filter by creation date
                value:
                  filter:
                    createdAt:
                      greaterThanOrEqualTo: '2025-01-01T00:00:00Z'
                      lessThanOrEqualTo: '2025-01-31T23:59:59Z'
      responses:
        '200':
          description: Documents matching filter criteria
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Document'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /documents:
    post:
      summary: Create a document
      description: |
        Create a new document record and receive a pre-signed URL for uploading the file.

        ## Workflow

        1. Call this endpoint with document metadata (type, fileName, contentType)
        2. Receive the created document with an `uploadUrl`
        3. Upload the file directly to S3 using the `uploadUrl` (PUT request)
        4. Document status changes from `PENDING_UPLOAD` to `UPLOADED` automatically

        ## Upload Instructions

        The `uploadUrl` is a pre-signed S3 URL. Upload your file with:

        ```bash
        curl -X PUT -H "Content-Type: application/pdf" \
          --data-binary @your-file.pdf \
          "https://s3.amazonaws.com/bucket/key?signature=..."
        ```

        **Important:**
        - The `uploadUrl` expires after 15 minutes
        - Use the exact `contentType` specified in the request
        - Maximum file size: 100MB
      operationId: createDocument
      tags:
        - Documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentInput'
            examples:
              pdfInvoice:
                summary: Create PDF invoice document
                value:
                  type: INVOICE
                  fileName: invoice-2025-001.pdf
                  contentType: application/pdf
                  fileSize: 102400
                  tags:
                    invoiceNumber: INV-2025-001
              podImage:
                summary: Create POD image
                value:
                  type: PROOF_OF_DELIVERY
                  fileName: pod-delivery-photo.jpg
                  contentType: image/jpeg
      responses:
        '201':
          description: Document created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
              examples:
                created:
                  summary: Newly created document with upload URL
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    type: INVOICE
                    fileName: invoice-2025-001.pdf
                    extension: pdf
                    contentType: application/pdf
                    fileSize: 102400
                    status: PENDING_UPLOAD
                    uploadUrl: https://s3.amazonaws.com/bucket/key?X-Amz-Signature=...
                    downloadUrl: null
                    tags:
                      invoiceNumber: INV-2025-001
                    createdAt: '2025-01-15T10:30:00Z'
                    updatedAt: null
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /documents/{id}:
    get:
      summary: Get a document
      description: |
        Retrieve a document by ID or key.

        Returns the document metadata including a fresh `downloadUrl` if the file is uploaded.

        **Note:** The `downloadUrl` is a pre-signed S3 URL that expires after 1 hour.
        Each GET request generates a fresh URL.
      operationId: getDocument
      tags:
        - Documents
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Document retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
              examples:
                uploaded:
                  summary: Document with download URL
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    key: doc-inv-2025-001
                    type: INVOICE
                    fileName: invoice-2025-001.pdf
                    extension: pdf
                    contentType: application/pdf
                    fileSize: 102400
                    status: UPLOADED
                    uploadUrl: null
                    downloadUrl: https://s3.amazonaws.com/bucket/key?X-Amz-Signature=...
                    tags:
                      invoiceNumber: INV-2025-001
                    createdAt: '2025-01-15T10:30:00Z'
                    updatedAt: '2025-01-15T10:35:00Z'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    patch:
      summary: Update a document
      description: |
        Update document metadata.

        **Note:** File content cannot be changed after upload.
        To replace a file, create a new document.
      operationId: updateDocument
      tags:
        - Documents
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentPatch'
            examples:
              updateTags:
                summary: Update document tags
                value:
                  tags:
                    invoiceNumber: INV-2025-001-REVISED
                    approved: true
              updateType:
                summary: Change document type
                value:
                  type: PROOF_OF_DELIVERY
      responses:
        '200':
          description: Document updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      summary: Delete a document
      description: |
        Soft delete a document.

        The document record is marked as deleted but not permanently removed.
        Associated files in S3 may be cleaned up asynchronously.
      operationId: deleteDocument
      tags:
        - Documents
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: Document deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /quotes/filter:
    post:
      summary: Filter quotes
      description: |
        Search for quotes using filter criteria.

        ## Common Filters

        - Active quotes: `{ "filter": { "status": { "in": ["DRAFT", "REQUESTED", "QUOTED"] } } }`
        - Won quotes: `{ "filter": { "status": { "equalTo": "WON" } } }`
        - By customer: `{ "filter": { "customerId": { "equalTo": "uuid" } } }`
        - Expiring soon: `{ "filter": { "expiresAt": { "lessThanOrEqualTo": "2025-01-20T00:00:00Z" } } }`
      operationId: filterQuotes
      tags:
        - Quotes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteFilterRequest'
            examples:
              activeQuotes:
                summary: Filter active quotes
                value:
                  filter:
                    status:
                      in:
                        - DRAFT
                        - REQUESTED
                        - QUOTED
                  pageSize: 50
              byCustomer:
                summary: Filter by customer
                value:
                  filter:
                    customerId:
                      equalTo: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Quotes matching filter criteria
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Quote'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /quotes:
    post:
      summary: Create a quote
      description: |
        Create a new quote with order details.

        ## How it works

        Creating a quote also creates an associated Order containing the route and freight details.
        The Order is embedded in the Quote and cannot be managed separately.

        ## Required fields

        - `customer`: Reference to the customer (shipper profile)
        - `order`: Order details including stops and mode

        ## Example workflow

        1. Create quote with customer and order details
        2. Add pricing (amount) via PATCH
        3. Send to customer (status changes to QUOTED)
        4. Convert to shipment when accepted (POST /quotes/{id}/convert-to-shipment)
      operationId: createQuote
      tags:
        - Quotes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteInput'
            examples:
              basicQuote:
                summary: Basic FTL quote
                value:
                  customer:
                    id: 550e8400-e29b-41d4-a716-446655440000
                  order:
                    mode: FTL
                    stops:
                      - type: PICKUP
                        address:
                          line1: 123 Warehouse Ave
                          city: Los Angeles
                          country: US
                          market: LAX
                        requestedStartDate: '2025-01-20'
                      - type: DELIVERY
                        address:
                          line1: 456 Distribution Center
                          city: New York
                          country: US
                          market: JFK
                        requestedStartDate: '2025-01-25'
                    freight:
                      handlingUnitQuantity: 10
                      handlingUnitType: PALLET
                      weight: 15000
                  amount: 2500
                  expiresAt: '2025-01-18T23:59:59Z'
      responses:
        '201':
          description: Quote created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /quotes/{id}:
    get:
      summary: Get a quote
      description: |
        Retrieve a quote by ID or key.

        The response includes embedded order details (route, freight, equipment).
      operationId: getQuote
      tags:
        - Quotes
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Quote retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    patch:
      summary: Update a quote
      description: |
        Update quote fields including status changes.

        ## Status changes

        Status changes use this endpoint (not separate action endpoints):
        - Set to QUOTED: `{ "status": "QUOTED", "amount": 2500 }`
        - Set to WON: `{ "status": "WON" }`
        - Set to LOST: `{ "status": "LOST", "lostReason": "TOO_HIGH" }`

        ## Validation rules

        - When setting `status` to `LOST`, `lostReason` is required
        - When `lostReason` is `OTHER`, `lostReasonText` is required

        ## Note

        To convert a won quote to a shipment, use POST /quotes/{id}/convert-to-shipment
      operationId: updateQuote
      tags:
        - Quotes
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuotePatch'
            examples:
              setQuoted:
                summary: Set quote as quoted
                value:
                  status: QUOTED
                  amount: 2500
              setWon:
                summary: Mark quote as won
                value:
                  status: WON
              setLost:
                summary: Mark quote as lost
                value:
                  status: LOST
                  lostReason: TOO_HIGH
              setLostOther:
                summary: Mark lost with custom reason
                value:
                  status: LOST
                  lostReason: OTHER
                  lostReasonText: Customer chose competitor with faster transit time
      responses:
        '200':
          description: Quote updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      summary: Delete a quote
      description: |
        Soft delete a quote.

        The quote record is marked as deleted but not permanently removed.
        Associated orders are also soft deleted.
      operationId: deleteQuote
      tags:
        - Quotes
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: Quote deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /quotes/{id}/convert-to-shipment:
    post:
      summary: Convert quote to shipment
      description: |
        Convert an accepted quote into a shipment.

        ## What happens

        1. Quote status is set to WON (if not already)
        2. A new Shipment is created
        3. The Order from the quote is linked to the shipment
        4. Optionally, additional orders can be added

        ## Prerequisites

        - Quote must be in QUOTED or WON status
        - Quote cannot already have a shipment

        ## Response

        Returns the IDs of both the quote and the newly created shipment.
      operationId: convertQuoteToShipment
      tags:
        - Quotes
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConvertToShipmentRequest'
            examples:
              simpleConvert:
                summary: Simple conversion
                value: {}
              withAdditionalOrder:
                summary: Add additional order
                value:
                  additionalOrders:
                    - mode: FTL
                      stops:
                        - type: PICKUP
                          location:
                            id: 550e8400-e29b-41d4-a716-446655440001
                          requestedStartDate: '2025-01-22'
                        - type: DELIVERY
                          location:
                            id: 550e8400-e29b-41d4-a716-446655440002
                          requestedStartDate: '2025-01-27'
      responses:
        '200':
          description: Quote converted to shipment successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConvertToShipmentResponse'
              examples:
                converted:
                  summary: Successful conversion
                  value:
                    quoteId: 550e8400-e29b-41d4-a716-446655440000
                    quoteStatus: WON
                    shipmentId: 660e8400-e29b-41d4-a716-446655440001
                    shipmentKey: SHP-12345
                    orderId: 770e8400-e29b-41d4-a716-446655440002
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
  /shipments/search:
    post:
      summary: Search shipments
      description: |
        Search shipments using OpenSearch-powered full-text and field-specific search.

        This endpoint provides fast, indexed search across shipment data with support for:
        - Full-text search across multiple fields (references, locations, parties)
        - Field-specific filtering with various operators
        - Sorting and pagination
        - Saved search preferences

        **Note:** Only active (non-deleted) shipments are searchable. Soft-deleted records are
        automatically excluded from all search results.

        **Response Formats:**
        - `flat` (default): Returns indexed fields only for faster performance
        - `full`: Returns complete shipment objects with all relationships
      operationId: searchShipments
      tags:
        - Shipments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentSearchRequest'
            examples:
              byCustomer:
                summary: Shipments for a customer
                value:
                  criteria:
                    shipperName:
                      operator: INCLUDES
                      values:
                        - Acme
                  pagination:
                    pageNumber: 1
                    pageSize: 50
              byStatus:
                summary: In-transit shipments
                value:
                  criteria:
                    status:
                      operator: ONE_OF
                      values:
                        - IN_TRANSIT
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /shipments/filter:
    post:
      summary: Filter shipments
      description: |
        Search for shipments using filter criteria.

        Each row in the response carries the fully nested shipment payload
        (orders with stops, freight, references, charges; loads with
        carriers). With a large `pageSize`, responses can be sizable — use a
        smaller page size if you only need scalar fields.

        ## Common Filters

        - Active shipments: `{ "filter": { "status": { "notIn": ["DELIVERED", "CANCELED"] } } }`
        - Delivered today: `{ "filter": { "deliveredAt": { "greaterThanOrEqualTo": "2025-01-15T00:00:00Z" } } }`
        - By customer: `{ "filter": { "customerId": { "equalTo": "uuid" } } }`
      operationId: filterShipments
      tags:
        - Shipments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentFilterRequest'
            examples:
              activeShipments:
                summary: Filter active shipments
                value:
                  filter:
                    status:
                      notIn:
                        - DELIVERED
                        - CANCELED
                  pageSize: 50
              inTransit:
                summary: Filter in-transit shipments
                value:
                  filter:
                    status:
                      equalTo: IN_TRANSIT
      responses:
        '200':
          description: Shipments matching filter criteria
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Shipment'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /shipments:
    post:
      summary: Create a shipment
      description: |
        Create a new shipment with orders, loads, and services.

        ## Required fields

        - `customer`: Reference to the customer
        - `orders`: At least one order with stops and mode

        ## What gets created

        - Shipment record
        - Order(s) with stops, freight, and charges
        - Optionally: Load(s) and Service(s)

        ## Relationship to Quotes

        If you have a Quote, use `POST /quotes/{id}/convert-to-shipment` instead.
        Direct shipment creation is for cases without a quote.
      operationId: createShipment
      tags:
        - Shipments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentInput'
            examples:
              basicShipment:
                summary: Basic FTL shipment
                value:
                  customer:
                    id: 550e8400-e29b-41d4-a716-446655440000
                  orders:
                    - mode: FTL
                      stops:
                        - type: PICKUP
                          location:
                            id: 660e8400-e29b-41d4-a716-446655440001
                          requestedStartDate: '2025-01-20'
                        - type: DELIVERY
                          location:
                            id: 770e8400-e29b-41d4-a716-446655440002
                          requestedStartDate: '2025-01-25'
                      freight:
                        handlingUnitQuantity: 10
                        handlingUnitType: PALLET
                        weight: 15000
      responses:
        '201':
          description: Shipment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /shipments/{id}:
    get:
      summary: Get a shipment
      description: |
        Retrieve a shipment by ID or key.

        The response includes embedded orders, loads, and services.
        The internal ShipmentDetail layer is hidden - all data is flattened.
      operationId: getShipment
      tags:
        - Shipments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Shipment retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    patch:
      summary: Update a shipment
      description: |
        Update shipment fields.

        **Note:** To update orders, loads, or services, use their respective endpoints:
        - Orders: Updates happen via order-specific endpoints
        - Loads: PATCH /loads/{id}
        - Services: PATCH /services/{id}
      operationId: updateShipment
      tags:
        - Shipments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentPatch'
            examples:
              changeCustomerRep:
                summary: Change customer rep
                value:
                  customerRep:
                    id: 550e8400-e29b-41d4-a716-446655440001
      responses:
        '200':
          description: Shipment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      summary: Delete a shipment
      description: |
        Soft delete a shipment.

        The shipment and all associated orders, loads, and services are marked as deleted.
      operationId: deleteShipment
      tags:
        - Shipments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: Shipment deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /shipments/{id}/cancel:
    post:
      summary: Cancel a shipment
      description: |
        Cancel a shipment.

        ## What happens

        - Shipment status is set to CANCELED
        - All orders are canceled
        - All loads are canceled
        - All services are canceled

        ## Prerequisites

        - Shipment must not already be delivered or canceled
      operationId: cancelShipment
      tags:
        - Shipments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelShipmentRequest'
            examples:
              withReason:
                summary: Cancel with reason
                value:
                  reason: Customer requested cancellation due to production delay
      responses:
        '200':
          description: Shipment canceled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Cannot cancel - shipment is delivered or already canceled
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /shipments/{id}/uncancel:
    post:
      summary: Un-cancel a shipment
      description: |
        Reactivate a canceled shipment.

        ## What happens

        - Shipment status is restored to previous state
        - Orders, loads, and services are reactivated

        ## Prerequisites

        - Shipment must be in CANCELED status
      operationId: uncancelShipment
      tags:
        - Shipments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Shipment un-canceled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Cannot un-cancel - shipment is not canceled
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /shipments/{id}/duplicate:
    post:
      summary: Duplicate a shipment
      description: |
        Create a copy of an existing shipment.

        ## What gets duplicated

        - Customer and customer rep
        - Order(s) with stops, freight, and references
        - Equipment and special requirements

        ## What is NOT duplicated

        - Loads and carriers
        - Services
        - Documents
        - Status history

        ## New shipment

        The duplicate is created in DRAFT status with new dates if provided.
      operationId: duplicateShipment
      tags:
        - Shipments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DuplicateShipmentRequest'
            examples:
              withNewDates:
                summary: Duplicate with new dates
                value:
                  pickUpDate: '2025-02-01'
                  deliveryDate: '2025-02-05'
      responses:
        '201':
          description: Shipment duplicated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DuplicateShipmentResponse'
              example:
                originalShipmentId: 550e8400-e29b-41d4-a716-446655440000
                newShipmentId: 660e8400-e29b-41d4-a716-446655440001
                newShipmentKey: SHP-12346
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /shipments/{id}/ready-to-invoice:
    post:
      summary: Mark shipment ready to invoice
      description: |
        Mark a shipment as ready for invoicing.

        ## What happens

        - Shipment billing status changes to READY_TO_INVOICE
        - Shipment is now visible in invoice generation workflows

        ## Prerequisites

        - Shipment must have delivery documents attached
        - Shipment must be in DOCS_NEEDED or NOT_READY_TO_INVOICE status
      operationId: markShipmentReadyToInvoice
      tags:
        - Shipments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Shipment marked ready to invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Shipment not in valid status for this action
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /shipments/{id}/not-ready-to-invoice:
    post:
      summary: Revert shipment to not ready
      description: |
        Revert a shipment from ready-to-invoice back to not ready.

        ## What happens

        - Shipment billing status changes back to NOT_READY_TO_INVOICE

        ## Prerequisites

        - Shipment must be in READY_TO_INVOICE status
        - Shipment must not already be invoiced
      operationId: markShipmentNotReadyToInvoice
      tags:
        - Shipments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Shipment reverted to not ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Shipment not in valid status for this action
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /shipments/{id}/invoice/generate:
    post:
      summary: Generate invoice for shipment
      description: |
        Generate an invoice PDF for the shipment.

        ## What happens

        - Invoice PDF is generated
        - Invoice document is attached to the shipment
        - Shipment billing status changes to INVOICED

        ## Prerequisites

        - Shipment must be in READY_TO_INVOICE status
      operationId: generateShipmentInvoice
      tags:
        - Shipments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Invoice generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  shipmentId:
                    type: string
                    format: uuid
                  invoiceId:
                    type: string
                    format: uuid
                    description: The generated invoice ID
                  documentId:
                    type: string
                    format: uuid
                    description: The invoice PDF document ID
                  downloadUrl:
                    type: string
                    format: uri
                    description: URL to download the invoice PDF
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Shipment not in valid status for invoice generation
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /loads/filter:
    post:
      summary: Filter loads
      description: |
        Search for loads using filter criteria.

        Each row carries the fully nested load payload (stops with addresses,
        carriers with charges). With a large `pageSize`, responses can be
        sizable.

        ## Common Filters

        - By shipment: `{ "filter": { "shipmentId": { "equalTo": "uuid" } } }`
        - Active loads: `{ "filter": { "status": { "notIn": ["COMPLETE", "CANCELED"] } } }`
        - FTL loads: `{ "filter": { "mode": { "equalTo": "FTL" } } }`
      operationId: filterLoads
      tags:
        - Loads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoadFilterRequest'
            examples:
              byShipment:
                summary: Filter by shipment
                value:
                  filter:
                    shipmentId:
                      equalTo: 550e8400-e29b-41d4-a716-446655440000
              activeLoads:
                summary: Active loads only
                value:
                  filter:
                    status:
                      notIn:
                        - COMPLETE
                        - CANCELED
      responses:
        '200':
          description: Loads matching filter criteria
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Load'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /loads:
    post:
      summary: Add an additional load
      description: |
        Add an additional load to an **existing shipment**. This endpoint
        requires a shipment — it cannot create one. Creating a shipment
        already creates its first load structure; use this endpoint only for
        multi-load scenarios (extra legs, split moves).

        ## What happens

        - Load is created for the specified shipment
        - Optionally assigns an initial carrier

        To book a carrier on a load afterwards, use the load-carrier
        endpoints — that is the primary booking flow.
      operationId: createLoad
      tags:
        - Loads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shipmentId
                - load
              properties:
                shipmentId:
                  type: string
                  format: uuid
                  description: Parent shipment ID
                load:
                  $ref: '#/components/schemas/LoadInput'
            examples:
              basicLoad:
                summary: Create FTL load
                value:
                  shipmentId: 550e8400-e29b-41d4-a716-446655440000
                  load:
                    mode: FTL
              withCarrier:
                summary: Create load with carrier
                value:
                  shipmentId: 550e8400-e29b-41d4-a716-446655440000
                  load:
                    mode: FTL
                    carrier:
                      carrier:
                        id: 660e8400-e29b-41d4-a716-446655440001
                      charges:
                        - chargeCode:
                            key: LINEHAUL
                          amount: 2000
      responses:
        '201':
          description: Load created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Load'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /loads/{id}:
    get:
      summary: Get a load
      description: |
        Retrieve a load by ID.

        The response includes embedded carriers and stops.
      operationId: getLoad
      tags:
        - Loads
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Load retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Load'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    patch:
      summary: Update a load
      description: |
        Update load fields.

        **Note:** To manage carriers, use the carrier-specific endpoints.
      operationId: updateLoad
      tags:
        - Loads
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoadPatch'
      responses:
        '200':
          description: Load updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Load'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      summary: Delete a load
      description: |
        Soft delete a load.

        ## Prerequisites

        - Load must not have any active carriers
      operationId: deleteLoad
      tags:
        - Loads
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: Load deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Cannot delete - load has active carriers
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /loads/{id}/add-carrier:
    post:
      summary: Add carrier to load
      description: |
        Add an additional carrier to a load.

        ## Use cases

        - Split loads (multiple carriers for same load)
        - Adding backup carrier
        - Re-assigning after TONU/bounce

        ## What happens

        - New LoadCarrier record is created
        - Carrier is notified (if configured)
      operationId: addCarrierToLoad
      tags:
        - Loads
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoadCarrierInput'
            examples:
              addCarrier:
                summary: Add carrier with costs
                value:
                  carrier:
                    id: 550e8400-e29b-41d4-a716-446655440000
                  contact:
                    id: 660e8400-e29b-41d4-a716-446655440001
                  charges:
                    - chargeCode:
                        key: LINEHAUL
                      amount: 2000
                  driverName: John Smith
                  driverPhone: '+15551234567'
      responses:
        '201':
          description: Carrier added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddCarrierResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /loads/{id}/rebook:
    post:
      summary: Rebook a TONU load
      description: |
        Create a new load to replace a TONU'd load.

        ## Use case

        After a carrier reports TONU, use this to create a replacement load
        that can be assigned to a new carrier.

        ## What happens

        - New Load is created with same stops
        - Original load remains in TONU status
        - New load is ready for carrier assignment
      operationId: rebookLoad
      tags:
        - Loads
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '201':
          description: Load rebooked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RebookLoadResponse'
              example:
                originalLoadId: 550e8400-e29b-41d4-a716-446655440000
                newLoadId: 660e8400-e29b-41d4-a716-446655440001
                newLoadKey: LD-12346
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Load is not in TONU status
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /loads/{loadId}/carriers/{carrierId}:
    get:
      summary: Get load carrier
      description: Retrieve a specific carrier assignment for a load.
      operationId: getLoadCarrier
      tags:
        - Loads
      parameters:
        - name: loadId
          in: path
          required: true
          schema:
            type: string
          description: Load ID
        - name: carrierId
          in: path
          required: true
          schema:
            type: string
          description: LoadCarrier ID
      responses:
        '200':
          description: Load carrier retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadCarrier'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    patch:
      summary: Update load carrier
      description: |
        Update carrier assignment details.

        Use this to update driver info, truck/trailer numbers, or contact.
      operationId: updateLoadCarrier
      tags:
        - Loads
      parameters:
        - name: loadId
          in: path
          required: true
          schema:
            type: string
        - name: carrierId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoadCarrierPatch'
            examples:
              updateDriver:
                summary: Update driver info
                value:
                  driverName: Jane Doe
                  driverPhone: '+15559876543'
                  truckNumber: TRK-123
                  trailerNumber: TRL-456
      responses:
        '200':
          description: Load carrier updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadCarrier'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /loads/{loadId}/carriers/{carrierId}/bounce:
    post:
      summary: Bounce carrier
      description: |
        Mark carrier as bounced (rejected load without payment).

        ## What happens

        - LoadCarrier status changes to BOUNCED
        - Carrier is removed from active execution
        - No payment is recorded

        ## When to use

        Use bounce when carrier rejects the load before dispatch,
        or fails to show up without prior notice.

        For carriers who were dispatched but cancelled, use TONU instead.
      operationId: bounceCarrier
      tags:
        - Loads
      parameters:
        - name: loadId
          in: path
          required: true
          schema:
            type: string
        - name: carrierId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BounceCarrierRequest'
            examples:
              bounceWithReason:
                summary: Bounce with reason
                value:
                  reason: CAN_NO_LONGER_TAKE_LOAD
                  reasonText: Driver did not show up at scheduled time
      responses:
        '200':
          description: Carrier bounced successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadCarrier'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Carrier is not in valid status for bounce
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /loads/{loadId}/carriers/{carrierId}/tonu:
    post:
      summary: Report TONU
      description: |
        Report Truck Ordered Not Used (TONU).

        ## What happens

        - LoadCarrier status changes to TONU
        - TONU costs are recorded if provided
        - Optionally creates a replacement load

        ## When to use

        Use TONU when:
        - Carrier was dispatched but load was cancelled
        - Carrier arrived but freight wasn't ready
        - Carrier was turned away at shipper

        TONU typically involves some payment to the carrier.
      operationId: reportTonu
      tags:
        - Loads
      parameters:
        - name: loadId
          in: path
          required: true
          schema:
            type: string
        - name: carrierId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportTonuRequest'
            examples:
              tonuWithCosts:
                summary: TONU with costs
                value:
                  reason: Freight not ready at shipper
                  costs:
                    - chargeCode:
                        key: TONU
                      amount: 250
                      description: TONU fee
                  createReplacementLoad: true
      responses:
        '200':
          description: TONU reported successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  loadCarrier:
                    $ref: '#/components/schemas/LoadCarrier'
                  replacementLoadId:
                    type: string
                    format: uuid
                    description: New load ID if replacement was requested
                    nullable: true
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Carrier is not in valid status for TONU
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /services/filter:
    post:
      summary: Filter services
      description: |
        Search for services using filter criteria.

        ## Common Filters

        - By shipment: `{ "filter": { "shipmentId": { "equalTo": "uuid" } } }`
        - By vendor: `{ "filter": { "vendorId": { "equalTo": "uuid" } } }`
        - Awaiting invoice: `{ "filter": { "status": { "equalTo": "AWAITING_INVOICE" } } }`
      operationId: filterServices
      tags:
        - Services
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceFilterRequest'
            examples:
              byShipment:
                summary: Filter by shipment
                value:
                  filter:
                    shipmentId:
                      equalTo: 550e8400-e29b-41d4-a716-446655440000
              awaitingInvoice:
                summary: Awaiting invoice
                value:
                  filter:
                    status:
                      equalTo: AWAITING_INVOICE
      responses:
        '200':
          description: Services matching filter criteria
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Service'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /services:
    post:
      summary: Create a service
      description: |
        Create a new service for a shipment.

        ## What happens

        - Service is created for the specified shipment
        - Vendor is associated with the service
        - Charges are recorded

        ## Note

        Services are typically created as part of shipment creation.
        Use this endpoint to add additional services to an existing shipment.
      operationId: createService
      tags:
        - Services
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shipmentId
                - service
              properties:
                shipmentId:
                  type: string
                  format: uuid
                  description: Parent shipment ID
                service:
                  $ref: '#/components/schemas/ServiceInput'
            examples:
              drayageService:
                summary: Create drayage service
                value:
                  shipmentId: 550e8400-e29b-41d4-a716-446655440000
                  service:
                    vendor:
                      id: 660e8400-e29b-41d4-a716-446655440001
                    description: Port drayage from Long Beach
                    charges:
                      - chargeCode:
                          key: DRAY
                        amount: 450
                    scheduledDate: '2025-01-20'
              customsService:
                summary: Create customs service
                value:
                  shipmentId: 550e8400-e29b-41d4-a716-446655440000
                  service:
                    vendor:
                      id: 770e8400-e29b-41d4-a716-446655440002
                    description: Import customs clearance
                    charges:
                      - chargeCode:
                          key: CUSTOMS
                        amount: 175
                    referenceNumber: CB-2025-1234
      responses:
        '201':
          description: Service created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /services/{id}:
    get:
      summary: Get a service
      description: |
        Retrieve a service by ID.

        The response includes vendor info and charges.
      operationId: getService
      tags:
        - Services
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Service retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    patch:
      summary: Update a service
      description: |
        Update service fields.

        **Note:** Status changes happen automatically based on billing workflow.
      operationId: updateService
      tags:
        - Services
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServicePatch'
            examples:
              updateSchedule:
                summary: Update scheduled date
                value:
                  scheduledDate: '2025-01-22'
              markComplete:
                summary: Mark as completed
                value:
                  completedDate: '2025-01-20'
      responses:
        '200':
          description: Service updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      summary: Delete a service
      description: |
        Soft delete a service.

        ## Prerequisites

        - Service must not be paid
      operationId: deleteService
      tags:
        - Services
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: Service deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Cannot delete - service is paid
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /invoices/filter:
    post:
      summary: Filter invoices
      description: |
        Search for AR invoices using filter criteria.

        ## Common Filters

        - By customer: `{ "filter": { "customerId": { "equalTo": "uuid" } } }`
        - Unpaid: `{ "filter": { "status": { "in": ["AWAITING_PAYMENT", "PARTIALLY_PAID"] } } }`
        - Overdue: `{ "filter": { "overdue": true } }`
        - By shipment: `{ "filter": { "shipmentId": { "equalTo": "uuid" } } }`
      operationId: filterInvoices
      tags:
        - Invoices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceFilterRequest'
            examples:
              unpaidInvoices:
                summary: Unpaid invoices
                value:
                  filter:
                    status:
                      in:
                        - AWAITING_PAYMENT
                        - PARTIALLY_PAID
              overdueByCustomer:
                summary: Overdue invoices for customer
                value:
                  filter:
                    customerId:
                      equalTo: 550e8400-e29b-41d4-a716-446655440000
                    overdue: true
      responses:
        '200':
          description: Invoices matching filter criteria
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invoice'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /invoices:
    post:
      summary: Create an invoice
      description: |
        Create a new invoice for an order.

        ## What happens

        - Invoice record is created for the order
        - Order status updates to `DELIVERED_UNPAID`
        - Due date calculated from payment term if not provided

        ## Note

        Each shipment can have only one AR invoice. Use `POST /shipments/{id}/invoice/generate`
        to generate the invoice PDF document.
      operationId: createInvoice
      tags:
        - Invoices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceInput'
            examples:
              basic:
                summary: Create invoice
                value:
                  orderId: 550e8400-e29b-41d4-a716-446655440000
                  invoiceDate: '2025-01-15'
                  dueDate: '2025-02-14'
                  amount: 2500
                  currency: USD
              withTerm:
                summary: With payment term
                value:
                  orderId: 550e8400-e29b-41d4-a716-446655440000
                  invoiceDate: '2025-01-15'
                  amount: 2500
                  paymentTermId: 660e8400-e29b-41d4-a716-446655440001
      responses:
        '201':
          description: Invoice created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: Order already has an invoice
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/ValidationError'
  /invoices/{id}:
    get:
      summary: Get an invoice
      description: |
        Retrieve an invoice by ID.

        The response includes payments, credits, and document info.
      operationId: getInvoice
      tags:
        - Invoices
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Invoice retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    patch:
      summary: Update an invoice
      description: |
        Update invoice fields.

        **Note:** Amount cannot be changed directly. Update order charges instead.
      operationId: updateInvoice
      tags:
        - Invoices
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoicePatch'
            examples:
              updateDueDate:
                summary: Update due date
                value:
                  dueDate: '2025-02-28'
              updateReference:
                summary: Update reference
                value:
                  reference: INV-CUST-123-REV
      responses:
        '200':
          description: Invoice updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      summary: Void an invoice
      description: |
        Void/cancel an invoice.

        ## Prerequisites

        - Invoice must not have any payments applied
        - Invoice must not be factored
      operationId: voidInvoice
      tags:
        - Invoices
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: Invoice voided successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Cannot void - invoice has payments or is factored
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /invoices/{id}/mark-awaiting:
    post:
      summary: Mark invoice as awaiting payment
      description: |
        Mark invoice as awaiting payment.

        ## What happens

        - Sets invoice date and due date
        - Updates order status to `DELIVERED_UNPAID`
        - Invoice is now ready for payment collection
      operationId: markInvoiceAwaiting
      tags:
        - Invoices
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkAwaitingPaymentRequest'
            examples:
              withDates:
                summary: With dates
                value:
                  invoiceDate: '2025-01-15'
                  dueDate: '2025-02-14'
      responses:
        '200':
          description: Invoice marked as awaiting payment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /invoices/{id}/send:
    post:
      summary: Email invoice
      description: |
        Send invoice to customer via email.

        ## What happens

        - Generates invoice PDF if not already generated
        - Sends email with PDF attachment
        - Logs email in activity feed
      operationId: sendInvoiceEmail
      tags:
        - Invoices
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendInvoiceEmailRequest'
            examples:
              basic:
                summary: Basic email
                value:
                  toEmails:
                    - billing@customer.com
              withMessage:
                summary: With custom message
                value:
                  toEmails:
                    - billing@customer.com
                  ccEmails:
                    - accounts@broker.com
                  subject: Invoice INV-00001 for Shipment SHP-00123
                  message: Please find attached your invoice for recent shipment services.
      responses:
        '200':
          description: Email sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  emailId:
                    type: string
                    format: uuid
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /invoices/{id}/payments:
    get:
      summary: Get invoice payments
      description: List all payments applied to a specific invoice.
      operationId: getInvoicePayments
      tags:
        - Invoices
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Payments retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/InvoicePayment'
                  totalPaid:
                    type: number
                  openBalance:
                    type: number
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /invoices/batch-generate:
    post:
      summary: Batch generate invoices
      description: |
        Generate invoices for multiple shipments in a single request.

        ## What happens

        - Creates invoice records for each shipment
        - Generates PDF documents
        - Optionally sends emails grouped by customer

        ## Note

        Shipments that already have invoices or are missing requirements
        will be skipped and returned in the `failed` array.
      operationId: batchGenerateInvoices
      tags:
        - Invoices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchGenerateInvoicesRequest'
            examples:
              basic:
                summary: Generate only
                value:
                  orderIds:
                    - 550e8400-e29b-41d4-a716-446655440000
                    - 550e8400-e29b-41d4-a716-446655440001
              withEmail:
                summary: Generate and email
                value:
                  orderIds:
                    - 550e8400-e29b-41d4-a716-446655440000
                    - 550e8400-e29b-41d4-a716-446655440001
                  sendEmail: true
                  emailConfig:
                    groupByCustomer: true
      responses:
        '200':
          description: Batch generation completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchGenerateInvoicesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /invoices/aging-report:
    get:
      summary: Get aging report
      description: |
        Generate accounts receivable aging report.

        ## Report buckets

        By default: Current, 1-30, 31-60, 61-90, 90+ days

        ## Export formats

        - JSON (default)
        - CSV (set Accept header to text/csv)
      operationId: getAgingReport
      tags:
        - Invoices
      parameters:
        - name: customerId
          in: query
          schema:
            type: string
            format: uuid
          description: Filter by specific customer
        - name: daysPerBucket
          in: query
          schema:
            type: integer
            default: 30
          description: Days per aging bucket
        - name: maxDays
          in: query
          schema:
            type: integer
            default: 120
          description: Maximum days to track
      responses:
        '200':
          description: Aging report generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgingReportResponse'
            text/csv:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /payments/filter:
    post:
      summary: Filter payments
      description: |
        Search for AR payments using filter criteria.

        ## Common Filters

        - By customer: `{ "filter": { "customerId": { "equalTo": "uuid" } } }`
        - By invoice: `{ "filter": { "invoiceId": { "equalTo": "uuid" } } }`
        - By date range: `{ "filter": { "paymentDate": { "greaterThanOrEqualTo": "2025-01-01" } } }`
        - By method: `{ "filter": { "paymentMethodType": { "equalTo": "check" } } }`
      operationId: filterPayments
      tags:
        - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentFilterRequest'
            examples:
              byCustomer:
                summary: Filter by customer
                value:
                  filter:
                    customerId:
                      equalTo: 550e8400-e29b-41d4-a716-446655440000
              byDateRange:
                summary: Filter by date range
                value:
                  filter:
                    paymentDate:
                      greaterThanOrEqualTo: '2025-01-01T00:00:00Z'
                      lessThanOrEqualTo: '2025-01-31T23:59:59Z'
      responses:
        '200':
          description: Payments matching filter criteria
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /payments:
    post:
      summary: Create a payment
      description: |
        Record a customer payment applied to invoices.

        ## What happens

        - Payment record is created
        - Specified amounts are applied to invoices
        - Invoice/order status updated to `PAID` when fully paid
        - Overpayment creates a credit memo automatically

        ## Validations

        - Payment date must be >= invoice date for all applied invoices
        - Application amounts must not exceed invoice open balances
        - Customer must match invoice customer
      operationId: createPayment
      tags:
        - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentInput'
            examples:
              singleInvoice:
                summary: Single invoice payment
                value:
                  customerId: 550e8400-e29b-41d4-a716-446655440000
                  paymentDate: '2025-01-15'
                  paymentMethodType: CHECK
                  reference: CHK-12345
                  applications:
                    - invoiceId: 660e8400-e29b-41d4-a716-446655440001
                      amount: 2500
              multipleInvoices:
                summary: Multiple invoices
                value:
                  customerId: 550e8400-e29b-41d4-a716-446655440000
                  paymentDate: '2025-01-15'
                  paymentMethodType: ACH_WIRE
                  reference: ACH-98765
                  notes: January payment batch
                  applications:
                    - invoiceId: 660e8400-e29b-41d4-a716-446655440001
                      amount: 1500
                    - invoiceId: 660e8400-e29b-41d4-a716-446655440002
                      amount: 2500
              withCredits:
                summary: With credits applied
                value:
                  customerId: 550e8400-e29b-41d4-a716-446655440000
                  paymentDate: '2025-01-15'
                  paymentMethodType: CHECK
                  reference: CHK-12345
                  applications:
                    - invoiceId: 660e8400-e29b-41d4-a716-446655440001
                      amount: 2000
                  creditApplications:
                    - creditMemoId: 770e8400-e29b-41d4-a716-446655440003
                      amount: 500
      responses:
        '201':
          description: Payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /payments/{id}:
    get:
      summary: Get a payment
      description: |
        Retrieve a payment by ID.

        The response includes all invoice applications and credit applications.
      operationId: getPayment
      tags:
        - Payments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Payment retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    patch:
      summary: Update a payment
      description: |
        Update payment details or reassign invoice applications.

        ## What happens

        - Payment fields are updated
        - Invoice applications are replaced if provided
        - Order statuses are recalculated

        ## Note

        Updating applications replaces all existing applications.
        Include all desired applications in the request.
      operationId: updatePayment
      tags:
        - Payments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentPatch'
            examples:
              updateReference:
                summary: Update reference
                value:
                  reference: CHK-12345-REV
                  notes: Corrected check number
              updateMethod:
                summary: Update method
                value:
                  paymentMethodType: ACH_WIRE
              reassignApplications:
                summary: Reassign to different invoices
                value:
                  applications:
                    - invoiceId: 660e8400-e29b-41d4-a716-446655440001
                      amount: 1500
      responses:
        '200':
          description: Payment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      summary: Delete a payment
      description: |
        Delete a payment and remove all invoice applications.

        ## What happens

        - Payment record is deleted
        - Invoice applications are removed
        - Order statuses revert if needed (PAID → UNPAID)

        ## Note

        This action cannot be undone. Consider voiding instead
        if you need to maintain a record.
      operationId: deletePayment
      tags:
        - Payments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: Payment deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Cannot delete - payment is synced to QBO
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /payments/{id}/applications:
    get:
      summary: Get payment applications
      description: List all invoice applications for a payment.
      operationId: getPaymentApplications
      tags:
        - Payments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Applications retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentApplication'
                  totalApplied:
                    type: number
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /customers/{id}/payments:
    get:
      summary: Get customer payments
      description: List all payments from a specific customer.
      operationId: getCustomerPayments
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
        - name: pageSize
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Payments retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /customers/{id}/outstanding-invoices:
    get:
      summary: Get outstanding invoices
      description: |
        List invoices available for payment from a customer.

        Returns invoices with status `AWAITING_PAYMENT` or `PARTIALLY_PAID`.
      operationId: getCustomerOutstandingInvoices
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Outstanding invoices retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutstandingInvoicesResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /credit-memos/filter:
    post:
      summary: Filter credit memos
      description: |
        Search for credit memos using filter criteria.

        ## Common Filters

        - By customer: `{ "filter": { "customerId": { "equalTo": "uuid" } } }`
        - With balance: `{ "filter": { "hasRemainingBalance": true } }`
        - Open credits: `{ "filter": { "status": { "in": ["OPEN", "PARTIALLY_APPLIED"] } } }`
      operationId: filterCreditMemos
      tags:
        - Credit Memos
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditMemoFilterRequest'
            examples:
              byCustomer:
                summary: Filter by customer
                value:
                  filter:
                    customerId:
                      equalTo: 550e8400-e29b-41d4-a716-446655440000
              availableCredits:
                summary: Credits with balance
                value:
                  filter:
                    hasRemainingBalance: true
                    status:
                      notEqualTo: VOIDED
      responses:
        '200':
          description: Credit memos matching filter criteria
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CreditMemo'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /credit-memos:
    post:
      summary: Create a credit memo
      description: |
        Create a new credit memo for a customer.

        ## Use cases

        - Customer refunds
        - Service adjustments
        - Promotional credits
        - Manual corrections

        ## Note

        Credit memos from overpayments are created automatically
        when a payment exceeds invoice totals.
      operationId: createCreditMemo
      tags:
        - Credit Memos
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditMemoInput'
            examples:
              refund:
                summary: Customer refund
                value:
                  customerId: 550e8400-e29b-41d4-a716-446655440000
                  amount: 500
                  currency: USD
                  memoDate: '2025-01-15'
                  reference: CM-00001
                  notes: Refund for damaged goods
              adjustment:
                summary: Service adjustment
                value:
                  customerId: 550e8400-e29b-41d4-a716-446655440000
                  amount: 150
                  memoDate: '2025-01-15'
                  notes: Price adjustment per agreement
      responses:
        '201':
          description: Credit memo created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditMemo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /credit-memos/{id}:
    get:
      summary: Get a credit memo
      description: |
        Retrieve a credit memo by ID.

        The response includes all applications showing how the credit has been used.
      operationId: getCreditMemo
      tags:
        - Credit Memos
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Credit memo retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditMemo'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    patch:
      summary: Update a credit memo
      description: |
        Update credit memo fields.

        ## Constraints

        - Amount cannot be changed if any applications exist
        - Customer cannot be changed once created
      operationId: updateCreditMemo
      tags:
        - Credit Memos
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditMemoPatch'
            examples:
              updateReference:
                summary: Update reference
                value:
                  reference: CM-00001-REV
              updateNotes:
                summary: Update notes
                value:
                  notes: 'Updated: Refund for damaged goods and shipping issues'
      responses:
        '200':
          description: Credit memo updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditMemo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /credit-memos/{id}/void:
    post:
      summary: Void a credit memo
      description: |
        Void/cancel a credit memo.

        ## Prerequisites

        - Credit memo must have no applications (full balance remaining)
        - Must unapply all applications before voiding

        ## What happens

        - Credit memo status changes to VOIDED
        - Credit is no longer available for application
        - QBO sync will delete the credit memo
      operationId: voidCreditMemo
      tags:
        - Credit Memos
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoidCreditMemoRequest'
            examples:
              withReason:
                summary: Void with reason
                value:
                  reason: Credit issued in error
      responses:
        '200':
          description: Credit memo voided successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditMemo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Cannot void - credit memo has applications
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /credit-memos/{id}/apply:
    post:
      summary: Apply credit to invoice
      description: |
        Apply credit memo amount to an invoice.

        ## What happens

        - Creates credit application record
        - Reduces credit memo remaining balance
        - Reduces invoice open balance
        - Updates order status if invoice is fully paid

        ## Constraints

        - Amount must not exceed remaining balance
        - Invoice must belong to same customer
        - Invoice must have outstanding balance
        - Currency must match
      operationId: applyCreditMemo
      tags:
        - Credit Memos
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyCreditRequest'
            examples:
              applyCredit:
                summary: Apply credit
                value:
                  invoiceId: 660e8400-e29b-41d4-a716-446655440001
                  amount: 200
      responses:
        '200':
          description: Credit applied successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplyCreditResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Cannot apply - insufficient balance or invalid invoice
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/ValidationError'
  /credit-memos/{id}/applications:
    get:
      summary: Get credit applications
      description: List all invoice applications for a credit memo.
      operationId: getCreditMemoApplications
      tags:
        - Credit Memos
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Applications retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CreditMemoApplication'
                  totalApplied:
                    type: number
                  remainingBalance:
                    type: number
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /credit-memos/{creditMemoId}/applications/{applicationId}:
    delete:
      summary: Unapply credit from invoice
      description: |
        Remove a credit application from an invoice.

        ## What happens

        - Application record is deleted
        - Credit memo remaining balance increases
        - Invoice open balance increases
        - Order status may revert if invoice becomes unpaid
      operationId: unapplyCreditMemo
      tags:
        - Credit Memos
      parameters:
        - name: creditMemoId
          in: path
          required: true
          schema:
            type: string
          description: Credit memo ID
        - name: applicationId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Application ID
      responses:
        '200':
          description: Credit unapplied successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditMemo'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /invoices/{id}/available-credits:
    get:
      summary: Get available credits for invoice
      description: |
        List credit memos that can be applied to an invoice.

        Returns credits for the same customer with remaining balance
        and matching currency.
      operationId: getAvailableCreditsForInvoice
      tags:
        - Invoices
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Available credits retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableCreditsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /bills/filter:
    post:
      summary: Filter bills
      description: |
        Search for AP bills using filter criteria.

        ## Common Filters

        - By carrier: `{ "filter": { "carrierId": { "equalTo": "uuid" } } }`
        - By vendor: `{ "filter": { "vendorId": { "equalTo": "uuid" } } }`
        - Awaiting approval: `{ "filter": { "status": { "equalTo": "IN_REVIEW" } } }`
        - By shipment: `{ "filter": { "shipmentId": { "equalTo": "uuid" } } }`
        - Overdue: `{ "filter": { "overdue": true } }`
      operationId: filterBills
      tags:
        - Bills
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillFilterRequest'
            examples:
              awaitingApproval:
                summary: Bills awaiting approval
                value:
                  filter:
                    status:
                      equalTo: IN_REVIEW
              byCarrier:
                summary: Bills by carrier
                value:
                  filter:
                    carrierId:
                      equalTo: 550e8400-e29b-41d4-a716-446655440000
                    entityType:
                      equalTo: CARRIER
              approvedToPay:
                summary: Bills approved to pay
                value:
                  filter:
                    status:
                      equalTo: APPROVED_TO_PAY
      responses:
        '200':
          description: Bills matching filter criteria
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Bill'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /bills:
    post:
      summary: Record a bill
      description: |
        Record a carrier or vendor bill (invoice).

        ## What happens

        - Bill record is created for the load carrier or vended service
        - Entity status updates to `IN_REVIEW`
        - Due date calculated from payment term if not provided

        ## Prerequisites

        - LoadCarrier or VendedService must exist
        - Entity must be in `AWAITING_INVOICE` status
      operationId: createBill
      tags:
        - Bills
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillInput'
            examples:
              carrierBill:
                summary: Record carrier bill
                value:
                  entityType: CARRIER
                  entityId: 550e8400-e29b-41d4-a716-446655440000
                  invoiceDate: '2025-01-15'
                  dueDate: '2025-02-14'
                  amount: 2500
                  reference: INV-CARRIER-123
                  currency: USD
              vendorBill:
                summary: Record vendor bill
                value:
                  entityType: VENDOR
                  entityId: 660e8400-e29b-41d4-a716-446655440001
                  invoiceDate: '2025-01-15'
                  amount: 500
                  reference: VS-2025-001
      responses:
        '201':
          description: Bill created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bill'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: Entity already has a bill or is not in correct status
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/ValidationError'
  /bills/{id}:
    get:
      summary: Get a bill
      description: |
        Retrieve a bill by ID.

        The response includes payments applied and carrier/vendor details.
      operationId: getBill
      tags:
        - Bills
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Bill retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bill'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    patch:
      summary: Update a bill
      description: |
        Update bill fields.

        ## Constraints

        - Cannot change amount if payments have been applied
        - Status changes use action endpoints
      operationId: updateBill
      tags:
        - Bills
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillPatch'
            examples:
              updateDueDate:
                summary: Update due date
                value:
                  dueDate: '2025-02-28'
              updateReference:
                summary: Update reference
                value:
                  reference: INV-CARRIER-123-REV
      responses:
        '200':
          description: Bill updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bill'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Cannot update - bill has payments
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      summary: Delete a bill
      description: |
        Delete a bill.

        ## Prerequisites

        - Bill must not have any payments applied

        ## What happens

        - Bill record is deleted
        - Entity status reverts to `AWAITING_INVOICE`
      operationId: deleteBill
      tags:
        - Bills
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: Bill deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Cannot delete - bill has payments
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /bills/{id}/approve:
    post:
      summary: Approve bill for payment
      description: |
        Approve a bill for payment.

        ## What happens

        - Bill status changes to `APPROVED_TO_PAY`
        - Bill is now ready for payment

        ## Prerequisites

        - Bill must be in `IN_REVIEW` status
      operationId: approveBill
      tags:
        - Bills
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Bill approved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bill'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Bill is not in valid status for approval
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /bills/batch-approve:
    post:
      summary: Batch approve bills
      description: |
        Approve multiple bills for payment in a single request.

        Bills that cannot be approved will be returned in the `failed` array.
      operationId: batchApproveBills
      tags:
        - Bills
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveBillsRequest'
            examples:
              approveBills:
                summary: Approve multiple bills
                value:
                  billIds:
                    - 550e8400-e29b-41d4-a716-446655440000
                    - 550e8400-e29b-41d4-a716-446655440001
      responses:
        '200':
          description: Batch approval completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApproveBillsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /bills/{id}/unapprove:
    post:
      summary: Unapprove bill
      description: |
        Revert bill from approved back to in review.

        ## What happens

        - Bill status changes to `IN_REVIEW`

        ## Prerequisites

        - Bill must be in `APPROVED_TO_PAY` status
        - Bill must not have any payments
      operationId: unapproveBill
      tags:
        - Bills
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Bill unapproved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bill'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Bill is not in valid status or has payments
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /bills/{id}/revert:
    post:
      summary: Revert bill to awaiting invoice
      description: |
        Revert bill completely back to awaiting invoice state.

        ## What happens

        - Bill record is deleted
        - Any payments are deleted
        - Entity status reverts to `AWAITING_INVOICE`

        ## Use case

        Use when a bill was recorded incorrectly and needs to start over.
      operationId: revertBill
      tags:
        - Bills
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevertBillRequest'
            examples:
              withReason:
                summary: Revert with reason
                value:
                  reason: Invoice amount was incorrect
      responses:
        '200':
          description: Bill reverted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  entityStatus:
                    type: string
                    description: New status of the load carrier or vended service
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /bills/{id}/payments:
    get:
      summary: Get bill payments
      description: List all payments applied to a specific bill.
      operationId: getBillPayments
      tags:
        - Bills
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Payments retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BillPaymentApplied'
                  totalPaid:
                    type: number
                  openBalance:
                    type: number
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /carriers/{id}/outstanding-bills:
    get:
      summary: Get carrier outstanding bills
      description: |
        List outstanding (unpaid) bills for a carrier.

        Returns bills with status `APPROVED_TO_PAY`.
      operationId: getCarrierOutstandingBills
      tags:
        - Carriers
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Outstanding bills retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutstandingBillsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /vendors/{id}/outstanding-bills:
    get:
      summary: Get vendor outstanding bills
      description: |
        List outstanding (unpaid) bills for a vendor.

        Returns bills with status `APPROVED_TO_PAY`.
      operationId: getVendorOutstandingBills
      tags:
        - Vendors
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Outstanding bills retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutstandingBillsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /bills/aging-report:
    get:
      summary: Get AP aging report
      description: |
        Generate accounts payable aging report.

        ## Report buckets

        By default: Current, 1-30, 31-60, 61-90, 90+ days

        ## Export formats

        - JSON (default)
        - CSV (set Accept header to text/csv)
      operationId: getApAgingReport
      tags:
        - Bills
      parameters:
        - name: carrierId
          in: query
          schema:
            type: string
            format: uuid
          description: Filter by specific carrier
        - name: vendorId
          in: query
          schema:
            type: string
            format: uuid
          description: Filter by specific vendor
        - name: entityType
          in: query
          schema:
            $ref: '#/components/schemas/BillEntityType'
          description: Filter by entity type
        - name: daysPerBucket
          in: query
          schema:
            type: integer
            default: 30
          description: Days per aging bucket
        - name: maxDays
          in: query
          schema:
            type: integer
            default: 120
          description: Maximum days to track
      responses:
        '200':
          description: AP aging report generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApAgingReportResponse'
            text/csv:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /bill-payments/filter:
    post:
      summary: Filter bill payments
      description: |
        Search for bill payments using filter criteria.

        ## Common Filters

        - By carrier: `{ "filter": { "carrierId": { "equalTo": "uuid" } } }`
        - By vendor: `{ "filter": { "vendorId": { "equalTo": "uuid" } } }`
        - By factor: `{ "filter": { "carrierFactorId": { "equalTo": "uuid" } } }`
        - By date range: `{ "filter": { "paymentDate": { "gte": "2025-01-01", "lte": "2025-01-31" } } }`
        - By method: `{ "filter": { "paymentMethodType": { "equalTo": "check" } } }`
      operationId: filterBillPayments
      tags:
        - Bill Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillPaymentFilterRequest'
            examples:
              byCarrier:
                summary: Payments by carrier
                value:
                  filter:
                    carrierId:
                      equalTo: 550e8400-e29b-41d4-a716-446655440000
              byDateRange:
                summary: Payments in date range
                value:
                  filter:
                    paymentDate:
                      greaterThanOrEqualTo: '2025-01-01T00:00:00Z'
                      lessThanOrEqualTo: '2025-01-31T23:59:59Z'
              byMethod:
                summary: Check payments
                value:
                  filter:
                    paymentMethodType:
                      equalTo: CHECK
      responses:
        '200':
          description: Bill payments matching filter criteria
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BillPayment'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /bill-payments:
    post:
      summary: Create a bill payment
      description: |
        Record a payment for one or more carrier/vendor bills.

        ## What happens

        - PaymentGroup record is created
        - Payment applications are created for each bill
        - Bill open balances are reduced
        - Load/service status updates to PAID when fully paid

        ## Carrier factor payments

        To pay a carrier's factor instead of the carrier directly,
        specify `carrierFactorId` in the request.

        ## Overpayments

        If `allowOverpayment` is true and payment exceeds bill totals,
        a credit memo is automatically created for the difference.
      operationId: createBillPayment
      tags:
        - Bill Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillPaymentInput'
            examples:
              singleBill:
                summary: Pay single bill
                value:
                  paymentDate: '2025-01-15'
                  paymentMethodType: CHECK
                  reference: CHK-12345
                  applications:
                    - billId: 550e8400-e29b-41d4-a716-446655440000
                      amount: 2500
              multipleBills:
                summary: Pay multiple bills
                value:
                  paymentDate: '2025-01-15'
                  paymentMethodType: ACH_WIRE
                  reference: ACH-2025-001
                  notes: January carrier payments
                  applications:
                    - billId: 550e8400-e29b-41d4-a716-446655440000
                      amount: 2500
                    - billId: 550e8400-e29b-41d4-a716-446655440001
                      amount: 3500
              factorPayment:
                summary: Pay carrier factor
                value:
                  paymentDate: '2025-01-15'
                  paymentMethodType: ACH_WIRE
                  carrierFactorId: 770e8400-e29b-41d4-a716-446655440002
                  reference: ACH-FACTOR-001
                  applications:
                    - billId: 550e8400-e29b-41d4-a716-446655440000
                      amount: 2500
      responses:
        '201':
          description: Bill payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillPayment'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: Conflict - bill already paid or invalid state
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/ValidationError'
  /bill-payments/{id}:
    get:
      summary: Get a bill payment
      description: |
        Retrieve a bill payment by ID.

        The response includes all payment applications and their associated bills.
      operationId: getBillPayment
      tags:
        - Bill Payments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Bill payment retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillPayment'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    patch:
      summary: Update a bill payment
      description: |
        Update bill payment fields.

        ## Constraints

        - Cannot change carrier factor after creation
        - Can add/remove/update payment applications

        ## Updating applications

        In the `applications` array:
        - Include `id` to update an existing application
        - Omit `id` and include `billId` to add a new application
        - Set `delete: true` with `id` to remove an application
      operationId: updateBillPayment
      tags:
        - Bill Payments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillPaymentPatch'
            examples:
              updateReference:
                summary: Update reference
                value:
                  reference: CHK-12345-UPDATED
              updateAmounts:
                summary: Update payment amounts
                value:
                  applications:
                    - id: 660e8400-e29b-41d4-a716-446655440001
                      amount: 2600
              addApplication:
                summary: Add new bill to payment
                value:
                  applications:
                    - billId: 770e8400-e29b-41d4-a716-446655440002
                      amount: 1000
              removeApplication:
                summary: Remove bill from payment
                value:
                  applications:
                    - id: 660e8400-e29b-41d4-a716-446655440001
                      delete: true
      responses:
        '200':
          description: Bill payment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillPayment'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Conflict - invalid state for update
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      summary: Delete a bill payment
      description: |
        Delete a bill payment and all its applications.

        ## What happens

        - PaymentGroup record is deleted
        - All Payment applications are deleted
        - Bill open balances are restored
        - Load/service status may revert if payment made them PAID
      operationId: deleteBillPayment
      tags:
        - Bill Payments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: Bill payment deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /bill-payments/{id}/applications:
    get:
      summary: Get bill payment applications
      description: List all bills paid by this payment group.
      operationId: getBillPaymentApplications
      tags:
        - Bill Payments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Applications retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BillPaymentApplication'
                  totalAmount:
                    type: number
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /carriers/{id}/bills-for-payment:
    get:
      summary: Get carrier bills available for payment
      description: |
        List bills available for payment from a carrier.

        Returns bills with status `APPROVED_TO_PAY` and open balance.

        ## Carrier factor

        If the carrier has a factor configured, factor details are included.
      operationId: getCarrierBillsForPayment
      tags:
        - Carriers
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Bills for payment retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutstandingBillsForPaymentResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /vendors/{id}/bills-for-payment:
    get:
      summary: Get vendor bills available for payment
      description: |
        List bills available for payment from a vendor.

        Returns bills with status `APPROVED_TO_PAY` and open balance.
      operationId: getVendorBillsForPayment
      tags:
        - Vendors
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Bills for payment retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutstandingBillsForPaymentResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /carrier-factors/{id}/bills-for-payment:
    get:
      summary: Get bills payable to a carrier factor
      description: |
        List bills that should be paid to this carrier factor.

        Returns bills from carriers that use this factor with status `APPROVED_TO_PAY`.
      operationId: getCarrierFactorBillsForPayment
      tags:
        - Carrier Factors
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Bills for payment retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutstandingBillsForPaymentResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /bill-payments/{id}/remittance-advice:
    get:
      summary: Generate remittance advice
      description: |
        Generate a remittance advice document for a bill payment.

        ## Formats

        - PDF (default): Set Accept header to application/pdf
        - JSON: Set Accept header to application/json
      operationId: getBillPaymentRemittanceAdvice
      tags:
        - Bill Payments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Remittance advice generated
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                type: object
                properties:
                  paymentDate:
                    type: string
                    format: date
                  paymentMethod:
                    type: string
                  reference:
                    type: string
                  payee:
                    type: object
                    properties:
                      name:
                        type: string
                      address:
                        type: string
                  applications:
                    type: array
                    items:
                      type: object
                      properties:
                        billFriendlyId:
                          type: string
                        shipmentFriendlyId:
                          type: string
                        invoiceDate:
                          type: string
                          format: date
                        amount:
                          type: number
                  totalAmount:
                    type: number
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /bill-payments/{id}/send-remittance:
    post:
      summary: Send remittance advice email
      description: |
        Email the remittance advice to the carrier or vendor.

        Uses the recipient's default email from their profile.
      operationId: sendBillPaymentRemittance
      tags:
        - Bill Payments
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                toEmail:
                  type: string
                  format: email
                  description: Override recipient email
                ccEmails:
                  type: array
                  items:
                    type: string
                    format: email
                  description: CC recipients
                message:
                  type: string
                  maxLength: 2000
                  description: Additional message in email body
            examples:
              defaultEmail:
                summary: Send to default contact
                value: {}
              customRecipient:
                summary: Send to specific email
                value:
                  toEmail: accounts@carrier.com
                  message: Please find attached remittance advice for recent payments.
      responses:
        '200':
          description: Remittance advice sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  sentTo:
                    type: string
                    format: email
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: No email address available
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /global-search:
    post:
      summary: Search globally
      description: |
        Search across multiple entity types simultaneously (shipments, customers, carriers, users, vendors).

        **Use Cases:**
        - Unified search bar for finding any type of record
        - Quick lookup by name, ID, or reference number
        - Cross-entity discovery

        **Search Behavior:**
        - Searches across default searchable fields for each entity type
        - Results are sorted by object type priority: SHIPMENT → CUSTOMER → CARRIER → USER → VENDOR
        - Within each object type, results are sorted by most recently updated

        **Prefix Filtering:**
        Use "type:query" syntax to search specific object types:
        - `carrier:acme` - searches only carriers
        - `shipment:12345` - searches only shipments
        - `customer:west` - searches only customers

        **IMPORTANT: Eventually Consistent**
        This endpoint queries OpenSearch indices which are updated asynchronously.
        Changes typically appear within 2 seconds, but this is not guaranteed.
      operationId: globalSearch
      tags:
        - Search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GlobalSearchRequest'
            examples:
              simpleSearch:
                summary: Simple search
                value:
                  query: acme
              filteredSearch:
                summary: Filter by object types
                value:
                  query: acme
                  objects:
                    - SHIPMENT
                    - CUSTOMER
                  pagination:
                    pageNumber: 1
                    pageSize: 20
              prefixSearch:
                summary: Prefix-filtered search
                value:
                  query: carrier:trucking
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalSearchResponse'
              example:
                data:
                  - object: SHIPMENT
                    id: 550e8400-e29b-41d4-a716-446655440001
                    key: ERP-SHIP-001
                    entityName: SHIPMENT
                    title: SHIP-12345
                    subtitle: Acme Corporation
                    field: Customer
                    highlight: <em>Acme</em> Corporation
                  - object: CUSTOMER
                    id: 550e8400-e29b-41d4-a716-446655440002
                    key: ERP-CUST-001
                    entityName: SHIPPER_PROFILE
                    title: Acme Corporation
                    subtitle: CUST-001
                    field: Name
                    highlight: <em>Acme</em> Corporation
                pagination:
                  pageNumber: 1
                  pageSize: 20
                  totalPages: 3
                totalResults: 42
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  parameters:
    IdOrClientKey:
      name: id
      in: path
      required: true
      description: Resource ID (UUID) or client key
      schema:
        type: string
      example: 550e8400-e29b-41d4-a716-446655440000
    LookupBy:
      name: by
      in: query
      description: |
        Specify lookup type for faster retrieval.
        If omitted, defaults to looking up by ID first, then falls back to client key if not found.
        Use `by=key` when you know you're providing a client key for best performance.
      schema:
        type: string
        enum:
          - id
          - key
      example: key
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 3
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: Specify lookup type for faster retrieval.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: If omitted, defaults to looking up by ID first, then falls back to client key if not found.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: 'Use '
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: by=key
                    children: []
                    type: code
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: ' when you know you''re providing a client key for best performance.'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
  responses:
    BadRequestError:
      description: Bad request - invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: bad_request
            message: Invalid request parameters
    UnauthorizedError:
      description: Unauthorized - invalid or missing access token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
            message: Invalid or expired access token
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: not_found
            message: Resource not found
    ConflictError:
      description: Conflict - resource already exists or constraint violation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: conflict
            message: A resource with this identifier already exists
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal_server_error
            message: An unexpected error occurred
    ValidationError:
      description: Validation error - invalid field values
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
          example:
            error: validation_error
            message: Invalid field values
            details:
              - field: email
                message: Must be a valid email address
              - field: status
                message: Must be one of PENDING, ACTIVE, INACTIVE
    RateLimitExceeded:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: rate_limit_exceeded
            message: Too many requests. Please retry after 60 seconds.
      headers:
        X-RateLimit-Limit:
          description: Request limit per minute
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Remaining requests in current window
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix timestamp when rate limit resets
          schema:
            type: integer
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
  schemas:
    PaginationInfo:
      type: object
      required:
        - pageSize
        - hasNextPage
      properties:
        pageSize:
          type: integer
          description: Number of items per page
          example: 50
        hasNextPage:
          type: boolean
          description: Whether there are more pages
          example: true
        hasPreviousPage:
          type: boolean
          description: Whether there are previous pages
          example: false
        endCursor:
          type: string
          description: Cursor for the next page (null if no next page)
          example: eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9
          nullable: true
    ResourceReference:
      type: object
      description: Reference to another resource (returned in responses)
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: Resource UUID
        key:
          type: string
          description: Client-defined reference ID if set
          nullable: true
      example:
        id: 550e8400-e29b-41d4-a716-446655440000
        key: ERP-USER-12345
    ResourceReferenceInput:
      type: object
      description: Reference to another resource by either ID or client key (used in create/update requests)
      properties:
        id:
          type: string
          format: uuid
          description: Resource UUID
        key:
          type: string
          description: Client-defined reference ID
      oneOf:
        - required:
            - id
        - required:
            - key
      example:
        id: 550e8400-e29b-41d4-a716-446655440000
    PaymentTermReference:
      type: object
      description: |
        Enhanced reference to a payment term resource (returned in responses).
        Includes full payment term details in addition to id/key.
      required:
        - id
        - name
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Payment term UUID
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          maxLength: 512
          description: Client-defined reference ID if set
          example: ERP-PAYTERM-NET30
          nullable: true
        name:
          type: string
          description: Payment term name
          example: Net 30
        description:
          type: string
          description: Payment term description or notes
          example: Payment due 30 days from invoice date
          nullable: true
        days:
          type: integer
          description: Number of days until payment is due
          example: 30
          nullable: true
        quickPayFee:
          type: number
          format: float
          description: Quick pay fee percentage (e.g., 0.05 for 5%)
          example: 0.05
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 1
                        inline: true
                        attributes:
                          content: Quick pay fee percentage (e.g., 0.05 for 5%)
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
          nullable: true
        apOnly:
          type: boolean
          description: Whether this payment term is for accounts payable only
          example: false
          nullable: true
        doNotUse:
          type: boolean
          description: Flag to prevent using this payment term for new transactions
          example: false
          nullable: true
        createdAt:
          type: string
          format: date-time
          description: When the payment term was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the payment term was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          description: When the payment term was soft deleted (null if active)
          example: null
          nullable: true
    UserReference:
      type: object
      description: |
        Enhanced reference to a user resource (returned in responses).
        Includes full user details in addition to id/key.

        Note: Does NOT include nested references (teams, etc.) to prevent recursion.
        Maximum nesting depth: 1 level.
      required:
        - id
        - email
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: User UUID
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          maxLength: 512
          description: Client-defined reference ID if set
          example: ERP-USER-12345
          nullable: true
        email:
          type: string
          format: email
          description: User's email address
          example: john.doe@example.com
        name:
          type: string
          description: User's full name
          example: John Doe
          nullable: true
        phone:
          type: string
          description: User's phone number
          example: +1-555-123-4567
          nullable: true
        phoneExt:
          type: string
          description: Phone extension
          example: '123'
          nullable: true
        status:
          type: string
          description: User account status
          enum:
            - PENDING
            - ACTIVE
            - INACTIVE
          example: ACTIVE
        avatarId:
          type: string
          format: uuid
          description: Profile avatar document ID
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
          nullable: true
        createdAt:
          type: string
          format: date-time
          description: When the user was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the user was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          description: When the user was soft deleted (null if active)
          example: null
          nullable: true
    CustomerReference:
      type: object
      description: |
        Enhanced reference to a customer resource (returned in responses).
        Includes full customer details in addition to id/key.

        Note: Does NOT include nested references (paymentTerm, contacts, etc.) to prevent recursion.
        Maximum nesting depth: 1 level.
      required:
        - id
        - name
        - friendlyId
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Customer UUID
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          maxLength: 512
          description: Client-defined reference ID if set
          example: ERP-CUSTOMER-ACME
          nullable: true
        name:
          type: string
          description: Customer company name
          example: Acme Manufacturing Corp
        friendlyId:
          type: string
          description: Human-readable customer identifier
          example: A123456
        status:
          type: string
          description: Customer status
          enum:
            - NEW
            - CONTACTED
            - QUALIFIED
            - QUOTED
            - NURTURING
            - PENDING
            - ACTIVE
            - INACTIVE
            - BLOCKED
            - CLOSED
          example: ACTIVE
        phoneNumber:
          type: string
          description: Primary phone number
          example: +1-555-123-4567
          nullable: true
        website:
          type: string
          description: Customer website URL
          example: https://acme-manufacturing.com
          nullable: true
        createdAt:
          type: string
          format: date-time
          description: When the customer was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the customer was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          description: When the customer was soft deleted (null if active)
          example: null
          nullable: true
    CarrierReference:
      type: object
      description: |
        Enhanced reference to a carrier resource (returned in responses).
        Includes full carrier details in addition to id/key.

        Note: Does NOT include nested references (contacts, etc.) to prevent recursion.
        Maximum nesting depth: 1 level.
      required:
        - id
        - name
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Carrier UUID
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          maxLength: 512
          description: Client-defined reference ID if set
          example: ERP-CARRIER-SWIFT
          nullable: true
        name:
          type: string
          description: Carrier company name
          example: Swift Transportation
        phoneNumber:
          type: string
          description: Primary phone number
          example: +1-555-987-6543
          nullable: true
        email:
          type: string
          format: email
          description: Primary email address
          example: dispatch@swifttrans.com
          nullable: true
        createdAt:
          type: string
          format: date-time
          description: When the carrier was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the carrier was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          description: When the carrier was soft deleted (null if active)
          example: null
          nullable: true
    CarrierType:
      type: string
      description: |
        Type of carrier operation.

        Note: In the backend, null carrier type is represented as TRUCKLOAD in the public API.
      enum:
        - TRUCKLOAD
        - AIR
        - CARTAGE
        - LINEHAUL
        - LTL
        - OCEAN
        - AGENT
        - RAIL
      example: TRUCKLOAD
    CarrierEquipment:
      type: string
      description: Equipment types that a carrier can operate
      enum:
        - CONTAINER
        - FLATBED
        - POWER_ONLY
        - REEFER
        - SPECIALIZED
        - TANKER
        - VAN
      example: VAN
    Currency:
      type: string
      description: Currency code (ISO 4217)
      enum:
        - ARS
        - AUD
        - BRL
        - CAD
        - CNY
        - EUR
        - GBP
        - IDR
        - INR
        - JPY
        - KRW
        - MXN
        - RUB
        - SAR
        - TRY
        - USD
        - ZAR
      example: USD
    CarrierBase:
      type: object
      required:
        - id
        - name
        - friendlyId
        - status
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - CARRIER
          readOnly: true
          description: Object type identifier
          example: CARRIER
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique carrier identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        friendlyId:
          type: string
          readOnly: true
          description: Human-readable carrier identifier
          example: C123456
        type:
          allOf:
            - $ref: '#/components/schemas/CarrierType'
          description: Carrier operation type (discriminator field)
        name:
          type: string
          description: Carrier legal name
          example: Swift Transportation Co
        dbaName:
          type: string
          description: Doing Business As name
          example: Swift Logistics
          nullable: true
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CARRIER-SWIFT-001
          nullable: true
        email:
          type: string
          format: email
          description: Primary email address
          example: dispatch@swifttrans.com
          nullable: true
        phone:
          type: string
          description: Primary phone number
          example: +1-555-987-6543
          nullable: true
        website:
          type: string
          description: Company website URL
          example: https://swifttrans.com
          nullable: true
        status:
          type: string
          description: Carrier status
          example: ACTIVE
        statusReason:
          type: string
          description: Reason for current status
          example: Active and in good standing
          nullable: true
        notes:
          type: string
          description: Internal notes about the carrier
          example: Preferred carrier for midwest routes
          nullable: true
        corporateAddress:
          description: Corporate headquarters address
          $ref: '#/components/schemas/Address'
          nullable: true
        billingAddress:
          description: Billing address for invoices
          $ref: '#/components/schemas/Address'
          nullable: true
        mcNumber:
          type: string
          description: Motor Carrier (MC) number
          example: MC-123456
          nullable: true
        dotNumber:
          type: string
          description: Department of Transportation (DOT) number
          example: '1234567'
          nullable: true
        scac:
          type: string
          description: Standard Carrier Alpha Code
          example: SWFT
          nullable: true
        einNumber:
          type: string
          description: Employer Identification Number
          example: 12-3456789
          nullable: true
        ffNumber:
          type: string
          description: Freight Forwarder (FF) number
          example: FF-123456
          nullable: true
        mxNumber:
          type: string
          description: Mexico carrier registration number
          example: MX-123456
          nullable: true
        rfcNumber:
          type: string
          description: RFC (Mexico tax ID) number
          example: ABCD123456XYZ
          nullable: true
        iataCode:
          type: string
          description: International Air Transport Association code
          example: AA
          nullable: true
        equipments:
          type: array
          description: Equipment types this carrier operates
          items:
            $ref: '#/components/schemas/CarrierEquipment'
          example:
            - VAN
            - REEFER
        isHazmat:
          type: boolean
          description: Whether carrier is certified to transport hazardous materials
          example: false
          nullable: true
        tsaApproved:
          type: boolean
          description: Whether carrier is TSA approved
          example: true
          nullable: true
        trucks:
          type: integer
          description: Number of trucks in fleet
          example: 50
          nullable: true
        trailers:
          type: integer
          description: Number of trailers in fleet
          example: 100
          nullable: true
        drivers:
          type: integer
          description: Number of drivers employed
          example: 75
          nullable: true
        powerUnits:
          type: integer
          description: Number of power units
          example: 50
          nullable: true
        currency:
          description: Preferred currency for transactions
          $ref: '#/components/schemas/Currency'
          nullable: true
        paymentTerm:
          description: Payment terms for this carrier
          $ref: '#/components/schemas/PaymentTermReference'
          nullable: true
        isFactoringPreferred:
          type: boolean
          description: Whether carrier prefers factoring for payment
          example: false
          nullable: true
        goldenCarrierId:
          type: string
          format: uuid
          description: Reference to golden carrier record (for deduplication)
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
          nullable: true
        paymentMethods:
          type: array
          description: Payment methods configured for this carrier
          items:
            $ref: '#/components/schemas/CarrierPaymentMethodReference'
        contacts:
          type: array
          description: Contacts for this carrier
          items:
            $ref: '#/components/schemas/CarrierContactReference'
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the carrier was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the carrier was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the carrier was soft deleted (null if active)
          example: null
          nullable: true
    TruckloadCarrier:
      allOf:
        - $ref: '#/components/schemas/CarrierBase'
        - type: object
          description: Truckload carrier with insurance, safety rating, and FMCSA data
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - TRUCKLOAD
              description: Carrier type discriminator
              example: TRUCKLOAD
            insuranceCompany:
              type: string
              description: Insurance company name
              example: State Farm Insurance
              nullable: true
            insuranceAgent:
              type: string
              description: Insurance agent name
              example: John Smith
              nullable: true
            insuranceAgentPhone:
              type: string
              description: Insurance agent phone number
              example: +1-555-123-4567
              nullable: true
            insuranceAuthorityDate:
              type: string
              format: date-time
              description: Date insurance authority was granted
              example: '2025-01-01T00:00:00Z'
              nullable: true
            insuranceExpirationDate:
              type: string
              format: date-time
              description: Insurance policy expiration date
              example: '2025-12-31T23:59:59Z'
              nullable: true
            insuranceAutoLiabilityLimit:
              type: number
              format: float
              description: Auto liability insurance limit (in dollars)
              example: 1000000
              nullable: true
            insuranceCargoLiabilityLimit:
              type: number
              format: float
              description: Cargo liability insurance limit (in dollars)
              example: 100000
              nullable: true
            insuranceGeneralLiabilityLimit:
              type: number
              format: float
              description: General liability insurance limit (in dollars)
              example: 1000000
              nullable: true
            rating:
              type: string
              description: Carrier safety rating
              example: SATISFACTORY
              nullable: true
            ratingDate:
              type: string
              format: date
              description: Date of last safety rating
              example: '2025-01-15'
              nullable: true
            reviewType:
              type: string
              description: Type of safety review conducted
              example: COMPLIANCE_REVIEW
              nullable: true
            reviewDate:
              type: string
              format: date
              description: Date of last safety review
              example: '2025-01-15'
              nullable: true
            operatingAbility:
              type: string
              description: FMCSA operating authority status
              example: AUTHORIZED
              nullable: true
            inFmcsa:
              type: boolean
              description: Whether carrier is registered in FMCSA database
              example: true
              nullable: true
            usDriverInspections:
              type: integer
              description: Total number of US driver inspections
              example: 100
              nullable: true
            usDriverInspectionsOos:
              type: integer
              description: Number of US driver inspections resulting in out-of-service
              example: 5
              nullable: true
            usDriverInspectionsOosPct:
              type: number
              format: float
              description: Percentage of US driver inspections resulting in out-of-service
              example: 5
              nullable: true
            usVehicleInspections:
              type: integer
              description: Total number of US vehicle inspections
              example: 150
              nullable: true
            usVehicleInspectionsOos:
              type: integer
              description: Number of US vehicle inspections resulting in out-of-service
              example: 8
              nullable: true
            usVehicleInspectionsOosPct:
              type: number
              format: float
              description: Percentage of US vehicle inspections resulting in out-of-service
              example: 5.33
              nullable: true
    AirCarrier:
      allOf:
        - $ref: '#/components/schemas/CarrierBase'
        - type: object
          description: Air cargo carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - AIR
              description: Carrier type discriminator
              example: AIR
    CartageCarrier:
      allOf:
        - $ref: '#/components/schemas/CarrierBase'
        - type: object
          description: Cartage (local pickup/delivery) carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - CARTAGE
              description: Carrier type discriminator
              example: CARTAGE
    LinehaulCarrier:
      allOf:
        - $ref: '#/components/schemas/CarrierBase'
        - type: object
          description: Linehaul (long-distance) carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - LINEHAUL
              description: Carrier type discriminator
              example: LINEHAUL
    LtlCarrier:
      allOf:
        - $ref: '#/components/schemas/CarrierBase'
        - type: object
          description: Less-than-truckload (LTL) carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - LTL
              description: Carrier type discriminator
              example: LTL
    OceanCarrier:
      allOf:
        - $ref: '#/components/schemas/CarrierBase'
        - type: object
          description: Ocean freight carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - OCEAN
              description: Carrier type discriminator
              example: OCEAN
    RailCarrier:
      allOf:
        - $ref: '#/components/schemas/CarrierBase'
        - type: object
          description: Rail freight carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - RAIL
              description: Carrier type discriminator
              example: RAIL
    Carrier:
      oneOf:
        - $ref: '#/components/schemas/TruckloadCarrier'
        - $ref: '#/components/schemas/AirCarrier'
        - $ref: '#/components/schemas/CartageCarrier'
        - $ref: '#/components/schemas/LinehaulCarrier'
        - $ref: '#/components/schemas/LtlCarrier'
        - $ref: '#/components/schemas/OceanCarrier'
        - $ref: '#/components/schemas/RailCarrier'
        - $ref: '#/components/schemas/AgentCarrier'
      discriminator:
        propertyName: type
        mapping:
          TRUCKLOAD: '#/components/schemas/TruckloadCarrier'
          AIR: '#/components/schemas/AirCarrier'
          CARTAGE: '#/components/schemas/CartageCarrier'
          LINEHAUL: '#/components/schemas/LinehaulCarrier'
          LTL: '#/components/schemas/LtlCarrier'
          OCEAN: '#/components/schemas/OceanCarrier'
          RAIL: '#/components/schemas/RailCarrier'
          AGENT: '#/components/schemas/AgentCarrier'
    CarrierInputBase:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: Carrier legal name
          example: Swift Transportation Co
        type:
          $ref: '#/components/schemas/CarrierType'
          description: Carrier operation type (discriminator field)
        dbaName:
          type: string
          description: Doing Business As name
          example: Swift Logistics
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CARRIER-SWIFT-001
        email:
          type: string
          format: email
          description: Primary email address
          example: dispatch@swifttrans.com
        phone:
          type: string
          description: Primary phone number
          example: +1-555-987-6543
        website:
          type: string
          description: Company website URL
          example: https://swifttrans.com
        status:
          type: string
          description: Carrier status
          example: ACTIVE
        statusReason:
          type: string
          description: Reason for current status
          example: Active and in good standing
        notes:
          type: string
          description: Internal notes about the carrier
          example: Preferred carrier for midwest routes
        corporateAddress:
          $ref: '#/components/schemas/AddressInput'
          description: Corporate headquarters address
        billingAddress:
          $ref: '#/components/schemas/AddressInput'
          description: Billing address for invoices
        mcNumber:
          type: string
          description: Motor Carrier (MC) number
          example: MC-123456
        dotNumber:
          type: string
          description: Department of Transportation (DOT) number
          example: '1234567'
        scac:
          type: string
          description: Standard Carrier Alpha Code
          example: SWFT
        einNumber:
          type: string
          description: Employer Identification Number
          example: 12-3456789
        ffNumber:
          type: string
          description: Freight Forwarder (FF) number
          example: FF-123456
        mxNumber:
          type: string
          description: Mexico carrier registration number
          example: MX-123456
        rfcNumber:
          type: string
          description: RFC (Mexico tax ID) number
          example: ABCD123456XYZ
        iataCode:
          type: string
          description: International Air Transport Association code
          example: AA
        equipments:
          type: array
          description: Equipment types this carrier operates
          items:
            $ref: '#/components/schemas/CarrierEquipment'
          example:
            - VAN
            - REEFER
        isHazmat:
          type: boolean
          description: Whether carrier is certified to transport hazardous materials
          example: false
        tsaApproved:
          type: boolean
          description: Whether carrier is TSA approved
          example: true
        trucks:
          type: integer
          description: Number of trucks in fleet
          example: 50
        trailers:
          type: integer
          description: Number of trailers in fleet
          example: 100
        drivers:
          type: integer
          description: Number of drivers employed
          example: 75
        powerUnits:
          type: integer
          description: Number of power units
          example: 50
        currency:
          $ref: '#/components/schemas/Currency'
          description: Preferred currency for transactions
        paymentTermId:
          type: string
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
        isFactoringPreferred:
          type: boolean
          description: Whether carrier prefers factoring for payment
          example: false
        goldenCarrierId:
          type: string
          format: uuid
          description: Reference to golden carrier record (for deduplication)
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
    TruckloadCarrierInput:
      allOf:
        - $ref: '#/components/schemas/CarrierInputBase'
        - type: object
          description: Input for creating a truckload carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - TRUCKLOAD
              description: Carrier type discriminator (must be TRUCKLOAD)
              example: TRUCKLOAD
            insuranceCompany:
              type: string
              description: Insurance company name
              example: State Farm Insurance
            insuranceAgent:
              type: string
              description: Insurance agent name
              example: John Smith
            insuranceAgentPhone:
              type: string
              description: Insurance agent phone number
              example: +1-555-123-4567
            insuranceAuthorityDate:
              type: string
              format: date-time
              description: Date insurance authority was granted
              example: '2025-01-01T00:00:00Z'
            insuranceExpirationDate:
              type: string
              format: date-time
              description: Insurance policy expiration date
              example: '2025-12-31T23:59:59Z'
            insuranceAutoLiabilityLimit:
              type: number
              format: float
              description: Auto liability insurance limit (in dollars)
              example: 1000000
            insuranceCargoLiabilityLimit:
              type: number
              format: float
              description: Cargo liability insurance limit (in dollars)
              example: 100000
            insuranceGeneralLiabilityLimit:
              type: number
              format: float
              description: General liability insurance limit (in dollars)
              example: 1000000
            rating:
              type: string
              description: Carrier safety rating
              example: SATISFACTORY
            ratingDate:
              type: string
              format: date
              description: Date of last safety rating
              example: '2025-01-15'
            reviewType:
              type: string
              description: Type of safety review conducted
              example: COMPLIANCE_REVIEW
            reviewDate:
              type: string
              format: date
              description: Date of last safety review
              example: '2025-01-15'
            operatingAbility:
              type: string
              description: FMCSA operating authority status
              example: AUTHORIZED
            inFmcsa:
              type: boolean
              description: Whether carrier is registered in FMCSA database
              example: true
            usDriverInspections:
              type: integer
              description: Total number of US driver inspections
              example: 100
            usDriverInspectionsOos:
              type: integer
              description: Number of US driver inspections resulting in out-of-service
              example: 5
            usDriverInspectionsOosPct:
              type: number
              format: float
              description: Percentage of US driver inspections resulting in out-of-service
              example: 5
            usVehicleInspections:
              type: integer
              description: Total number of US vehicle inspections
              example: 150
            usVehicleInspectionsOos:
              type: integer
              description: Number of US vehicle inspections resulting in out-of-service
              example: 8
            usVehicleInspectionsOosPct:
              type: number
              format: float
              description: Percentage of US vehicle inspections resulting in out-of-service
              example: 5.33
    AirCarrierInput:
      allOf:
        - $ref: '#/components/schemas/CarrierInputBase'
        - type: object
          description: Input for creating an air carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - AIR
              description: Carrier type discriminator (must be AIR)
              example: AIR
    CartageCarrierInput:
      allOf:
        - $ref: '#/components/schemas/CarrierInputBase'
        - type: object
          description: Input for creating a cartage carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - CARTAGE
              description: Carrier type discriminator (must be CARTAGE)
              example: CARTAGE
    LinehaulCarrierInput:
      allOf:
        - $ref: '#/components/schemas/CarrierInputBase'
        - type: object
          description: Input for creating a linehaul carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - LINEHAUL
              description: Carrier type discriminator (must be LINEHAUL)
              example: LINEHAUL
    LtlCarrierInput:
      allOf:
        - $ref: '#/components/schemas/CarrierInputBase'
        - type: object
          description: Input for creating an LTL carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - LTL
              description: Carrier type discriminator (must be LTL)
              example: LTL
    OceanCarrierInput:
      allOf:
        - $ref: '#/components/schemas/CarrierInputBase'
        - type: object
          description: Input for creating an ocean carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - OCEAN
              description: Carrier type discriminator (must be OCEAN)
              example: OCEAN
    RailCarrierInput:
      allOf:
        - $ref: '#/components/schemas/CarrierInputBase'
        - type: object
          description: Input for creating a rail carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - RAIL
              description: Carrier type discriminator (must be RAIL)
              example: RAIL
    CarrierInput:
      oneOf:
        - $ref: '#/components/schemas/TruckloadCarrierInput'
        - $ref: '#/components/schemas/AirCarrierInput'
        - $ref: '#/components/schemas/CartageCarrierInput'
        - $ref: '#/components/schemas/LinehaulCarrierInput'
        - $ref: '#/components/schemas/LtlCarrierInput'
        - $ref: '#/components/schemas/OceanCarrierInput'
        - $ref: '#/components/schemas/RailCarrierInput'
        - $ref: '#/components/schemas/AgentCarrierInput'
      discriminator:
        propertyName: type
        mapping:
          TRUCKLOAD: '#/components/schemas/TruckloadCarrierInput'
          AIR: '#/components/schemas/AirCarrierInput'
          CARTAGE: '#/components/schemas/CartageCarrierInput'
          LINEHAUL: '#/components/schemas/LinehaulCarrierInput'
          LTL: '#/components/schemas/LtlCarrierInput'
          OCEAN: '#/components/schemas/OceanCarrierInput'
          RAIL: '#/components/schemas/RailCarrierInput'
          AGENT: '#/components/schemas/AgentCarrierInput'
    CarrierPatchBase:
      type: object
      description: |
        Partial carrier update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Carrier legal name
          example: Swift Transportation Co
        type:
          $ref: '#/components/schemas/CarrierType'
          description: Carrier operation type
        dbaName:
          type: string
          description: Doing Business As name
          example: Swift Logistics
          nullable: true
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CARRIER-SWIFT-001
          nullable: true
        email:
          type: string
          format: email
          description: Primary email address
          example: dispatch@swifttrans.com
          nullable: true
        phone:
          type: string
          description: Primary phone number
          example: +1-555-987-6543
          nullable: true
        website:
          type: string
          description: Company website URL
          example: https://swifttrans.com
          nullable: true
        status:
          type: string
          description: Carrier status
          example: ACTIVE
        statusReason:
          type: string
          description: Reason for current status
          example: Active and in good standing
          nullable: true
        notes:
          type: string
          description: Internal notes about the carrier
          example: Preferred carrier for midwest routes
          nullable: true
        corporateAddress:
          $ref: '#/components/schemas/AddressPatch'
          description: Corporate headquarters address
        billingAddress:
          $ref: '#/components/schemas/AddressPatch'
          description: Billing address for invoices
        mcNumber:
          type: string
          description: Motor Carrier (MC) number
          example: MC-123456
          nullable: true
        dotNumber:
          type: string
          description: Department of Transportation (DOT) number
          example: '1234567'
          nullable: true
        scac:
          type: string
          description: Standard Carrier Alpha Code
          example: SWFT
          nullable: true
        einNumber:
          type: string
          description: Employer Identification Number
          example: 12-3456789
          nullable: true
        ffNumber:
          type: string
          description: Freight Forwarder (FF) number
          example: FF-123456
          nullable: true
        mxNumber:
          type: string
          description: Mexico carrier registration number
          example: MX-123456
          nullable: true
        rfcNumber:
          type: string
          description: RFC (Mexico tax ID) number
          example: ABCD123456XYZ
          nullable: true
        iataCode:
          type: string
          description: International Air Transport Association code
          example: AA
          nullable: true
        equipments:
          type: array
          description: Equipment types this carrier operates
          items:
            $ref: '#/components/schemas/CarrierEquipment'
          example:
            - VAN
            - REEFER
        isHazmat:
          type: boolean
          description: Whether carrier is certified to transport hazardous materials
          example: false
          nullable: true
        tsaApproved:
          type: boolean
          description: Whether carrier is TSA approved
          example: true
          nullable: true
        trucks:
          type: integer
          description: Number of trucks in fleet
          example: 50
          nullable: true
        trailers:
          type: integer
          description: Number of trailers in fleet
          example: 100
          nullable: true
        drivers:
          type: integer
          description: Number of drivers employed
          example: 75
          nullable: true
        powerUnits:
          type: integer
          description: Number of power units
          example: 50
          nullable: true
        currency:
          description: Preferred currency for transactions
          $ref: '#/components/schemas/Currency'
          nullable: true
        paymentTermId:
          type: string
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
          nullable: true
        isFactoringPreferred:
          type: boolean
          description: Whether carrier prefers factoring for payment
          example: false
          nullable: true
        goldenCarrierId:
          type: string
          format: uuid
          description: Reference to golden carrier record (for deduplication)
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
          nullable: true
    TruckloadCarrierPatch:
      allOf:
        - $ref: '#/components/schemas/CarrierPatchBase'
        - type: object
          description: Partial update for truckload carrier
          properties:
            type:
              type: string
              enum:
                - TRUCKLOAD
              description: Carrier type discriminator (optional - only needed if changing type)
              example: TRUCKLOAD
            insuranceCompany:
              type: string
              description: Insurance company name
              example: State Farm Insurance
              nullable: true
            insuranceAgent:
              type: string
              description: Insurance agent name
              example: John Smith
              nullable: true
            insuranceAgentPhone:
              type: string
              description: Insurance agent phone number
              example: +1-555-123-4567
              nullable: true
            insuranceAuthorityDate:
              type: string
              format: date-time
              description: Date insurance authority was granted
              example: '2025-01-01T00:00:00Z'
              nullable: true
            insuranceExpirationDate:
              type: string
              format: date-time
              description: Insurance policy expiration date
              example: '2025-12-31T23:59:59Z'
              nullable: true
            insuranceAutoLiabilityLimit:
              type: number
              format: float
              description: Auto liability insurance limit (in dollars)
              example: 1000000
              nullable: true
            insuranceCargoLiabilityLimit:
              type: number
              format: float
              description: Cargo liability insurance limit (in dollars)
              example: 100000
              nullable: true
            insuranceGeneralLiabilityLimit:
              type: number
              format: float
              description: General liability insurance limit (in dollars)
              example: 1000000
              nullable: true
            rating:
              type: string
              description: Carrier safety rating
              example: SATISFACTORY
              nullable: true
            ratingDate:
              type: string
              format: date
              description: Date of last safety rating
              example: '2025-01-15'
              nullable: true
            reviewType:
              type: string
              description: Type of safety review conducted
              example: COMPLIANCE_REVIEW
              nullable: true
            reviewDate:
              type: string
              format: date
              description: Date of last safety review
              example: '2025-01-15'
              nullable: true
            operatingAbility:
              type: string
              description: FMCSA operating authority status
              example: AUTHORIZED
              nullable: true
            inFmcsa:
              type: boolean
              description: Whether carrier is registered in FMCSA database
              example: true
              nullable: true
            usDriverInspections:
              type: integer
              description: Total number of US driver inspections
              example: 100
              nullable: true
            usDriverInspectionsOos:
              type: integer
              description: Number of US driver inspections resulting in out-of-service
              example: 5
              nullable: true
            usDriverInspectionsOosPct:
              type: number
              format: float
              description: Percentage of US driver inspections resulting in out-of-service
              example: 5
              nullable: true
            usVehicleInspections:
              type: integer
              description: Total number of US vehicle inspections
              example: 150
              nullable: true
            usVehicleInspectionsOos:
              type: integer
              description: Number of US vehicle inspections resulting in out-of-service
              example: 8
              nullable: true
            usVehicleInspectionsOosPct:
              type: number
              format: float
              description: Percentage of US vehicle inspections resulting in out-of-service
              example: 5.33
              nullable: true
    AirCarrierPatch:
      allOf:
        - $ref: '#/components/schemas/CarrierPatchBase'
        - type: object
          description: Partial update for air carrier
          properties:
            type:
              type: string
              enum:
                - AIR
              description: Carrier type discriminator (optional - only needed if changing type)
              example: AIR
    CartageCarrierPatch:
      allOf:
        - $ref: '#/components/schemas/CarrierPatchBase'
        - type: object
          description: Partial update for cartage carrier
          properties:
            type:
              type: string
              enum:
                - CARTAGE
              description: Carrier type discriminator (optional - only needed if changing type)
              example: CARTAGE
    LinehaulCarrierPatch:
      allOf:
        - $ref: '#/components/schemas/CarrierPatchBase'
        - type: object
          description: Partial update for linehaul carrier
          properties:
            type:
              type: string
              enum:
                - LINEHAUL
              description: Carrier type discriminator (optional - only needed if changing type)
              example: LINEHAUL
    LtlCarrierPatch:
      allOf:
        - $ref: '#/components/schemas/CarrierPatchBase'
        - type: object
          description: Partial update for LTL carrier
          properties:
            type:
              type: string
              enum:
                - LTL
              description: Carrier type discriminator (optional - only needed if changing type)
              example: LTL
    OceanCarrierPatch:
      allOf:
        - $ref: '#/components/schemas/CarrierPatchBase'
        - type: object
          description: Partial update for ocean carrier
          properties:
            type:
              type: string
              enum:
                - OCEAN
              description: Carrier type discriminator (optional - only needed if changing type)
              example: OCEAN
    RailCarrierPatch:
      allOf:
        - $ref: '#/components/schemas/CarrierPatchBase'
        - type: object
          description: Partial update for rail carrier
          properties:
            type:
              type: string
              enum:
                - RAIL
              description: Carrier type discriminator (optional - only needed if changing type)
              example: RAIL
    CarrierPatch:
      description: |
        Partial carrier update, discriminated by `type`. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable — except
          `type`, which only changes through a discriminator value
      oneOf:
        - $ref: '#/components/schemas/TruckloadCarrierPatch'
        - $ref: '#/components/schemas/AirCarrierPatch'
        - $ref: '#/components/schemas/CartageCarrierPatch'
        - $ref: '#/components/schemas/LinehaulCarrierPatch'
        - $ref: '#/components/schemas/LtlCarrierPatch'
        - $ref: '#/components/schemas/OceanCarrierPatch'
        - $ref: '#/components/schemas/RailCarrierPatch'
        - $ref: '#/components/schemas/AgentCarrierPatch'
      discriminator:
        propertyName: type
        mapping:
          TRUCKLOAD: '#/components/schemas/TruckloadCarrierPatch'
          AIR: '#/components/schemas/AirCarrierPatch'
          CARTAGE: '#/components/schemas/CartageCarrierPatch'
          LINEHAUL: '#/components/schemas/LinehaulCarrierPatch'
          LTL: '#/components/schemas/LtlCarrierPatch'
          OCEAN: '#/components/schemas/OceanCarrierPatch'
          RAIL: '#/components/schemas/RailCarrierPatch'
          AGENT: '#/components/schemas/AgentCarrierPatch'
    CarrierFilter:
      type: object
      description: Filter criteria for carriers with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierFilter'
        not:
          $ref: '#/components/schemas/CarrierFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        friendlyId:
          $ref: '#/components/schemas/StringFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        dbaName:
          $ref: '#/components/schemas/StringFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        phone:
          $ref: '#/components/schemas/StringFilter'
        website:
          $ref: '#/components/schemas/StringFilter'
        status:
          $ref: '#/components/schemas/StringFilter'
        statusReason:
          $ref: '#/components/schemas/StringFilter'
        type:
          $ref: '#/components/schemas/StringFilter'
        mcNumber:
          $ref: '#/components/schemas/StringFilter'
        dotNumber:
          $ref: '#/components/schemas/StringFilter'
        scac:
          $ref: '#/components/schemas/StringFilter'
        einNumber:
          $ref: '#/components/schemas/StringFilter'
        ffNumber:
          $ref: '#/components/schemas/StringFilter'
        mxNumber:
          $ref: '#/components/schemas/StringFilter'
        rfcNumber:
          $ref: '#/components/schemas/StringFilter'
        iataCode:
          $ref: '#/components/schemas/StringFilter'
        isHazmat:
          $ref: '#/components/schemas/BooleanFilter'
        tsaApproved:
          $ref: '#/components/schemas/BooleanFilter'
        trucks:
          $ref: '#/components/schemas/IntFilter'
        trailers:
          $ref: '#/components/schemas/IntFilter'
        drivers:
          $ref: '#/components/schemas/IntFilter'
        powerUnits:
          $ref: '#/components/schemas/IntFilter'
        currency:
          $ref: '#/components/schemas/StringFilter'
        isFactoringPreferred:
          $ref: '#/components/schemas/BooleanFilter'
        goldenCarrierId:
          $ref: '#/components/schemas/UUIDFilter'
        paymentTermId:
          $ref: '#/components/schemas/UUIDFilter'
        rating:
          $ref: '#/components/schemas/StringFilter'
        ratingDate:
          $ref: '#/components/schemas/DatetimeFilter'
        operatingAbility:
          $ref: '#/components/schemas/StringFilter'
        inFmcsa:
          $ref: '#/components/schemas/BooleanFilter'
        insuranceCompany:
          $ref: '#/components/schemas/StringFilter'
        insuranceExpirationDate:
          $ref: '#/components/schemas/DatetimeFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    CarrierFilterRequest:
      type: object
      description: Request body for filtering carriers
      properties:
        filter:
          $ref: '#/components/schemas/CarrierFilter'
          description: |
            Filter criteria (optional - omit to return all carriers).

            Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - type:
                equalTo: TRUCKLOAD
            - status:
                equalTo: ACTIVE
            - inFmcsa:
                equalTo: true
        pageSize: 50
    CarrierFactor:
      type: object
      required:
        - id
        - companyName
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique carrier factor identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        companyName:
          type: string
          description: Factoring company legal name
          example: Capital Factoring Services Inc
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-FACTOR-001
          nullable: true
        email:
          type: string
          format: email
          description: Primary email address
          example: accounting@capitalfactoring.com
          nullable: true
        phoneNumber:
          type: string
          description: Primary phone number
          example: +1-555-234-5678
          nullable: true
        phoneExtension:
          type: string
          description: Primary phone extension
          example: '123'
          nullable: true
        fax:
          type: string
          description: Fax number
          example: +1-555-234-9999
          nullable: true
        addressLine1:
          type: string
          description: Primary street address
          example: 789 Finance Ave
          nullable: true
        addressLine2:
          type: string
          description: Secondary address line (suite, floor, etc.)
          example: Suite 500
          nullable: true
        city:
          type: string
          description: City name
          example: Dallas
          nullable: true
        state:
          type: string
          description: State or province
          example: TX
          nullable: true
        country:
          type: string
          description: Country code or name
          example: USA
          nullable: true
        zipCode:
          type: string
          description: Postal/ZIP code
          example: '75201'
          nullable: true
        bankName:
          type: string
          description: Bank name
          example: Chase Bank
          nullable: true
        bankAddress:
          type: string
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
          nullable: true
        accountName:
          type: string
          description: Bank account holder name
          example: Capital Factoring Services Inc
          nullable: true
        accountNumber:
          type: string
          description: Bank account number
          example: '****1234'
          nullable: true
        abaAch:
          type: string
          description: ABA/ACH routing number for electronic transfers
          example: '021000021'
          nullable: true
        wire:
          type: string
          description: Wire transfer routing number
          example: '026009593'
          nullable: true
        swiftCode:
          type: string
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
          nullable: true
        eftInstitution:
          type: string
          description: EFT institution number (Canadian banking)
          example: '001'
          nullable: true
        eftTransit:
          type: string
          description: EFT transit number (Canadian banking)
          example: '00010'
          nullable: true
        clabe:
          type: string
          description: CLABE number (Mexican banking identifier)
          example: '012180001234567897'
          nullable: true
        currency:
          type: string
          description: Preferred currency code (ISO 4217)
          example: USD
          nullable: true
        paymentTerm:
          description: Payment terms for this factoring company
          $ref: '#/components/schemas/PaymentTermReference'
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the carrier factor was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the carrier factor was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the carrier factor was soft deleted (null if active)
          example: null
          nullable: true
    CarrierFactorInput:
      type: object
      required:
        - companyName
      properties:
        companyName:
          type: string
          description: Factoring company legal name
          example: Capital Factoring Services Inc
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-FACTOR-001
        email:
          type: string
          format: email
          description: Primary email address
          example: accounting@capitalfactoring.com
        phoneNumber:
          type: string
          description: Primary phone number
          example: +1-555-234-5678
        phoneExtension:
          type: string
          description: Primary phone extension
          example: '123'
        fax:
          type: string
          description: Fax number
          example: +1-555-234-9999
        addressLine1:
          type: string
          description: Primary street address
          example: 789 Finance Ave
        addressLine2:
          type: string
          description: Secondary address line (suite, floor, etc.)
          example: Suite 500
        city:
          type: string
          description: City name
          example: Dallas
        state:
          type: string
          description: State or province
          example: TX
        country:
          type: string
          description: Country code or name
          example: USA
        zipCode:
          type: string
          description: Postal/ZIP code
          example: '75201'
        bankName:
          type: string
          description: Bank name
          example: Chase Bank
        bankAddress:
          type: string
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
        accountName:
          type: string
          description: Bank account holder name
          example: Capital Factoring Services Inc
        accountNumber:
          type: string
          description: Bank account number
          example: '1234567890'
        abaAch:
          type: string
          description: ABA/ACH routing number for electronic transfers
          example: '021000021'
        wire:
          type: string
          description: Wire transfer routing number
          example: '026009593'
        swiftCode:
          type: string
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
        eftInstitution:
          type: string
          description: EFT institution number (Canadian banking)
          example: '001'
        eftTransit:
          type: string
          description: EFT transit number (Canadian banking)
          example: '00010'
        clabe:
          type: string
          description: CLABE number (Mexican banking identifier)
          example: '012180001234567897'
        currency:
          type: string
          description: Preferred currency code (ISO 4217)
          example: USD
        paymentTermId:
          type: string
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
    CarrierFactorPatch:
      type: object
      description: |
        Partial carrier factor update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        companyName:
          type: string
          description: Factoring company legal name
          example: Capital Factoring Services Inc
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-FACTOR-001
          nullable: true
        email:
          type: string
          format: email
          description: Primary email address
          example: accounting@capitalfactoring.com
          nullable: true
        phoneNumber:
          type: string
          description: Primary phone number
          example: +1-555-234-5678
          nullable: true
        phoneExtension:
          type: string
          description: Primary phone extension
          example: '123'
          nullable: true
        fax:
          type: string
          description: Fax number
          example: +1-555-234-9999
          nullable: true
        addressLine1:
          type: string
          description: Primary street address
          example: 789 Finance Ave
          nullable: true
        addressLine2:
          type: string
          description: Secondary address line
          example: Suite 500
          nullable: true
        city:
          type: string
          description: City name
          example: Dallas
          nullable: true
        state:
          type: string
          description: State or province
          example: TX
          nullable: true
        country:
          type: string
          description: Country code or name
          example: USA
          nullable: true
        zipCode:
          type: string
          description: Postal/ZIP code
          example: '75201'
          nullable: true
        bankName:
          type: string
          description: Bank name
          example: Chase Bank
          nullable: true
        bankAddress:
          type: string
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
          nullable: true
        accountName:
          type: string
          description: Bank account holder name
          example: Capital Factoring Services Inc
          nullable: true
        accountNumber:
          type: string
          description: Bank account number
          example: '1234567890'
          nullable: true
        abaAch:
          type: string
          description: ABA/ACH routing number
          example: '021000021'
          nullable: true
        wire:
          type: string
          description: Wire transfer routing number
          example: '026009593'
          nullable: true
        swiftCode:
          type: string
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
          nullable: true
        eftInstitution:
          type: string
          description: EFT institution number (Canadian banking)
          example: '001'
          nullable: true
        eftTransit:
          type: string
          description: EFT transit number (Canadian banking)
          example: '00010'
          nullable: true
        clabe:
          type: string
          description: CLABE number (Mexican banking)
          example: '012180001234567897'
          nullable: true
        currency:
          type: string
          description: Preferred currency code (ISO 4217)
          example: USD
          nullable: true
        paymentTermId:
          type: string
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
          nullable: true
    CarrierFactorFilter:
      type: object
      description: Filter criteria for carrier factors with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierFactorFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierFactorFilter'
        not:
          $ref: '#/components/schemas/CarrierFactorFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        companyName:
          $ref: '#/components/schemas/StringFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        phoneNumber:
          $ref: '#/components/schemas/StringFilter'
        phoneExtension:
          $ref: '#/components/schemas/StringFilter'
        fax:
          $ref: '#/components/schemas/StringFilter'
        city:
          $ref: '#/components/schemas/StringFilter'
        state:
          $ref: '#/components/schemas/StringFilter'
        country:
          $ref: '#/components/schemas/StringFilter'
        zipCode:
          $ref: '#/components/schemas/StringFilter'
        bankName:
          $ref: '#/components/schemas/StringFilter'
        currency:
          $ref: '#/components/schemas/StringFilter'
        paymentTermId:
          $ref: '#/components/schemas/UUIDFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    CarrierFactorFilterRequest:
      type: object
      description: Request body for filtering carrier factors
      properties:
        filter:
          $ref: '#/components/schemas/CarrierFactorFilter'
          description: |
            Filter criteria (optional - omit to return all carrier factors).

            Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - companyName:
                includes: Capital
            - currency:
                equalTo: USD
        pageSize: 50
    CarrierFactorReference:
      type: object
      description: |
        Enhanced reference to a carrier factor (factoring company).
        Includes full carrier factor details in addition to id/key.
      required:
        - id
        - companyName
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Carrier factor UUID
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          maxLength: 512
          description: Client-defined reference ID if set
          example: ERP-FACTOR-001
          nullable: true
        companyName:
          type: string
          description: Factoring company legal name
          example: Capital Factoring Services Inc
        email:
          type: string
          format: email
          description: Primary email address
          example: accounting@capitalfactoring.com
          nullable: true
        phoneNumber:
          type: string
          description: Primary phone number
          example: +1-555-234-5678
          nullable: true
        currency:
          type: string
          description: Preferred currency code (ISO 4217)
          example: USD
          nullable: true
        createdAt:
          type: string
          format: date-time
          description: When the carrier factor was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the carrier factor was last updated
          example: '2025-01-15T14:30:00Z'
    PaymentRecipientType:
      type: string
      description: |
        Who receives the payment.

        - `DIRECT`: Payment goes directly to the carrier
        - `FACTOR`: Payment goes to a factoring company (requires carrierFactorId)
      enum:
        - DIRECT
        - FACTOR
      example: DIRECT
    PaymentRecipientTypeFilter:
      type: object
      description: Filter for payment recipient type
      properties:
        equalTo:
          $ref: '#/components/schemas/PaymentRecipientType'
        notEqualTo:
          $ref: '#/components/schemas/PaymentRecipientType'
        in:
          type: array
          items:
            $ref: '#/components/schemas/PaymentRecipientType'
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/PaymentRecipientType'
    PaymentMethodType:
      type: string
      description: Payment method type
      enum:
        - ACH_WIRE
        - ZELLE
        - VENMO
        - ACH
        - CHECK
        - WIRE
        - CAD_EFT
        - TRIUMPH_PAY
        - COMCHECK
        - EFS
        - ECHECK
        - E_TRANSFER
        - EFT_DIRECT_DEPOSIT
        - SPEI
      example: ACH
    PaymentMethodTypeFilter:
      type: object
      description: Filter for payment method type
      properties:
        equalTo:
          $ref: '#/components/schemas/PaymentMethodType'
        notEqualTo:
          $ref: '#/components/schemas/PaymentMethodType'
        in:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodType'
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodType'
    CarrierPaymentMethod:
      type: object
      required:
        - id
        - carrierId
        - carrier
        - paymentRecipientType
        - paymentMethodType
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique carrier payment method identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        carrierId:
          type: string
          format: uuid
          readOnly: true
          description: |
            Carrier profile ID (read-only after creation).

            This field cannot be changed after the payment method is created.
          example: 770e8400-e29b-41d4-a716-446655440000
        carrier:
          $ref: '#/components/schemas/CarrierReference'
          description: Carrier profile reference with full details
        paymentRecipientType:
          $ref: '#/components/schemas/PaymentRecipientType'
          description: |
            Who receives the payment.

            - **DIRECT**: Payment goes directly to the carrier (carrierFactorId must be null)
            - **FACTOR**: Payment goes to a factoring company (carrierFactorId is required)
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
          description: How payment is made
        status:
          type: string
          description: Payment method status
          example: ACTIVE
          nullable: true
        isPreferred:
          type: boolean
          description: Whether this is the preferred payment method for the carrier
          example: true
          nullable: true
        email:
          type: string
          format: email
          description: Email address for payment notifications
          example: payments@carrier.com
          nullable: true
        phone:
          type: string
          description: Phone number for payment contact
          example: +1-555-123-4567
          nullable: true
        companyName:
          type: string
          description: Company name for this payment method (may differ from carrier name)
          example: Carrier Payments LLC
          nullable: true
        username:
          type: string
          description: Username for payment platforms (e.g., Zelle, Venmo)
          example: carrier_payments
          nullable: true
        bankName:
          type: string
          description: Bank name
          example: Chase Bank
          nullable: true
        bankAddress:
          type: string
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
          nullable: true
        accountName:
          type: string
          description: Bank account holder name
          example: Carrier Transport Inc
          nullable: true
        accountNumber:
          type: string
          description: Bank account number (masked in responses)
          example: '****1234'
          nullable: true
        abaAch:
          type: string
          description: ABA/ACH routing number for electronic transfers
          example: '021000021'
          nullable: true
        wire:
          type: string
          description: Wire transfer routing number
          example: '026009593'
          nullable: true
        swiftCode:
          type: string
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
          nullable: true
        eftInstitution:
          type: string
          description: EFT institution number (Canadian banking)
          example: '001'
          nullable: true
        eftTransit:
          type: string
          description: EFT transit number (Canadian banking)
          example: '00010'
          nullable: true
        clabe:
          type: string
          description: CLABE number (Mexican banking identifier)
          example: '012180001234567897'
          nullable: true
        currency:
          type: string
          description: Preferred currency code (ISO 4217)
          example: USD
          nullable: true
        carrierFactor:
          description: |
            Factoring company reference (required when paymentRecipientType is FACTOR).

            When paymentRecipientType is DIRECT, this must be null.
          $ref: '#/components/schemas/CarrierFactorReference'
          nullable: true
        paymentTerm:
          description: Payment terms for this payment method
          $ref: '#/components/schemas/PaymentTermReference'
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was soft deleted (null if active)
          example: null
          nullable: true
        deletedBy:
          readOnly: true
          description: User who deleted this payment method
          $ref: '#/components/schemas/UserReference'
          nullable: true
    CarrierPaymentMethodInput:
      type: object
      required:
        - carrierId
        - paymentRecipientType
        - paymentMethodType
      properties:
        carrierId:
          type: string
          format: uuid
          description: |
            Carrier profile ID.

            **IMPORTANT**: This field cannot be changed after creation.
          example: 770e8400-e29b-41d4-a716-446655440000
        paymentRecipientType:
          $ref: '#/components/schemas/PaymentRecipientType'
          description: |
            Who receives the payment.

            - **DIRECT**: carrierFactorId must be null or omitted
            - **FACTOR**: carrierFactorId is required
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
          description: How payment is made
        status:
          type: string
          description: Payment method status
          example: ACTIVE
        isPreferred:
          type: boolean
          description: Whether this is the preferred payment method
          example: true
        email:
          type: string
          format: email
          description: Email address for payment notifications
          example: payments@carrier.com
        phone:
          type: string
          description: Phone number for payment contact
          example: +1-555-123-4567
        companyName:
          type: string
          description: Company name for this payment method
          example: Carrier Payments LLC
        username:
          type: string
          description: Username for payment platforms
          example: carrier_payments
        bankName:
          type: string
          description: Bank name
          example: Chase Bank
        bankAddress:
          type: string
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
        accountName:
          type: string
          description: Bank account holder name
          example: Carrier Transport Inc
        accountNumber:
          type: string
          description: Bank account number
          example: '1234567890'
        abaAch:
          type: string
          description: ABA/ACH routing number
          example: '021000021'
        wire:
          type: string
          description: Wire transfer routing number
          example: '026009593'
        swiftCode:
          type: string
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
        eftInstitution:
          type: string
          description: EFT institution number (Canadian banking)
          example: '001'
        eftTransit:
          type: string
          description: EFT transit number (Canadian banking)
          example: '00010'
        clabe:
          type: string
          description: CLABE number (Mexican banking)
          example: '012180001234567897'
        currency:
          type: string
          description: Preferred currency code (ISO 4217)
          example: USD
        carrierFactorId:
          type: string
          format: uuid
          description: |
            Carrier factor (factoring company) ID.

            **Constraint**: Required when paymentRecipientType is FACTOR, must be null when DIRECT.
          example: 550e8400-e29b-41d4-a716-446655440000
        paymentTermId:
          type: string
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
    CarrierPaymentMethodPatch:
      type: object
      description: |
        Partial carrier payment method update. All fields are optional.

        **IMPORTANT**: The `carrierId` field cannot be changed after creation.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        paymentRecipientType:
          $ref: '#/components/schemas/PaymentRecipientType'
          description: |
            Who receives the payment.

            - **DIRECT**: carrierFactorId must be null
            - **FACTOR**: carrierFactorId is required
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
          description: How payment is made
        status:
          type: string
          description: Payment method status
          example: ACTIVE
          nullable: true
        isPreferred:
          type: boolean
          description: Whether this is the preferred payment method
          example: true
          nullable: true
        email:
          type: string
          format: email
          description: Email address for payment notifications
          example: payments@carrier.com
          nullable: true
        phone:
          type: string
          description: Phone number for payment contact
          example: +1-555-123-4567
          nullable: true
        companyName:
          type: string
          description: Company name for this payment method
          example: Carrier Payments LLC
          nullable: true
        username:
          type: string
          description: Username for payment platforms
          example: carrier_payments
          nullable: true
        bankName:
          type: string
          description: Bank name
          example: Chase Bank
          nullable: true
        bankAddress:
          type: string
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
          nullable: true
        accountName:
          type: string
          description: Bank account holder name
          example: Carrier Transport Inc
          nullable: true
        accountNumber:
          type: string
          description: Bank account number
          example: '1234567890'
          nullable: true
        abaAch:
          type: string
          description: ABA/ACH routing number
          example: '021000021'
          nullable: true
        wire:
          type: string
          description: Wire transfer routing number
          example: '026009593'
          nullable: true
        swiftCode:
          type: string
          description: SWIFT/BIC code
          example: CHASUS33
          nullable: true
        eftInstitution:
          type: string
          description: EFT institution number
          example: '001'
          nullable: true
        eftTransit:
          type: string
          description: EFT transit number
          example: '00010'
          nullable: true
        clabe:
          type: string
          description: CLABE number
          example: '012180001234567897'
          nullable: true
        currency:
          type: string
          description: Preferred currency code
          example: USD
          nullable: true
        carrierFactorId:
          type: string
          format: uuid
          description: |
            Carrier factor ID.

            **Constraint**: Required when paymentRecipientType is FACTOR, must be null when DIRECT.
          example: 550e8400-e29b-41d4-a716-446655440000
          nullable: true
        paymentTermId:
          type: string
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
          nullable: true
    CarrierPaymentMethodFilter:
      type: object
      description: Filter criteria for carrier payment methods with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierPaymentMethodFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierPaymentMethodFilter'
        not:
          $ref: '#/components/schemas/CarrierPaymentMethodFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        carrierId:
          $ref: '#/components/schemas/UUIDFilter'
        paymentRecipientType:
          $ref: '#/components/schemas/PaymentRecipientTypeFilter'
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodTypeFilter'
        status:
          $ref: '#/components/schemas/StringFilter'
        isPreferred:
          $ref: '#/components/schemas/BooleanFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        companyName:
          $ref: '#/components/schemas/StringFilter'
        bankName:
          $ref: '#/components/schemas/StringFilter'
        currency:
          $ref: '#/components/schemas/StringFilter'
        carrierFactorId:
          $ref: '#/components/schemas/UUIDFilter'
        paymentTermId:
          $ref: '#/components/schemas/UUIDFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    CarrierPaymentMethodFilterRequest:
      type: object
      description: Request body for filtering carrier payment methods
      properties:
        filter:
          $ref: '#/components/schemas/CarrierPaymentMethodFilter'
          description: |
            Filter criteria (optional - omit to return all carrier payment methods).

            Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - carrierId:
                equalTo: 770e8400-e29b-41d4-a716-446655440000
            - paymentRecipientType:
                equalTo: DIRECT
            - isPreferred:
                equalTo: true
        pageSize: 50
    Address:
      type: object
      description: |
        Physical address/location details (nested, without id).

        This is an embedded object representing a Location record. The id is managed
        internally and not exposed in the API.
      required:
        - line1
        - city
        - country
        - market
        - isAirportOrAirbase
        - isConstructionOrUtilitySite
        - isSmartyValidated
        - obeysDst
      properties:
        line1:
          type: string
          description: Primary street address line
          example: 123 Main St
        line2:
          type: string
          description: Secondary address line (suite, floor, etc.)
          example: Suite 400
          nullable: true
        city:
          type: string
          description: City name
          example: Chicago
        state:
          type: string
          description: State or province code
          example: IL
          nullable: true
        zipCode:
          type: string
          description: Postal / ZIP code
          example: '60601'
          nullable: true
        country:
          type: string
          description: Country name or code
          example: USA
        market:
          type: string
          description: Market or region identifier
          example: CHI
        latitude:
          type: string
          description: Latitude coordinate
          example: '41.8781'
          nullable: true
        longitude:
          type: string
          description: Longitude coordinate
          example: '-87.6298'
          nullable: true
        isAirportOrAirbase:
          type: boolean
          description: Whether this location is an airport or airbase
          example: false
        isConstructionOrUtilitySite:
          type: boolean
          description: Whether this location is a construction or utility site
          example: false
        isSmartyValidated:
          type: boolean
          description: Whether address has been validated by SmartyStreets
          example: true
        obeysDst:
          type: boolean
          description: Whether this location observes daylight saving time
          example: true
        cityId:
          type: string
          format: uuid
          description: Reference to standardized city record (internal use)
          example: null
          nullable: true
    AddressInput:
      type: object
      description: Address data for creating a new location
      required:
        - line1
        - city
        - country
      properties:
        line1:
          type: string
          description: Primary street address line
          example: 123 Main St
        line2:
          type: string
          description: Secondary address line (suite, floor, etc.)
          example: Suite 400
        city:
          type: string
          description: City name
          example: Chicago
        state:
          type: string
          description: State or province code
          example: IL
        zipCode:
          type: string
          description: Postal / ZIP code
          example: '60601'
        country:
          type: string
          description: Country name or code
          example: USA
        market:
          type: string
          description: Market or region identifier
          example: CHI
        latitude:
          type: string
          description: Latitude coordinate
          example: '41.8781'
        longitude:
          type: string
          description: Longitude coordinate
          example: '-87.6298'
        isAirportOrAirbase:
          type: boolean
          default: false
          description: Whether this location is an airport or airbase
          example: false
        isConstructionOrUtilitySite:
          type: boolean
          default: false
          description: Whether this location is a construction or utility site
          example: false
        isSmartyValidated:
          type: boolean
          default: false
          description: Whether address has been validated by SmartyStreets
          example: true
        obeysDst:
          type: boolean
          default: true
          description: Whether this location observes daylight saving time
          example: true
        cityId:
          type: string
          format: uuid
          description: Reference to standardized city record (internal use)
    AddressPatch:
      type: object
      description: |
        Partial address update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Treated as omitted (null-clears are not yet
          supported for address fields)
      properties:
        line1:
          type: string
          description: Primary street address line
          example: 123 Main St
        line2:
          type: string
          description: Secondary address line
          example: Suite 400
          nullable: true
        city:
          type: string
          description: City name
          example: Chicago
        state:
          type: string
          description: State or province code
          example: IL
        zipCode:
          type: string
          description: Postal / ZIP code
          example: '60601'
        country:
          type: string
          description: Country name or code
          example: USA
        market:
          type: string
          description: Market or region identifier
          example: CHI
        latitude:
          type: string
          description: Latitude coordinate
          example: '41.8781'
          nullable: true
        longitude:
          type: string
          description: Longitude coordinate
          example: '-87.6298'
          nullable: true
        isAirportOrAirbase:
          type: boolean
          description: Whether this location is an airport or airbase
          example: false
        isConstructionOrUtilitySite:
          type: boolean
          description: Whether this location is a construction or utility site
          example: false
        isSmartyValidated:
          type: boolean
          description: Whether address has been validated by SmartyStreets
          example: true
        obeysDst:
          type: boolean
          description: Whether this location observes daylight saving time
          example: true
        cityId:
          type: string
          format: uuid
          description: Reference to standardized city record
          example: null
          nullable: true
    ContactInfo:
      type: object
      description: |
        Contact information details (nested, without id).

        This is an embedded object representing a Contact record. The id is managed
        internally and not exposed in the API.
      required:
        - name
      properties:
        name:
          type: string
          description: Contact person's full name
          example: John Smith
        email:
          type: string
          format: email
          description: Email address
          example: john.smith@example.com
          nullable: true
        phoneNumber:
          type: string
          description: Phone number
          example: +1-555-0100
          nullable: true
        title:
          type: string
          description: Job title or position
          example: Operations Manager
          nullable: true
    ContactInfoInput:
      type: object
      description: Contact information for creating a new contact record
      required:
        - name
      properties:
        name:
          type: string
          description: Contact person's full name
          example: John Smith
        email:
          type: string
          format: email
          description: Email address
          example: john.smith@example.com
        phoneNumber:
          type: string
          description: Phone number
          example: +1-555-0100
        title:
          type: string
          description: Job title or position
          example: Operations Manager
    ContactInfoPatch:
      type: object
      description: |
        Partial contact information update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Contact person's full name
          example: John Smith
        email:
          type: string
          format: email
          description: Email address
          example: john.smith@example.com
          nullable: true
        phoneNumber:
          type: string
          description: Phone number
          example: +1-555-0100
          nullable: true
        title:
          type: string
          description: Job title or position
          example: Operations Manager
          nullable: true
    StringFilter:
      type: object
      description: Filter options for string fields
      properties:
        equalTo:
          type: string
          description: Exact match
        notEqualTo:
          type: string
          description: Not equal to
        in:
          type: array
          items:
            type: string
          description: Matches any value in the array
        notIn:
          type: array
          items:
            type: string
          description: Does not match any value in the array
        includes:
          type: string
          description: Contains substring (case-insensitive)
        notIncludes:
          type: string
          description: Does not contain substring (case-insensitive)
        startsWith:
          type: string
          description: Starts with prefix (case-insensitive)
        notStartsWith:
          type: string
          description: Does not start with prefix (case-insensitive)
        endsWith:
          type: string
          description: Ends with suffix (case-insensitive)
        notEndsWith:
          type: string
          description: Does not end with suffix (case-insensitive)
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    IntFilter:
      type: object
      description: Filter options for integer fields
      properties:
        equalTo:
          type: integer
          description: Exact match
        notEqualTo:
          type: integer
          description: Not equal to
        lessThan:
          type: integer
          description: Less than
        lessThanOrEqualTo:
          type: integer
          description: Less than or equal to
        greaterThan:
          type: integer
          description: Greater than
        greaterThanOrEqualTo:
          type: integer
          description: Greater than or equal to
        in:
          type: array
          items:
            type: integer
          description: Matches any value in the array
        notIn:
          type: array
          items:
            type: integer
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    FloatFilter:
      type: object
      description: Filter options for float/number fields
      properties:
        equalTo:
          type: number
          format: float
          description: Exact match
        notEqualTo:
          type: number
          format: float
          description: Not equal to
        lessThan:
          type: number
          format: float
          description: Less than
        lessThanOrEqualTo:
          type: number
          format: float
          description: Less than or equal to
        greaterThan:
          type: number
          format: float
          description: Greater than
        greaterThanOrEqualTo:
          type: number
          format: float
          description: Greater than or equal to
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    BooleanFilter:
      type: object
      description: Filter options for boolean fields
      properties:
        equalTo:
          type: boolean
          description: Exact match
        notEqualTo:
          type: boolean
          description: Not equal to
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    DatetimeFilter:
      type: object
      description: Filter options for datetime fields
      properties:
        equalTo:
          type: string
          format: date-time
          description: Exact match
        notEqualTo:
          type: string
          format: date-time
          description: Not equal to
        lessThan:
          type: string
          format: date-time
          description: Before this datetime
        lessThanOrEqualTo:
          type: string
          format: date-time
          description: On or before this datetime
        greaterThan:
          type: string
          format: date-time
          description: After this datetime
        greaterThanOrEqualTo:
          type: string
          format: date-time
          description: On or after this datetime
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    IDFilter:
      type: object
      description: Filter options for ID fields (limited operations - exact match only)
      properties:
        equalTo:
          type: string
          format: uuid
          description: Exact match
        in:
          type: array
          description: Matches any UUID in the array
          items:
            type: string
            format: uuid
    ClientKeyFilter:
      type: object
      description: Filter options for client key fields (limited operations - exact match only)
      properties:
        equalTo:
          type: string
          description: Exact match
        in:
          type: array
          description: Matches any value in the array
          items:
            type: string
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CompanyFilter:
      type: object
      description: Filter criteria for companies with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/CompanyFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/CompanyFilter'
        not:
          $ref: '#/components/schemas/CompanyFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        addressLine1:
          $ref: '#/components/schemas/StringFilter'
        addressLine2:
          $ref: '#/components/schemas/StringFilter'
        city:
          $ref: '#/components/schemas/StringFilter'
        country:
          $ref: '#/components/schemas/StringFilter'
        fax:
          $ref: '#/components/schemas/StringFilter'
        invoiceOnly:
          $ref: '#/components/schemas/BooleanFilter'
        invoiceVerbiage:
          $ref: '#/components/schemas/StringFilter'
        primaryContactName:
          $ref: '#/components/schemas/StringFilter'
        primaryContactEmail:
          $ref: '#/components/schemas/StringFilter'
        primaryContactPhone:
          $ref: '#/components/schemas/StringFilter'
        createdById:
          $ref: '#/components/schemas/UUIDFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    CompanyFilterRequest:
      type: object
      description: Request body for filtering companies
      properties:
        filter:
          $ref: '#/components/schemas/CompanyFilter'
          description: |
            Filter criteria (optional - omit to return all companies).

            Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - invoiceOnly:
                equalTo: false
            - name:
                includes: Inc
        pageSize: 50
    Company:
      type: object
      required:
        - id
        - name
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - COMPANY
          readOnly: true
          description: Object type identifier
          example: COMPANY
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique company identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Company legal name
          example: Acme Logistics Inc
        addressLine1:
          type: string
          description: Primary street address
          example: 123 Main St
          nullable: true
        addressLine2:
          type: string
          description: Secondary address line (suite, floor, etc.)
          example: Suite 400
          nullable: true
        city:
          type: string
          description: City name
          example: Chicago
          nullable: true
        country:
          type: string
          description: Country code or name
          example: USA
          nullable: true
        fax:
          type: string
          description: Fax number
          example: +1-555-0123
          nullable: true
        invoiceOnly:
          type: boolean
          description: Whether this company is used only for invoicing purposes
          example: false
          nullable: true
        invoiceVerbiage:
          type: string
          description: Custom text to include on invoices for this company
          example: Please remit payment within 30 days
          nullable: true
        primaryContactName:
          type: string
          description: Name of primary contact person
          example: John Smith
          nullable: true
        primaryContactEmail:
          type: string
          format: email
          description: Email address of primary contact
          example: john.smith@acmelogistics.com
          nullable: true
        primaryContactPhone:
          type: string
          description: Phone number of primary contact
          example: +1-555-0100
          nullable: true
        createdBy:
          readOnly: true
          description: User who created this company (full user details)
          $ref: '#/components/schemas/UserReference'
          nullable: true
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-COMPANY-ACME-001
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the company was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the company was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the company was soft deleted (null if active)
          example: null
          nullable: true
    CompanyInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Company legal name
          example: Acme Logistics Inc
        addressLine1:
          type: string
          description: Primary street address
          example: 123 Main St
        addressLine2:
          type: string
          description: Secondary address line (suite, floor, etc.)
          example: Suite 400
        city:
          type: string
          description: City name
          example: Chicago
        country:
          type: string
          description: Country code or name
          example: USA
        fax:
          type: string
          description: Fax number
          example: +1-555-0123
        invoiceOnly:
          type: boolean
          description: Whether this company is used only for invoicing purposes
          example: false
        invoiceVerbiage:
          type: string
          description: Custom text to include on invoices for this company
          example: Please remit payment within 30 days
        primaryContactName:
          type: string
          description: Name of primary contact person
          example: John Smith
        primaryContactEmail:
          type: string
          format: email
          description: Email address of primary contact
          example: john.smith@acmelogistics.com
        primaryContactPhone:
          type: string
          description: Phone number of primary contact
          example: +1-555-0100
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-COMPANY-ACME-001
    CompanyPatch:
      type: object
      description: |
        Partial company update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Company legal name
          example: Acme Logistics Inc
        addressLine1:
          type: string
          description: Primary street address
          example: 123 Main St
          nullable: true
        addressLine2:
          type: string
          description: Secondary address line
          example: Suite 400
          nullable: true
        city:
          type: string
          description: City name
          example: Chicago
          nullable: true
        country:
          type: string
          description: Country code or name
          example: USA
          nullable: true
        fax:
          type: string
          description: Fax number
          example: +1-555-0123
          nullable: true
        invoiceOnly:
          type: boolean
          description: Whether this company is used only for invoicing purposes
          example: false
          nullable: true
        invoiceVerbiage:
          type: string
          description: Custom text to include on invoices
          example: Please remit payment within 30 days
          nullable: true
        primaryContactName:
          type: string
          description: Name of primary contact person
          example: John Smith
          nullable: true
        primaryContactEmail:
          type: string
          format: email
          description: Email address of primary contact
          example: john.smith@acmelogistics.com
          nullable: true
        primaryContactPhone:
          type: string
          description: Phone number of primary contact
          example: +1-555-0100
          nullable: true
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-COMPANY-ACME-001
          nullable: true
    CarrierContactType:
      type: string
      description: Type of carrier contact role
      enum:
        - ACCOUNTING
        - AFTER_HOURS
        - CENSUS
        - CLAIMS
        - DISPATCH
        - DRIVER
        - EMERGENCY
        - MANAGER
        - OWNER
    CarrierContactTypeFilter:
      type: object
      description: Filter for contact type enum array field
      properties:
        includes:
          $ref: '#/components/schemas/CarrierContactType'
          description: Array contains this contact type
        notIncludes:
          $ref: '#/components/schemas/CarrierContactType'
          description: Array does not contain this contact type
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CarrierContactFilter:
      type: object
      description: Filter criteria for carrier contacts with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierContactFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierContactFilter'
        not:
          $ref: '#/components/schemas/CarrierContactFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        carrierId:
          $ref: '#/components/schemas/UUIDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        phoneNumber:
          $ref: '#/components/schemas/StringFilter'
        contactTypes:
          $ref: '#/components/schemas/CarrierContactTypeFilter'
        invitedUserId:
          $ref: '#/components/schemas/UUIDFilter'
        deletedById:
          $ref: '#/components/schemas/UUIDFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    CarrierContactFilterRequest:
      type: object
      description: Request body for filtering carrier contacts
      properties:
        filter:
          $ref: '#/components/schemas/CarrierContactFilter'
          description: |
            Filter criteria (optional - omit to return all contacts).

            Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - contactTypes:
                includes: DISPATCH
            - email:
                isNull: false
        pageSize: 50
    CarrierContact:
      type: object
      required:
        - id
        - carrier
        - name
        - contactInfo
        - createdAt
      properties:
        object:
          type: string
          enum:
            - CARRIER_CONTACT
          readOnly: true
          description: Object type identifier
          example: CARRIER_CONTACT
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique contact identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        carrier:
          $ref: '#/components/schemas/CarrierReference'
          description: Carrier this contact belongs to (full carrier details)
        name:
          type: string
          description: Contact person's name (denormalized from ContactInfo for convenience)
          example: Jane Dispatcher
        contactInfo:
          allOf:
            - $ref: '#/components/schemas/ContactInfo'
          description: Contact information details (email, phone, title) - nested from parent Contact record
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/CarrierContactType'
          description: Types/roles this contact serves
          example:
            - DISPATCH
            - AFTER_HOURS
          nullable: true
        invitedUser:
          readOnly: true
          description: User account invited/created for this contact (full user details)
          $ref: '#/components/schemas/UserReference'
          nullable: true
        deletedBy:
          readOnly: true
          description: User who deleted this contact (full user details)
          $ref: '#/components/schemas/UserReference'
          nullable: true
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CARRIER-CONTACT-001
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was created
          example: '2025-01-15T10:00:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was soft deleted (null if active)
          example: null
          nullable: true
    CarrierContactInput:
      type: object
      required:
        - carrierId
        - name
        - contactInfo
      properties:
        carrierId:
          type: string
          format: uuid
          description: Carrier this contact belongs to
          example: 550e8400-e29b-41d4-a716-446655440001
        name:
          type: string
          description: Contact person's name (should match contactInfo.name)
          example: Jane Dispatcher
        contactInfo:
          $ref: '#/components/schemas/ContactInfoInput'
          description: Contact information details (will create new Contact record)
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/CarrierContactType'
          description: Types/roles this contact serves
          example:
            - DISPATCH
            - AFTER_HOURS
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CARRIER-CONTACT-001
    CarrierContactPatch:
      type: object
      description: |
        Partial carrier contact update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable

        Note: carrierId cannot be updated after creation.
      properties:
        name:
          type: string
          description: Contact person's name (should match contactInfo.name if updating both)
          example: Jane Dispatcher
        contactInfo:
          description: |
            Contact information update. Provide partial or full contact data to update the parent Contact record.
            Cannot be set to null (contact info is required).
          $ref: '#/components/schemas/ContactInfoPatch'
          nullable: true
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/CarrierContactType'
          description: Types/roles this contact serves (replaces entire array)
          example:
            - DISPATCH
            - AFTER_HOURS
          nullable: true
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CARRIER-CONTACT-001
          nullable: true
    CustomerContactType:
      type: string
      description: Type of customer contact role
      enum:
        - ACCOUNT_MANAGER
        - BILLING
        - DOCK_SHIPPING
        - EMERGENCY
        - LOCATION_MANAGER
        - OWNER
        - PROCUREMENT
        - PURCHASING
        - RATES_PRICING
        - RECEIVING
        - SHIPPING
    CustomerContactNotificationType:
      type: string
      description: Types of shipment notifications the contact should receive
      enum:
        - SHIPMENT_DELIVERED
        - SHIPMENT_IN_TRANSIT
        - SHIPMENT_LOADING
        - SHIPMENT_OUT_FOR_DELIVERY
        - SHIPMENT_PICKED_UP
        - SHIPMENT_TENDER_REJECTED
        - SHIPMENT_UNLOADING
    CustomerContactTypeFilter:
      type: object
      description: Filter for contact type enum array field
      properties:
        includes:
          $ref: '#/components/schemas/CustomerContactType'
          description: Array contains this contact type
        notIncludes:
          $ref: '#/components/schemas/CustomerContactType'
          description: Array does not contain this contact type
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerContactNotificationTypeFilter:
      type: object
      description: Filter for notification type enum array field
      properties:
        includes:
          $ref: '#/components/schemas/CustomerContactNotificationType'
          description: Array contains this notification type
        notIncludes:
          $ref: '#/components/schemas/CustomerContactNotificationType'
          description: Array does not contain this notification type
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerContactFilter:
      type: object
      description: Filter criteria for contacts with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/CustomerContactFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/CustomerContactFilter'
        not:
          $ref: '#/components/schemas/CustomerContactFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        customerId:
          $ref: '#/components/schemas/UUIDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        phoneNumber:
          $ref: '#/components/schemas/StringFilter'
        phoneExtension:
          $ref: '#/components/schemas/StringFilter'
        isPrimary:
          $ref: '#/components/schemas/BooleanFilter'
        contactTypes:
          $ref: '#/components/schemas/CustomerContactTypeFilter'
        notifications:
          $ref: '#/components/schemas/CustomerContactNotificationTypeFilter'
        invitedUserId:
          $ref: '#/components/schemas/UUIDFilter'
        deletedById:
          $ref: '#/components/schemas/UUIDFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    CustomerContactFilterRequest:
      type: object
      description: Request body for filtering contacts
      properties:
        filter:
          $ref: '#/components/schemas/CustomerContactFilter'
          description: |
            Filter criteria (optional - omit to return all contacts).

            Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - isPrimary:
                equalTo: true
            - contactTypes:
                includes: BILLING
        pageSize: 50
    CustomerContact:
      type: object
      required:
        - id
        - customer
        - name
        - isPrimary
        - contactInfo
        - createdAt
      properties:
        object:
          type: string
          enum:
            - CUSTOMER_CONTACT
          readOnly: true
          description: Object type identifier
          example: CUSTOMER_CONTACT
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique contact identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        customer:
          $ref: '#/components/schemas/CustomerReference'
          description: Customer this contact belongs to (full customer details)
        name:
          type: string
          description: Contact person's name (denormalized from ContactInfo for convenience)
          example: John Smith
        contactInfo:
          allOf:
            - $ref: '#/components/schemas/ContactInfo'
          description: Contact information details (email, phone, title) - nested from parent Contact record
        phoneExtension:
          type: string
          description: Phone extension specific to this contact role
          example: '1234'
          nullable: true
        isPrimary:
          type: boolean
          description: Whether this is the primary contact for the customer
          example: true
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/CustomerContactType'
          description: Types/roles this contact serves
          example:
            - BILLING
            - ACCOUNT_MANAGER
          nullable: true
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/CustomerContactNotificationType'
          description: Shipment notification types to send to this contact
          example:
            - SHIPMENT_PICKED_UP
            - SHIPMENT_DELIVERED
          nullable: true
        invitedUser:
          readOnly: true
          description: User account invited/created for this contact (full user details)
          $ref: '#/components/schemas/UserReference'
          nullable: true
        deletedBy:
          readOnly: true
          description: User who deleted this contact (full user details)
          $ref: '#/components/schemas/UserReference'
          nullable: true
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CONTACT-JOHN-001
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was created
          example: '2025-01-15T10:00:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was soft deleted (null if active)
          example: null
          nullable: true
    CustomerContactInput:
      type: object
      required:
        - customerId
        - name
        - contactInfo
      properties:
        customerId:
          type: string
          format: uuid
          description: Customer this contact belongs to
          example: 550e8400-e29b-41d4-a716-446655440001
        name:
          type: string
          description: Contact person's name (should match contactInfo.name)
          example: John Smith
        contactInfo:
          $ref: '#/components/schemas/ContactInfoInput'
          description: Contact information details (will create new Contact record)
        phoneExtension:
          type: string
          description: Phone extension specific to this contact role
          example: '1234'
        isPrimary:
          type: boolean
          default: false
          description: Whether this is the primary contact for the customer
          example: true
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/CustomerContactType'
          description: Types/roles this contact serves
          example:
            - BILLING
            - ACCOUNT_MANAGER
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/CustomerContactNotificationType'
          description: Shipment notification types to send to this contact
          example:
            - SHIPMENT_PICKED_UP
            - SHIPMENT_DELIVERED
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CONTACT-JOHN-001
    CustomerContactPatch:
      type: object
      description: |
        Partial contact update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable

        Note: customerId cannot be updated after creation.
      properties:
        name:
          type: string
          description: Contact person's name (should match contactInfo.name if updating both)
          example: John Smith
        contactInfo:
          description: |
            Contact information update. Provide partial or full contact data to update the parent Contact record.
            Cannot be set to null (contact info is required).
          $ref: '#/components/schemas/ContactInfoPatch'
          nullable: true
        phoneExtension:
          type: string
          description: Phone extension
          example: '1234'
          nullable: true
        isPrimary:
          type: boolean
          description: Whether this is the primary contact
          example: true
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/CustomerContactType'
          description: Types/roles this contact serves (replaces entire array)
          example:
            - BILLING
            - ACCOUNT_MANAGER
          nullable: true
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/CustomerContactNotificationType'
          description: Notification types (replaces entire array)
          example:
            - SHIPMENT_PICKED_UP
            - SHIPMENT_DELIVERED
          nullable: true
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CONTACT-JOHN-001
          nullable: true
    CustomerStatus:
      type: string
      enum:
        - NEW
        - CONTACTED
        - QUALIFIED
        - QUOTED
        - NURTURING
        - PENDING
        - ACTIVE
        - INACTIVE
        - BLOCKED
        - CLOSED
      description: |
        Customer account status (includes lead stages):
        - `NEW`: New lead, not yet contacted
        - `CONTACTED`: Initial contact made with lead
        - `QUALIFIED`: Lead has been qualified as potential customer
        - `QUOTED`: Quote has been provided to lead
        - `NURTURING`: Lead being nurtured for future opportunity
        - `PENDING`: Customer prospect pending activation
        - `ACTIVE`: Active customer account
        - `INACTIVE`: Deactivated customer account
        - `BLOCKED`: Customer account blocked from operations
        - `CLOSED`: Customer account permanently closed
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: 'Customer account status (includes lead stages):'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 11
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: NEW
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': New lead, not yet contacted'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: CONTACTED
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Initial contact made with lead'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: QUALIFIED
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': Lead has been qualified as potential customer'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 4
                  - 5
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 4
                      - 5
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 4
                          - 5
                        inline: true
                        attributes:
                          content: QUOTED
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 4
                          - 5
                        inline: true
                        attributes:
                          content: ': Quote has been provided to lead'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 5
                  - 6
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 5
                      - 6
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 5
                          - 6
                        inline: true
                        attributes:
                          content: NURTURING
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 5
                          - 6
                        inline: true
                        attributes:
                          content: ': Lead being nurtured for future opportunity'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 6
                  - 7
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 6
                      - 7
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 6
                          - 7
                        inline: true
                        attributes:
                          content: PENDING
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 6
                          - 7
                        inline: true
                        attributes:
                          content: ': Customer prospect pending activation'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 7
                  - 8
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 7
                      - 8
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 7
                          - 8
                        inline: true
                        attributes:
                          content: ACTIVE
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 7
                          - 8
                        inline: true
                        attributes:
                          content: ': Active customer account'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 8
                  - 9
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 8
                      - 9
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 8
                          - 9
                        inline: true
                        attributes:
                          content: INACTIVE
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 8
                          - 9
                        inline: true
                        attributes:
                          content: ': Deactivated customer account'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 9
                  - 10
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 9
                      - 10
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 9
                          - 10
                        inline: true
                        attributes:
                          content: BLOCKED
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 9
                          - 10
                        inline: true
                        attributes:
                          content: ': Customer account blocked from operations'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 10
                  - 11
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 10
                      - 11
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 10
                          - 11
                        inline: true
                        attributes:
                          content: CLOSED
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 10
                          - 11
                        inline: true
                        attributes:
                          content: ': Customer account permanently closed'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    CustomerServiceTier:
      type: string
      enum:
        - TIER_1
        - TIER_2
        - TIER_3
      description: Service tier level for the customer
    CustomerSpendType:
      type: string
      enum:
        - CONTRACT
        - SPOT
      description: |
        Customer spend type:
        - `CONTRACT`: Customer operates under contract pricing
        - `SPOT`: Customer operates on spot market pricing
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: 'Customer spend type:'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 3
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: CONTRACT
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': Customer operates under contract pricing'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: SPOT
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Customer operates on spot market pricing'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    CustomerDeactivationReason:
      type: string
      enum:
        - NOT_PAYING_INVOICE
        - ACQUIRED
        - DUPLICATE
        - NOT_IN_BUSINESS
        - OTHER
      description: |
        Reason for customer deactivation:
        - `NOT_PAYING_INVOICE`: Customer is not paying invoices
        - `ACQUIRED`: Customer was acquired by another company
        - `DUPLICATE`: Duplicate customer record
        - `NOT_IN_BUSINESS`: Customer is no longer in business
        - `OTHER`: Other reason (see deactivationNotes for details)
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: 'Reason for customer deactivation:'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 6
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: NOT_PAYING_INVOICE
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': Customer is not paying invoices'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ACQUIRED
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Customer was acquired by another company'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: DUPLICATE
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': Duplicate customer record'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 4
                  - 5
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 4
                      - 5
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 4
                          - 5
                        inline: true
                        attributes:
                          content: NOT_IN_BUSINESS
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 4
                          - 5
                        inline: true
                        attributes:
                          content: ': Customer is no longer in business'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 5
                  - 6
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 5
                      - 6
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 5
                          - 6
                        inline: true
                        attributes:
                          content: OTHER
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 5
                          - 6
                        inline: true
                        attributes:
                          content: ': Other reason (see deactivationNotes for details)'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    CustomerIndustry:
      type: string
      enum:
        - AGRICULTURE_FORESTRY
        - CONSTRUCTION
        - CONSUMER_GOODS
        - EDUCATIONAL_SERVICES
        - ENTERTAINMENT
        - FOOD_SERVICES
        - HEALTHCARE
        - INDUSTRIAL_MACHINERY
        - MANUFACTURING
        - MINING
        - RETAIL_TRADE
        - TRANSPORTATION_WAREHOUSING
        - UTILITIES
        - WHOLESALE_TRADE
      description: Industry classification for the customer
    CustomerAnnualSpend:
      type: string
      enum:
        - _0_TO_25K
        - _25_TO_150K
        - _150K_TO_300K
        - _300K_TO_1M
        - _1_TO_5M
        - _5M_TO_25M
        - _25M_TO_75M
        - _75M_PLUS
      description: Annual freight spend estimate range
    CustomerAnnualRevenue:
      type: string
      enum:
        - _0_TO_500K
        - _500K_TO_3M
        - _3M_TO_10M
        - _10M_TO_25M
        - _25M_TO_50M
        - _50M_TO_100M
        - _100M_TO_500M
        - _500M_PLUS
      description: Annual revenue range
    CustomerNumberOfEmployees:
      type: string
      enum:
        - _0_TO_1
        - _2_TO_5
        - _6_TO_9
        - _10_TO_24
        - _25_TO_99
        - _100_TO_249
        - _250_TO_499
        - _500_OR_MORE
      description: Number of employees in the company
    CustomerCurrency:
      type: string
      enum:
        - USD
        - CAD
        - MXN
        - EUR
        - GBP
        - JPY
        - CNY
        - AUD
        - BRL
        - INR
        - KRW
        - RUB
        - SAR
        - TRY
        - IDR
        - ARS
        - ZAR
      description: Preferred currency for transactions
    CustomerTransportationMode:
      type: string
      enum:
        - FTL
        - LTL
        - AIR
        - OCEAN
        - RAIL
        - INTERMODAL
        - DRAYAGE
        - EXPEDITED_GROUND
        - EXPEDITED_AIR
        - AUTO
        - PTL
        - RLTL
      description: Transportation mode type
    CustomerStatusFilter:
      type: object
      description: Filter options for CustomerStatus enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerStatus'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerStatus'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerStatus'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerStatus'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerServiceTierFilter:
      type: object
      description: Filter options for CustomerServiceTier enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerServiceTier'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerServiceTier'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerServiceTier'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerServiceTier'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerSpendTypeFilter:
      type: object
      description: Filter options for CustomerSpendType enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerSpendType'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerSpendType'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerSpendType'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerSpendType'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerDeactivationReasonFilter:
      type: object
      description: Filter options for CustomerDeactivationReason enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerDeactivationReason'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerDeactivationReason'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerDeactivationReason'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerDeactivationReason'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerIndustryFilter:
      type: object
      description: Filter options for CustomerIndustry enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerIndustry'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerIndustry'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerIndustry'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerIndustry'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerAnnualSpendFilter:
      type: object
      description: Filter options for CustomerAnnualSpend enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerAnnualSpend'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerAnnualSpend'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerAnnualSpend'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerAnnualSpend'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerAnnualRevenueFilter:
      type: object
      description: Filter options for CustomerAnnualRevenue enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerAnnualRevenue'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerAnnualRevenue'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerAnnualRevenue'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerAnnualRevenue'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerNumberOfEmployeesFilter:
      type: object
      description: Filter options for CustomerNumberOfEmployees enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerNumberOfEmployees'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerNumberOfEmployees'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerNumberOfEmployees'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerNumberOfEmployees'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerCurrencyFilter:
      type: object
      description: Filter options for CustomerCurrency enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerCurrency'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerCurrency'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerCurrency'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerCurrency'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerTransportationModeFilter:
      type: object
      description: Filter options for CustomerTransportationMode enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerTransportationMode'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerTransportationMode'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerTransportationMode'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerTransportationMode'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerFilter:
      type: object
      description: Filter criteria for customers with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/CustomerFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/CustomerFilter'
        not:
          $ref: '#/components/schemas/CustomerFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        friendlyId:
          $ref: '#/components/schemas/StringFilter'
        status:
          $ref: '#/components/schemas/CustomerStatusFilter'
        serviceTier:
          $ref: '#/components/schemas/CustomerServiceTierFilter'
        website:
          $ref: '#/components/schemas/StringFilter'
        phoneNumber:
          $ref: '#/components/schemas/StringFilter'
        industry:
          $ref: '#/components/schemas/CustomerIndustryFilter'
        annualRevenue:
          $ref: '#/components/schemas/CustomerAnnualRevenueFilter'
        annualSpend:
          $ref: '#/components/schemas/CustomerAnnualSpendFilter'
        spendType:
          $ref: '#/components/schemas/CustomerSpendTypeFilter'
        naics:
          $ref: '#/components/schemas/StringFilter'
        ein:
          $ref: '#/components/schemas/StringFilter'
        duns:
          $ref: '#/components/schemas/StringFilter'
        leadSource:
          $ref: '#/components/schemas/StringFilter'
        deactivationReason:
          $ref: '#/components/schemas/CustomerDeactivationReasonFilter'
        numberOfEmployees:
          $ref: '#/components/schemas/CustomerNumberOfEmployeesFilter'
        currency:
          $ref: '#/components/schemas/CustomerCurrencyFilter'
        defaultMode:
          $ref: '#/components/schemas/CustomerTransportationModeFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        closedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deactivationDate:
          $ref: '#/components/schemas/DatetimeFilter'
    CustomerFilterRequest:
      type: object
      description: Request body for filtering customers
      properties:
        filter:
          $ref: '#/components/schemas/CustomerFilter'
          description: |
            Filter criteria (optional - omit to return all customers).
            Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: Filter criteria (optional - omit to return all customers).
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes: {}
                        children: []
                        type: softbreak
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: 'Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - status:
                equalTo: ACTIVE
            - industry:
                equalTo: MANUFACTURING
        pageSize: 50
    Customer:
      type: object
      required:
        - id
        - name
        - status
        - friendlyId
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - CUSTOMER
          readOnly: true
          description: Object type identifier
          example: CUSTOMER
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique customer identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Customer company name
          example: Acme Manufacturing Corp
        friendlyId:
          type: string
          readOnly: true
          description: Human-readable customer identifier, starts with "A"
          example: A123456
        status:
          $ref: '#/components/schemas/CustomerStatus'
        serviceTier:
          description: Service tier level
          $ref: '#/components/schemas/CustomerServiceTier'
          nullable: true
        website:
          type: string
          description: Customer website URL
          example: https://acme-manufacturing.com
          nullable: true
        phoneNumber:
          type: string
          description: Primary phone number
          example: +1-555-123-4567
          nullable: true
        industry:
          description: Industry classification
          $ref: '#/components/schemas/CustomerIndustry'
          nullable: true
        annualRevenue:
          description: Annual revenue range
          $ref: '#/components/schemas/CustomerAnnualRevenue'
          nullable: true
        annualSpend:
          description: Annual freight spend estimate
          $ref: '#/components/schemas/CustomerAnnualSpend'
          nullable: true
        spendType:
          description: Customer spend type (contract vs spot pricing)
          $ref: '#/components/schemas/CustomerSpendType'
          nullable: true
        naics:
          type: string
          description: NAICS industry code
          example: '336411'
          nullable: true
        ein:
          type: string
          description: Employer Identification Number
          example: 12-3456789
          nullable: true
        duns:
          type: string
          description: Dun & Bradstreet number
          example: '123456789'
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 1
                        inline: true
                        attributes:
                          content: Dun & Bradstreet number
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
          nullable: true
        leadSource:
          type: string
          description: How this customer was acquired
          example: Referral
          nullable: true
        dbaName:
          type: string
          description: Doing business as name
          example: Acme Corp DBA
          nullable: true
        numberOfEmployees:
          description: Company size by number of employees
          $ref: '#/components/schemas/CustomerNumberOfEmployees'
          nullable: true
        externalId:
          type: string
          description: External system identifier
          example: EXT-12345
          nullable: true
        currency:
          description: Preferred currency for transactions
          $ref: '#/components/schemas/CustomerCurrency'
          nullable: true
        creditLimit:
          type: number
          format: float
          description: Maximum credit allowed
          example: 50000
          nullable: true
        creditUsageWarning:
          type: number
          format: float
          description: Credit usage warning threshold
          example: 40000
          nullable: true
        freeCreditReq:
          type: number
          format: float
          description: Free credit requirement
          example: 5000
          nullable: true
        defaultMode:
          description: |
            Default transportation mode. Values outside the enum are rejected
            with 400; customers whose internal mode isn't in the public enum
            return the field omitted.
          $ref: '#/components/schemas/CustomerTransportationMode'
          nullable: true
        defaultMargin:
          type: number
          format: float
          description: Default margin percentage (0-1, e.g., 0.15 for 15%)
          example: 0.15
          nullable: true
        minMargin:
          type: number
          format: float
          description: Minimum margin threshold
          example: 0.1
          nullable: true
        maxMargin:
          type: number
          format: float
          description: Maximum margin threshold
          example: 0.25
          nullable: true
        defaultInternalNotes:
          type: string
          description: Default internal notes template
          example: Contact via email only
          nullable: true
        defaultCarrierNotes:
          type: string
          description: Default carrier-facing notes template used when note splitting is enabled
          example: Call pickup contact before arrival
          nullable: true
        defaultExternalNotes:
          type: string
          description: Default external notes template
          example: Please call 1 hour before delivery
          nullable: true
        defaultShowNotes:
          description: Controls whether default external notes are reused on carrier docs or split from default carrier notes
          $ref: '#/components/schemas/ShowNotes'
          nullable: true
        autoAcceptTender:
          type: boolean
          description: Auto-accept tender flag
          example: false
          nullable: true
        group:
          description: Customer group reference (minimal - id and key only)
          $ref: '#/components/schemas/ResourceReference'
          nullable: true
        paymentTerm:
          description: Payment term configuration reference with full details
          $ref: '#/components/schemas/PaymentTermReference'
          nullable: true
        notes:
          type: string
          description: Internal notes about this customer
          example: Prefers email communication
          nullable: true
        deactivationReason:
          description: Reason for deactivation if status is INACTIVE
          $ref: '#/components/schemas/CustomerDeactivationReason'
          nullable: true
        deactivationNotes:
          type: string
          description: Additional details about deactivation
          nullable: true
        deactivationDate:
          type: string
          format: date-time
          description: When the customer was deactivated
          example: null
          nullable: true
        closedAt:
          type: string
          format: date-time
          description: When the customer account was closed
          example: null
          nullable: true
        closedBy:
          readOnly: true
          description: User who closed the account (full user details)
          $ref: '#/components/schemas/UserReference'
          nullable: true
        closedNotes:
          type: string
          description: Notes about account closure
          nullable: true
        corporateAddress:
          description: Corporate headquarters address (nested location data)
          $ref: '#/components/schemas/Address'
          nullable: true
        billingAddress:
          description: Billing address (nested location data)
          $ref: '#/components/schemas/Address'
          nullable: true
        qboCustomerId:
          type: string
          description: QuickBooks Online customer ID
          example: null
          nullable: true
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier for this customer
          example: ERP-CUSTOMER-12345
          nullable: true
        contacts:
          type: array
          description: Contacts for this customer
          items:
            $ref: '#/components/schemas/CustomerContactReference'
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when customer was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when customer was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when customer was soft-deleted (null if active)
          example: null
          nullable: true
        deletedBy:
          readOnly: true
          description: User who deleted the customer (full user details)
          $ref: '#/components/schemas/UserReference'
          nullable: true
    CustomerInput:
      type: object
      required:
        - name
        - status
      properties:
        name:
          type: string
          description: Customer company name (required)
          example: Acme Manufacturing Corp
        status:
          $ref: '#/components/schemas/CustomerStatus'
        serviceTier:
          $ref: '#/components/schemas/CustomerServiceTier'
        website:
          type: string
          description: Customer website URL
          example: https://acme-manufacturing.com
        phoneNumber:
          type: string
          description: Primary phone number
          example: +1-555-123-4567
        industry:
          $ref: '#/components/schemas/CustomerIndustry'
        annualRevenue:
          $ref: '#/components/schemas/CustomerAnnualRevenue'
        annualSpend:
          $ref: '#/components/schemas/CustomerAnnualSpend'
        spendType:
          $ref: '#/components/schemas/CustomerSpendType'
        naics:
          type: string
          description: NAICS industry code
          example: '336411'
        ein:
          type: string
          description: Employer Identification Number
          example: 12-3456789
        duns:
          type: string
          description: Dun & Bradstreet number
          example: '123456789'
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 1
                        inline: true
                        attributes:
                          content: Dun & Bradstreet number
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        leadSource:
          type: string
          description: How this customer was acquired
          example: Referral
        dbaName:
          type: string
          description: Doing business as name
          example: Acme Corp DBA
        numberOfEmployees:
          $ref: '#/components/schemas/CustomerNumberOfEmployees'
        externalId:
          type: string
          description: External system identifier
          example: EXT-12345
        currency:
          $ref: '#/components/schemas/CustomerCurrency'
        creditLimit:
          type: number
          format: float
          description: Maximum credit allowed
          example: 50000
        creditUsageWarning:
          type: number
          format: float
          description: Credit usage warning threshold
          example: 40000
        freeCreditReq:
          type: number
          format: float
          description: Free credit requirement
          example: 5000
        defaultMode:
          $ref: '#/components/schemas/CustomerTransportationMode'
        defaultMargin:
          type: number
          format: float
          description: Default margin percentage (0-1, e.g., 0.15 for 15%)
          example: 0.15
        minMargin:
          type: number
          format: float
          description: Minimum margin threshold
          example: 0.1
        maxMargin:
          type: number
          format: float
          description: Maximum margin threshold
          example: 0.25
        defaultInternalNotes:
          type: string
          description: Default internal notes template
          example: Contact via email only
        defaultCarrierNotes:
          type: string
          description: Default carrier-facing notes template used when note splitting is enabled
          example: Call pickup contact before arrival
        defaultExternalNotes:
          type: string
          description: Default external notes template
          example: Please call 1 hour before delivery
        defaultShowNotes:
          $ref: '#/components/schemas/ShowNotes'
        autoAcceptTender:
          type: boolean
          description: Auto-accept tender flag
          example: false
        groupId:
          type: string
          format: uuid
          description: Customer group reference
        paymentTerm:
          $ref: '#/components/schemas/ResourceReferenceInput'
        notes:
          type: string
          description: Internal notes about this customer
          example: Prefers email communication
        deactivationReason:
          $ref: '#/components/schemas/CustomerDeactivationReason'
        deactivationNotes:
          type: string
          description: Additional details about deactivation
        deactivationDate:
          type: string
          format: date-time
          description: When the customer was deactivated
        corporateAddress:
          $ref: '#/components/schemas/AddressInput'
          description: Corporate headquarters address (will create new location record)
        billingAddress:
          $ref: '#/components/schemas/AddressInput'
          description: Billing address (will create new location record)
        qboCustomerId:
          type: string
          description: QuickBooks Online customer ID
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CUSTOMER-12345
    CustomerPatch:
      type: object
      description: |
        Partial customer update. All fields are optional.
        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Customer company name
          example: Acme Manufacturing Corp
        status:
          $ref: '#/components/schemas/CustomerStatus'
        serviceTier:
          description: Service tier level
          $ref: '#/components/schemas/CustomerServiceTier'
          nullable: true
        website:
          type: string
          description: Customer website URL
          example: https://acme-manufacturing.com
          nullable: true
        phoneNumber:
          type: string
          description: Primary phone number
          example: +1-555-123-4567
          nullable: true
        industry:
          description: Industry classification
          $ref: '#/components/schemas/CustomerIndustry'
          nullable: true
        annualRevenue:
          description: Annual revenue range
          $ref: '#/components/schemas/CustomerAnnualRevenue'
          nullable: true
        annualSpend:
          description: Annual freight spend estimate
          $ref: '#/components/schemas/CustomerAnnualSpend'
          nullable: true
        spendType:
          description: Customer spend type (contract vs spot pricing)
          $ref: '#/components/schemas/CustomerSpendType'
          nullable: true
        naics:
          type: string
          description: NAICS industry code
          example: '336411'
          nullable: true
        ein:
          type: string
          description: Employer Identification Number
          example: 12-3456789
          nullable: true
        duns:
          type: string
          description: Dun & Bradstreet number
          example: '123456789'
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 1
                        inline: true
                        attributes:
                          content: Dun & Bradstreet number
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
          nullable: true
        leadSource:
          type: string
          description: How this customer was acquired
          example: Referral
          nullable: true
        dbaName:
          type: string
          description: Doing business as name
          example: Acme Corp DBA
          nullable: true
        numberOfEmployees:
          description: Company size by number of employees
          $ref: '#/components/schemas/CustomerNumberOfEmployees'
          nullable: true
        externalId:
          type: string
          description: External system identifier
          example: EXT-12345
          nullable: true
        currency:
          description: Preferred currency for transactions
          $ref: '#/components/schemas/CustomerCurrency'
          nullable: true
        creditLimit:
          type: number
          format: float
          description: Maximum credit allowed
          example: 50000
          nullable: true
        creditUsageWarning:
          type: number
          format: float
          description: Credit usage warning threshold
          example: 40000
          nullable: true
        freeCreditReq:
          type: number
          format: float
          description: Free credit requirement
          example: 5000
          nullable: true
        defaultMode:
          description: |
            Default transportation mode. Values outside the enum are rejected
            with 400; customers whose internal mode isn't in the public enum
            return the field omitted.
          $ref: '#/components/schemas/CustomerTransportationMode'
          nullable: true
        defaultMargin:
          type: number
          format: float
          description: Default margin percentage (0-1, e.g., 0.15 for 15%)
          example: 0.15
          nullable: true
        minMargin:
          type: number
          format: float
          description: Minimum margin threshold
          example: 0.1
          nullable: true
        maxMargin:
          type: number
          format: float
          description: Maximum margin threshold
          example: 0.25
          nullable: true
        defaultInternalNotes:
          type: string
          description: Default internal notes template
          example: Contact via email only
          nullable: true
        defaultCarrierNotes:
          type: string
          description: Default carrier-facing notes template used when note splitting is enabled
          example: Call pickup contact before arrival
          nullable: true
        defaultExternalNotes:
          type: string
          description: Default external notes template
          example: Please call 1 hour before delivery
          nullable: true
        defaultShowNotes:
          description: Controls whether default external notes are reused on carrier docs or split from default carrier notes
          $ref: '#/components/schemas/ShowNotes'
          nullable: true
        autoAcceptTender:
          type: boolean
          description: Auto-accept tender flag
          example: false
          nullable: true
        groupId:
          type: string
          format: uuid
          description: Customer group reference
          example: null
          nullable: true
        paymentTerm:
          description: Payment term configuration reference
          $ref: '#/components/schemas/ResourceReferenceInput'
          nullable: true
        notes:
          type: string
          description: Internal notes
          example: Prefers email communication
          nullable: true
        deactivationReason:
          description: Reason for deactivation
          $ref: '#/components/schemas/CustomerDeactivationReason'
          nullable: true
        deactivationNotes:
          type: string
          description: Additional deactivation details
          nullable: true
        deactivationDate:
          type: string
          format: date-time
          description: Deactivation date
          nullable: true
        corporateAddress:
          description: |
            Corporate address update. Provide partial or full address data to update the existing location.
            Set to null to clear the address reference.
          $ref: '#/components/schemas/AddressPatch'
          nullable: true
        billingAddress:
          description: |
            Billing address update. Provide partial or full address data to update the existing location.
            Set to null to clear the address reference.
          $ref: '#/components/schemas/AddressPatch'
          nullable: true
        qboCustomerId:
          type: string
          description: QuickBooks Online customer ID
          nullable: true
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CUSTOMER-12345
          nullable: true
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: Partial customer update. All fields are optional.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 4
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 1
                              - 2
                            inline: true
                            attributes:
                              content: Omitted fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': Not modified (current value preserved)'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 2
                              - 3
                            inline: true
                            attributes:
                              content: Provided fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Updated to the new value'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 3
                              - 4
                            inline: true
                            attributes:
                              content: Null values
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': Clear the field (set to null) where applicable'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    LocationType:
      type: string
      enum:
        - SHIPPER
        - RECEIVER
        - BOTH
      description: |
        The type of location:
        - `SHIPPER`: Pickup location only
        - `RECEIVER`: Delivery location only
        - `BOTH`: Can be used for both pickup and delivery
    LocationFilter:
      type: object
      description: Filter criteria for locations with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/LocationFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/LocationFilter'
        not:
          $ref: '#/components/schemas/LocationFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        customerId:
          $ref: '#/components/schemas/IDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        type:
          $ref: '#/components/schemas/StringFilter'
        isAppointmentRequired:
          $ref: '#/components/schemas/BooleanFilter'
        notes:
          $ref: '#/components/schemas/StringFilter'
        internalNotes:
          $ref: '#/components/schemas/StringFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    LocationFilterRequest:
      type: object
      description: Request body for filtering locations
      properties:
        filter:
          $ref: '#/components/schemas/LocationFilter'
          description: |
            Filter criteria (optional - omit to return all locations).

            Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - customerId:
                equalTo: 550e8400-e29b-41d4-a716-446655440000
            - type:
                equalTo: SHIPPER
        pageSize: 50
    Location:
      type: object
      required:
        - id
        - customerId
        - name
        - isAppointmentRequired
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - LOCATION
          readOnly: true
          description: Object type identifier
          example: LOCATION
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique location identifier
          example: 770e8400-e29b-41d4-a716-446655440000
        customerId:
          type: string
          format: uuid
          description: Customer (shipper profile) this location belongs to
          example: 550e8400-e29b-41d4-a716-446655440000
        customer:
          $ref: '#/components/schemas/Customer'
          readOnly: true
          description: The customer this location belongs to
        address:
          $ref: '#/components/schemas/Address'
          readOnly: true
          description: Physical address of this location
        name:
          type: string
          description: Location name
          example: ABC Warehouse - Dallas
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier for this location
          example: ERP-LOC-DALLAS-01
          nullable: true
        type:
          $ref: '#/components/schemas/LocationType'
          description: Type of location (SHIPPER, RECEIVER, or BOTH)
          example: SHIPPER
        isAppointmentRequired:
          type: boolean
          description: Whether appointments are required for this location
          example: true
        notes:
          type: string
          description: External notes visible to carriers
          example: Call 24 hours ahead for appointment
          nullable: true
        internalNotes:
          type: string
          description: Internal notes (not visible to carriers)
          example: Use dock door 5 for expedited shipments
          nullable: true
        contacts:
          type: array
          description: Contacts for this location
          items:
            $ref: '#/components/schemas/LocationContactReference'
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when location was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when location was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when location was soft-deleted (null if active)
          example: null
          nullable: true
    LocationInput:
      type: object
      required:
        - customerId
        - address
        - name
        - isAppointmentRequired
      properties:
        customerId:
          type: string
          format: uuid
          description: Customer (shipper profile) this location belongs to (required)
          example: 550e8400-e29b-41d4-a716-446655440000
        address:
          $ref: '#/components/schemas/LocationAddressInput'
          description: |
            Physical address for this location (required). The backing address
            record is created and linked automatically — no separate address or
            location id is needed. `country` accepts US, CA, or MX.
        name:
          type: string
          description: Location name (required)
          example: ABC Warehouse - Dallas
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-LOC-DALLAS-01
        type:
          $ref: '#/components/schemas/LocationType'
          description: Type of location (SHIPPER, RECEIVER, or BOTH)
          example: SHIPPER
        isAppointmentRequired:
          type: boolean
          description: Whether appointments are required for this location (required)
          example: true
        notes:
          type: string
          description: External notes visible to carriers
          example: Call 24 hours ahead for appointment
        internalNotes:
          type: string
          description: Internal notes (not visible to carriers)
          example: Use dock door 5 for expedited shipments
    LocationPatch:
      type: object
      description: |
        Partial location update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        customerId:
          type: string
          format: uuid
          description: Customer (shipper profile) this location belongs to
          example: 550e8400-e29b-41d4-a716-446655440000
        address:
          $ref: '#/components/schemas/AddressPatch'
          description: |
            Partial update of the location's physical address. Provided fields
            update the backing address record in place. Null values are treated
            as omitted for address fields (null-clears are not yet supported).
        name:
          type: string
          description: Location name
          example: ABC Warehouse - Dallas
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-LOC-DALLAS-01
          nullable: true
        type:
          $ref: '#/components/schemas/LocationType'
          description: Type of location (SHIPPER, RECEIVER, or BOTH)
          example: SHIPPER
        isAppointmentRequired:
          type: boolean
          description: Whether appointments are required for this location
          example: true
        notes:
          type: string
          description: External notes visible to carriers
          example: Call 24 hours ahead for appointment
          nullable: true
        internalNotes:
          type: string
          description: Internal notes (not visible to carriers)
          example: Use dock door 5 for expedited shipments
          nullable: true
    LocationContactType:
      type: string
      description: Type of location contact role
      enum:
        - ACCOUNT_MANAGER
        - BILLING
        - DOCK_SHIPPING
        - EMERGENCY
        - LOCATION_MANAGER
        - OWNER
        - PROCUREMENT
        - PURCHASING
        - RATES_PRICING
        - RECEIVING
        - SHIPPING
    LocationContactTypeFilter:
      type: object
      description: Filter for contact type enum array field
      properties:
        includes:
          $ref: '#/components/schemas/LocationContactType'
          description: Array contains this contact type
        notIncludes:
          $ref: '#/components/schemas/LocationContactType'
          description: Array does not contain this contact type
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    LocationContactFilter:
      type: object
      description: Filter criteria for location contacts with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/LocationContactFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/LocationContactFilter'
        not:
          $ref: '#/components/schemas/LocationContactFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        locationId:
          $ref: '#/components/schemas/UUIDFilter'
        customerContactId:
          $ref: '#/components/schemas/UUIDFilter'
        isPrimary:
          $ref: '#/components/schemas/BooleanFilter'
        contactTypes:
          $ref: '#/components/schemas/LocationContactTypeFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    LocationContactFilterRequest:
      type: object
      description: Request body for filtering location contacts
      properties:
        filter:
          $ref: '#/components/schemas/LocationContactFilter'
          description: |
            Filter criteria (optional - omit to return all location contacts).

            Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - locationId:
                equalTo: 770e8400-e29b-41d4-a716-446655440000
            - isPrimary:
                equalTo: true
        pageSize: 50
    LocationContact:
      type: object
      required:
        - id
        - locationId
        - customerContactId
        - isPrimary
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - LOCATION_CONTACT
          readOnly: true
          description: Object type identifier
          example: LOCATION_CONTACT
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique location contact identifier
          example: 880e8400-e29b-41d4-a716-446655440000
        locationId:
          type: string
          format: uuid
          description: Location this contact is associated with
          example: 770e8400-e29b-41d4-a716-446655440000
        location:
          $ref: '#/components/schemas/Location'
          readOnly: true
          description: The location this contact is associated with
        customerContactId:
          type: string
          format: uuid
          description: Customer contact linked to this location
          example: 660e8400-e29b-41d4-a716-446655440000
        customerContact:
          $ref: '#/components/schemas/CustomerContact'
          readOnly: true
          description: The customer contact details
        isPrimary:
          type: boolean
          description: Whether this is the primary contact for the location
          example: true
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/LocationContactType'
          description: Roles/types for this location contact
          example:
            - LOCATION_MANAGER
            - SHIPPING
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier for this location contact
          example: ERP-LOC-CONTACT-001
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when location contact was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when location contact was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when location contact was soft-deleted (null if active)
          example: null
          nullable: true
    LocationContactReference:
      type: object
      description: |
        Location contact reference for embedding in Location responses.
        Identical to LocationContact but excludes the location and locationId fields to avoid circular references.
      required:
        - id
        - customerContactId
        - isPrimary
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - LOCATION_CONTACT
          readOnly: true
          description: Object type identifier
          example: LOCATION_CONTACT
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique location contact identifier
          example: 880e8400-e29b-41d4-a716-446655440000
        customerContactId:
          type: string
          format: uuid
          description: Customer contact linked to this location
          example: 660e8400-e29b-41d4-a716-446655440000
        customerContact:
          $ref: '#/components/schemas/CustomerContact'
          readOnly: true
          description: The customer contact details
        isPrimary:
          type: boolean
          description: Whether this is the primary contact for the location
          example: true
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/LocationContactType'
          description: Roles/types for this location contact
          example:
            - LOCATION_MANAGER
            - SHIPPING
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier for this location contact
          example: ERP-LOC-CONTACT-001
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when location contact was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when location contact was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when location contact was soft-deleted (null if active)
          example: null
          nullable: true
    LocationContactInput:
      type: object
      required:
        - locationId
        - customerContactId
        - isPrimary
      properties:
        locationId:
          type: string
          format: uuid
          description: Location this contact is associated with (required)
          example: 770e8400-e29b-41d4-a716-446655440000
        customerContactId:
          type: string
          format: uuid
          description: Customer contact to link to this location (required)
          example: 660e8400-e29b-41d4-a716-446655440000
        isPrimary:
          type: boolean
          description: Whether this is the primary contact for the location (required)
          example: true
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/LocationContactType'
          description: Roles/types for this location contact
          example:
            - LOCATION_MANAGER
            - SHIPPING
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-LOC-CONTACT-001
    LocationContactPatch:
      type: object
      description: |
        Partial location contact update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        locationId:
          type: string
          format: uuid
          description: Location this contact is associated with
          example: 770e8400-e29b-41d4-a716-446655440000
        customerContactId:
          type: string
          format: uuid
          description: Customer contact linked to this location
          example: 660e8400-e29b-41d4-a716-446655440000
        isPrimary:
          type: boolean
          description: Whether this is the primary contact for the location
          example: true
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/LocationContactType'
          description: Roles/types for this location contact
          example:
            - LOCATION_MANAGER
            - SHIPPING
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-LOC-CONTACT-001
          nullable: true
    PaymentTermFilter:
      type: object
      description: Filter criteria for payment terms with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/PaymentTermFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/PaymentTermFilter'
        not:
          $ref: '#/components/schemas/PaymentTermFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        description:
          $ref: '#/components/schemas/StringFilter'
        days:
          $ref: '#/components/schemas/IntFilter'
        quickPayFee:
          $ref: '#/components/schemas/FloatFilter'
        apOnly:
          $ref: '#/components/schemas/BooleanFilter'
        doNotUse:
          $ref: '#/components/schemas/BooleanFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    PaymentTermFilterRequest:
      type: object
      description: Request body for filtering payment terms
      properties:
        filter:
          $ref: '#/components/schemas/PaymentTermFilter'
          description: |
            Filter criteria (optional - omit to return all payment terms).
            Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: Filter criteria (optional - omit to return all payment terms).
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes: {}
                        children: []
                        type: softbreak
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: 'Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - doNotUse:
                equalTo: false
            - days:
                greaterThan: 0
        pageSize: 50
    PaymentTerm:
      type: object
      required:
        - id
        - name
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique payment term identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Payment term name
          example: Net 30
        description:
          type: string
          description: Payment term description or notes
          example: Payment due 30 days from invoice date
          nullable: true
        days:
          type: integer
          description: Number of days until payment is due
          example: 30
          nullable: true
        quickPayFee:
          type: number
          format: float
          description: Quick pay fee percentage (e.g., 0.05 for 5%)
          example: 0.05
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 1
                        inline: true
                        attributes:
                          content: Quick pay fee percentage (e.g., 0.05 for 5%)
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
          nullable: true
        apOnly:
          type: boolean
          description: Whether this payment term is for accounts payable only
          example: false
          nullable: true
        doNotUse:
          type: boolean
          description: Flag to prevent using this payment term for new transactions
          example: false
          nullable: true
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-PAYTERM-NET30
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment term was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment term was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment term was soft deleted (null if active)
          example: null
          nullable: true
    PaymentTermInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Payment term name
          example: Net 30
        description:
          type: string
          description: Payment term description or notes
          example: Payment due 30 days from invoice date
        days:
          type: integer
          description: Number of days until payment is due
          example: 30
        quickPayFee:
          type: number
          format: float
          description: Quick pay fee percentage (e.g., 0.05 for 5%)
          example: 0.05
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 1
                        inline: true
                        attributes:
                          content: Quick pay fee percentage (e.g., 0.05 for 5%)
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        apOnly:
          type: boolean
          description: Whether this payment term is for accounts payable only
          example: false
        doNotUse:
          type: boolean
          description: Flag to prevent using this payment term for new transactions
          example: false
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-PAYTERM-NET30
    PaymentTermPatch:
      type: object
      description: |
        Partial payment term update. All fields are optional.
        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Payment term name
          example: Net 30
        description:
          type: string
          description: Payment term description
          example: Payment due 30 days from invoice date
          nullable: true
        days:
          type: integer
          description: Number of days until payment is due
          example: 30
          nullable: true
        quickPayFee:
          type: number
          format: float
          description: Quick pay fee percentage
          example: 0.05
          nullable: true
        apOnly:
          type: boolean
          description: Whether this payment term is for accounts payable only
          example: false
          nullable: true
        doNotUse:
          type: boolean
          description: Flag to prevent using this payment term
          example: false
          nullable: true
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-PAYTERM-NET30
          nullable: true
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: Partial payment term update. All fields are optional.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 4
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 1
                              - 2
                            inline: true
                            attributes:
                              content: Omitted fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': Not modified (current value preserved)'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 2
                              - 3
                            inline: true
                            attributes:
                              content: Provided fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Updated to the new value'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 3
                              - 4
                            inline: true
                            attributes:
                              content: Null values
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': Clear the field (set to null) where applicable'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    TeamFilter:
      type: object
      description: Filter criteria for teams with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/TeamFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/TeamFilter'
        not:
          $ref: '#/components/schemas/TeamFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    TeamFilterRequest:
      type: object
      description: Request body for filtering teams
      properties:
        filter:
          $ref: '#/components/schemas/TeamFilter'
          description: |
            Filter criteria (optional - omit to return all teams).
            Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: Filter criteria (optional - omit to return all teams).
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes: {}
                        children: []
                        type: softbreak
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: 'Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          name:
            includes: Sales
        pageSize: 50
    Team:
      type: object
      required:
        - id
        - name
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - TEAM
          readOnly: true
          description: Object type identifier
          example: TEAM
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique team identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
          description: Team name
          example: Sales Team - West Coast
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier for this team
          example: ERP-TEAM-WEST
          nullable: true
        users:
          type: array
          description: Users who are members of this team
          items:
            $ref: '#/components/schemas/UserReference-2'
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when team was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when team was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when team was soft-deleted (null if active)
          example: null
          nullable: true
    TeamInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Team name (required)
          example: Sales Team - West Coast
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-TEAM-WEST
        users:
          type: array
          description: Users to add to this team
          items:
            $ref: '#/components/schemas/ResourceReferenceInput'
          example:
            - id: 550e8400-e29b-41d4-a716-446655440000
            - key: ERP-USER-12345
    TeamPatch:
      type: object
      description: |
        Partial team update. All fields are optional.
        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Team name
          example: Sales Team - West Coast
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-TEAM-WEST
          nullable: true
        users:
          type: array
          description: Team members (replaces all existing memberships)
          items:
            $ref: '#/components/schemas/ResourceReferenceInput'
          example:
            - id: 550e8400-e29b-41d4-a716-446655440000
            - key: ERP-USER-12345
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: Partial team update. All fields are optional.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 4
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 1
                              - 2
                            inline: true
                            attributes:
                              content: Omitted fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': Not modified (current value preserved)'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 2
                              - 3
                            inline: true
                            attributes:
                              content: Provided fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Updated to the new value'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 3
                              - 4
                            inline: true
                            attributes:
                              content: Null values
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': Clear the field (set to null) where applicable'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    UserStatus:
      type: string
      enum:
        - PENDING
        - ACTIVE
        - INACTIVE
      description: |
        User account status:
        - `PENDING`: User invited but has not completed onboarding
        - `ACTIVE`: User account is active and can access the system
        - `INACTIVE`: User account is deactivated
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: 'User account status:'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 4
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: PENDING
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': User invited but has not completed onboarding'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ACTIVE
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': User account is active and can access the system'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: INACTIVE
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': User account is deactivated'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    UserRole:
      type: string
      enum:
        - CUSTOMER_REP
        - CARRIER_REP
        - AR_AP
        - COMPLIANCE
        - MANAGER
        - ADMIN
      description: |
        User role within the organization:
        - `CUSTOMER_REP`: Customer service representative
        - `CARRIER_REP`: Carrier service representative
        - `AR_AP`: Accounts receivable/payable
        - `COMPLIANCE`: Compliance officer
        - `ADMIN`: System administrator
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: 'User role within the organization:'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 6
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: CUSTOMER_REP
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': Customer service representative'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: CARRIER_REP
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Carrier service representative'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: AR_AP
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': Accounts receivable/payable'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 4
                  - 5
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 4
                      - 5
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 4
                          - 5
                        inline: true
                        attributes:
                          content: COMPLIANCE
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 4
                          - 5
                        inline: true
                        attributes:
                          content: ': Compliance officer'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 5
                  - 6
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 5
                      - 6
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 5
                          - 6
                        inline: true
                        attributes:
                          content: ADMIN
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 5
                          - 6
                        inline: true
                        attributes:
                          content: ': System administrator'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    UserStatusFilter:
      type: object
      description: Filter options for UserStatus enum
      properties:
        equalTo:
          $ref: '#/components/schemas/UserStatus'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/UserStatus'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/UserStatus'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/UserStatus'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    UserRoleFilter:
      type: object
      description: Filter options for UserRole enum array
      properties:
        contains:
          $ref: '#/components/schemas/UserRole'
          description: Array contains this role
        containsAll:
          type: array
          items:
            $ref: '#/components/schemas/UserRole'
          description: Array contains all of these roles
        containsAny:
          type: array
          items:
            $ref: '#/components/schemas/UserRole'
          description: Array contains at least one of these roles
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    UserFilter:
      type: object
      description: Filter criteria for users with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/UserFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/UserFilter'
        not:
          $ref: '#/components/schemas/UserFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        phone:
          $ref: '#/components/schemas/StringFilter'
        status:
          $ref: '#/components/schemas/UserStatusFilter'
        roles:
          $ref: '#/components/schemas/UserRoleFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        datUsername:
          $ref: '#/components/schemas/StringFilter'
        mcpUsername:
          $ref: '#/components/schemas/StringFilter'
        avatarId:
          $ref: '#/components/schemas/UUIDFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    UserFilterRequest:
      type: object
      description: Request body for filtering users
      properties:
        filter:
          $ref: '#/components/schemas/UserFilter'
          description: |
            Filter criteria (optional - omit to return all users).
            Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: Filter criteria (optional - omit to return all users).
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes: {}
                        children: []
                        type: softbreak
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: 'Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - status:
                equalTo: ACTIVE
            - roles:
                contains: CUSTOMER_REP
            - email:
                includes: '@example.com'
        pageSize: 50
    User:
      type: object
      required:
        - id
        - email
        - status
        - roles
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - USER
          readOnly: true
          description: Object type identifier
          example: USER
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique user identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        email:
          type: string
          format: email
          description: User's email address
          example: john.doe@example.com
        name:
          type: string
          description: User's full name
          example: John Doe
          nullable: true
        phone:
          type: string
          description: User's phone number
          example: +1-555-123-4567
          nullable: true
        phoneExt:
          type: string
          description: Phone extension
          example: '123'
          nullable: true
        status:
          $ref: '#/components/schemas/UserStatus'
        roles:
          type: array
          description: User's roles within the organization
          items:
            $ref: '#/components/schemas/UserRole'
          example:
            - CUSTOMER_REP
            - ADMIN
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier for this user
          example: ERP-USER-12345
          nullable: true
        datUsername:
          type: string
          description: DAT (Load Board) integration username
          example: johndoe_dat
          nullable: true
        mcpUsername:
          type: string
          description: MyCarrierPortal integration username
          example: johndoe_mcp
          nullable: true
        avatarId:
          type: string
          format: uuid
          description: Profile avatar document ID
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
          nullable: true
        teams:
          type: array
          description: Teams this user belongs to
          items:
            $ref: '#/components/schemas/TeamReference'
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when user was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when user was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when user was soft-deleted (null if active)
          example: null
          nullable: true
    UserInput:
      type: object
      required:
        - email
        - status
        - roles
      properties:
        email:
          type: string
          format: email
          description: User's email address (required)
          example: john.doe@example.com
        name:
          type: string
          description: User's full name
          example: John Doe
        phone:
          type: string
          description: User's phone number
          example: +1-555-123-4567
        phoneExt:
          type: string
          description: Phone extension
          example: '123'
        status:
          $ref: '#/components/schemas/UserStatus'
        roles:
          type: array
          description: User's roles within the organization (required)
          items:
            $ref: '#/components/schemas/UserRole'
          minItems: 1
          example:
            - CUSTOMER_REP
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-USER-12345
        datUsername:
          type: string
          description: DAT (Load Board) integration username
          example: johndoe_dat
        mcpUsername:
          type: string
          description: MyCarrierPortal integration username
          example: johndoe_mcp
        avatarId:
          type: string
          format: uuid
          description: Profile avatar document ID
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        teams:
          type: array
          description: Teams to add this user to
          items:
            $ref: '#/components/schemas/ResourceReferenceInput'
          example:
            - id: 123e4567-e89b-12d3-a456-426614174000
            - key: TEAM-WEST-COAST
    UserPatch:
      type: object
      description: |
        Partial user update. All fields are optional.
        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        email:
          type: string
          format: email
          description: User's email address
          example: john.doe@example.com
        name:
          type: string
          description: User's full name
          example: John Doe
          nullable: true
        phone:
          type: string
          description: User's phone number
          example: +1-555-123-4567
          nullable: true
        phoneExt:
          type: string
          description: Phone extension
          example: '123'
          nullable: true
        status:
          $ref: '#/components/schemas/UserStatus'
        roles:
          type: array
          description: User's roles (replaces all existing roles)
          items:
            $ref: '#/components/schemas/UserRole'
          minItems: 1
          example:
            - CUSTOMER_REP
            - ADMIN
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-USER-12345
          nullable: true
        datUsername:
          type: string
          description: DAT integration username
          example: johndoe_dat
          nullable: true
        mcpUsername:
          type: string
          description: MyCarrierPortal integration username
          example: johndoe_mcp
          nullable: true
        avatarId:
          type: string
          format: uuid
          description: Profile avatar document ID
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
          nullable: true
        teams:
          type: array
          description: Teams this user belongs to (replaces all existing team memberships)
          items:
            $ref: '#/components/schemas/ResourceReferenceInput'
          example:
            - id: 123e4567-e89b-12d3-a456-426614174000
            - key: TEAM-WEST-COAST
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: Partial user update. All fields are optional.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 4
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 1
                              - 2
                            inline: true
                            attributes:
                              content: Omitted fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': Not modified (current value preserved)'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 2
                              - 3
                            inline: true
                            attributes:
                              content: Provided fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Updated to the new value'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 3
                              - 4
                            inline: true
                            attributes:
                              content: Null values
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': Clear the field (set to null) where applicable'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    VendorStatus:
      type: string
      description: Vendor status
      enum:
        - ACTIVE
        - INACTIVE
        - DO_NOT_USE
    VendorStatusFilter:
      type: object
      description: Filter for vendor status enum field
      properties:
        equalTo:
          $ref: '#/components/schemas/VendorStatus'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/VendorStatus'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/VendorStatus'
          description: Matches any value in the list
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/VendorStatus'
          description: Does not match any value in the list
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    VendorFilter:
      type: object
      description: Filter criteria for vendors with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/VendorFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/VendorFilter'
        not:
          $ref: '#/components/schemas/VendorFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        friendlyId:
          $ref: '#/components/schemas/StringFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        phone:
          $ref: '#/components/schemas/StringFilter'
        status:
          $ref: '#/components/schemas/VendorStatusFilter'
        notes:
          $ref: '#/components/schemas/StringFilter'
        taxId:
          $ref: '#/components/schemas/StringFilter'
        currency:
          $ref: '#/components/schemas/CurrencyFilter'
        paymentTermId:
          $ref: '#/components/schemas/UUIDFilter'
        isMvmnt:
          $ref: '#/components/schemas/BooleanFilter'
        deletedById:
          $ref: '#/components/schemas/UUIDFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    VendorFilterRequest:
      type: object
      description: Request body for filtering vendors
      properties:
        filter:
          $ref: '#/components/schemas/VendorFilter'
          description: |
            Filter criteria (optional - omit to return all vendors).

            Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - status:
                equalTo: ACTIVE
            - currency:
                equalTo: USD
        pageSize: 50
    Vendor:
      type: object
      required:
        - id
        - friendlyId
        - name
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - VENDOR
          readOnly: true
          description: Object type identifier
          example: VENDOR
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique vendor identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        friendlyId:
          type: string
          readOnly: true
          description: Human-readable vendor identifier
          example: V123456
        name:
          type: string
          description: Vendor legal name
          example: ABC Warehouse Services
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-VENDOR-ABC-001
          nullable: true
        email:
          type: string
          format: email
          description: Primary email address
          example: billing@abcwarehouse.com
          nullable: true
        phone:
          type: string
          description: Primary phone number
          example: +1-555-123-4567
          nullable: true
        status:
          type: string
          description: Vendor status
          example: ACTIVE
          nullable: true
        notes:
          type: string
          description: Internal notes about the vendor
          example: Preferred vendor for warehouse services
          nullable: true
        taxId:
          type: string
          description: Tax identification number
          example: 12-3456789
          nullable: true
        currency:
          description: Preferred currency for transactions
          $ref: '#/components/schemas/Currency-2'
          nullable: true
        corporateAddress:
          description: Corporate headquarters address
          $ref: '#/components/schemas/Address'
          nullable: true
        billingAddress:
          description: Billing address for invoices
          $ref: '#/components/schemas/Address'
          nullable: true
        paymentTerm:
          description: Payment terms for this vendor
          $ref: '#/components/schemas/PaymentTermReference'
          nullable: true
        isMvmnt:
          type: boolean
          description: Whether this vendor is MVMNT itself
          example: false
          nullable: true
        requiredDocuments:
          type: array
          items:
            type: string
          description: List of required document types
          example:
            - W9
            - INSURANCE_CERTIFICATE
          nullable: true
        paymentMethods:
          type: array
          description: Payment methods configured for this vendor
          items:
            $ref: '#/components/schemas/VendorPaymentMethodReference'
        contacts:
          type: array
          description: Contacts for this vendor
          items:
            $ref: '#/components/schemas/VendorContactReference'
        deletedBy:
          readOnly: true
          description: User who deleted this vendor (full user details)
          $ref: '#/components/schemas/UserReference'
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the vendor was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the vendor was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the vendor was soft deleted (null if active)
          example: null
          nullable: true
    VendorInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Vendor legal name
          example: ABC Warehouse Services
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-VENDOR-ABC-001
        email:
          type: string
          format: email
          description: Primary email address
          example: billing@abcwarehouse.com
        phone:
          type: string
          description: Primary phone number
          example: +1-555-123-4567
        status:
          type: string
          description: Vendor status
          example: ACTIVE
        notes:
          type: string
          description: Internal notes about the vendor
          example: Preferred vendor for warehouse services
        taxId:
          type: string
          description: Tax identification number
          example: 12-3456789
        currency:
          $ref: '#/components/schemas/Currency-2'
          description: Preferred currency for transactions
        corporateAddress:
          $ref: '#/components/schemas/AddressInput'
          description: Corporate headquarters address
        billingAddress:
          $ref: '#/components/schemas/AddressInput'
          description: Billing address for invoices
        paymentTermId:
          type: string
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440001
        isMvmnt:
          type: boolean
          description: Whether this vendor is MVMNT itself
          example: false
        requiredDocuments:
          type: array
          items:
            type: string
          description: List of required document types
          example:
            - W9
            - INSURANCE_CERTIFICATE
    VendorPatch:
      type: object
      description: |
        Partial vendor update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Vendor legal name
          example: ABC Warehouse Services
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-VENDOR-ABC-001
          nullable: true
        email:
          type: string
          format: email
          description: Primary email address
          example: billing@abcwarehouse.com
          nullable: true
        phone:
          type: string
          description: Primary phone number
          example: +1-555-123-4567
          nullable: true
        status:
          type: string
          description: Vendor status
          example: ACTIVE
          nullable: true
        notes:
          type: string
          description: Internal notes about the vendor
          example: Preferred vendor for warehouse services
          nullable: true
        taxId:
          type: string
          description: Tax identification number
          example: 12-3456789
          nullable: true
        currency:
          description: Preferred currency for transactions
          $ref: '#/components/schemas/Currency-2'
          nullable: true
        corporateAddress:
          description: Corporate headquarters address
          $ref: '#/components/schemas/AddressInput'
          nullable: true
        billingAddress:
          description: Billing address for invoices
          $ref: '#/components/schemas/AddressInput'
          nullable: true
        paymentTermId:
          type: string
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440001
          nullable: true
        isMvmnt:
          type: boolean
          description: Whether this vendor is MVMNT itself
          example: false
          nullable: true
        requiredDocuments:
          type: array
          items:
            type: string
          description: List of required document types
          example:
            - W9
            - INSURANCE_CERTIFICATE
          nullable: true
    VendorContactRole:
      type: string
      description: Type of vendor contact role
      enum:
        - AGENT
        - BILLING
        - OPERATION
        - OWNER
    VendorContactRoleFilter:
      type: object
      description: Filter for contact role enum array field
      properties:
        includes:
          $ref: '#/components/schemas/VendorContactRole'
          description: Array contains this contact role
        notIncludes:
          $ref: '#/components/schemas/VendorContactRole'
          description: Array does not contain this contact role
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    VendorContactFilter:
      type: object
      description: Filter criteria for vendor contacts with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/VendorContactFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/VendorContactFilter'
        not:
          $ref: '#/components/schemas/VendorContactFilter'
          description: Negates the filter
        vendorId:
          $ref: '#/components/schemas/UUIDFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        phone:
          $ref: '#/components/schemas/StringFilter'
        role:
          $ref: '#/components/schemas/StringFilter'
        roles:
          $ref: '#/components/schemas/VendorContactRoleFilter'
        deletedById:
          $ref: '#/components/schemas/UUIDFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    VendorContactFilterRequest:
      type: object
      description: Request body for filtering vendor contacts
      properties:
        filter:
          $ref: '#/components/schemas/VendorContactFilter'
          description: |
            Filter criteria (optional - omit to return all vendor contacts).

            Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - roles:
                includes: BILLING
            - vendorId:
                equalTo: 550e8400-e29b-41d4-a716-446655440001
        pageSize: 50
    VendorContact:
      type: object
      required:
        - vendor
        - createdAt
      properties:
        object:
          type: string
          enum:
            - VENDOR_CONTACT
          readOnly: true
          description: Object type identifier
          example: VENDOR_CONTACT
        vendor:
          $ref: '#/components/schemas/ResourceReference'
          description: Vendor this contact belongs to (id and key only)
        email:
          type: string
          format: email
          description: Contact email address
          example: john.smith@abcwarehouse.com
          nullable: true
        phone:
          type: string
          description: Contact phone number
          example: +1-555-123-4567
          nullable: true
        role:
          type: string
          description: Contact role or title (deprecated - use roles array)
          example: Billing Manager
          nullable: true
        roles:
          type: array
          items:
            $ref: '#/components/schemas/VendorContactRole'
          description: Types/roles this contact serves
          example:
            - BILLING
            - AGENT
          nullable: true
        deletedBy:
          readOnly: true
          description: User who deleted this contact (full user details)
          $ref: '#/components/schemas/UserReference'
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was created
          example: '2025-01-15T10:00:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was soft deleted (null if active)
          example: null
          nullable: true
    VendorContactInput:
      type: object
      required:
        - vendorId
        - name
      properties:
        vendorId:
          type: string
          format: uuid
          description: Vendor this contact belongs to
          example: 550e8400-e29b-41d4-a716-446655440001
        name:
          type: string
          description: Contact person's name (required)
          example: John Smith
        email:
          type: string
          format: email
          description: Contact email address
          example: john.smith@abcwarehouse.com
        phone:
          type: string
          description: Contact phone number
          example: +1-555-123-4567
        role:
          type: string
          description: Contact role or title (deprecated - use roles array)
          example: Billing Manager
        roles:
          type: array
          items:
            $ref: '#/components/schemas/VendorContactRole'
          description: Types/roles this contact serves
          example:
            - BILLING
            - AGENT
    VendorContactPatch:
      type: object
      description: |
        Partial vendor contact update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable

        Note: vendorId cannot be updated after creation.
      properties:
        email:
          type: string
          format: email
          description: Contact email address
          example: john.smith@abcwarehouse.com
          nullable: true
        phone:
          type: string
          description: Contact phone number
          example: +1-555-123-4567
          nullable: true
        role:
          type: string
          description: Contact role or title (deprecated - use roles array)
          example: Billing Manager
          nullable: true
        roles:
          type: array
          items:
            $ref: '#/components/schemas/VendorContactRole'
          description: Types/roles this contact serves (replaces entire array)
          example:
            - BILLING
            - AGENT
          nullable: true
    VendorReference:
      type: object
      description: |
        Enhanced reference to a vendor profile.
        Includes full vendor details in addition to id/key.
      required:
        - id
        - friendlyId
        - name
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Vendor UUID
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          maxLength: 512
          description: Client-defined reference ID if set
          example: ERP-VENDOR-ABC-001
          nullable: true
        friendlyId:
          type: string
          description: Human-readable vendor identifier
          example: V123456
        name:
          type: string
          description: Vendor legal name
          example: ABC Warehouse Services
        email:
          type: string
          format: email
          description: Primary email address
          example: billing@abcwarehouse.com
          nullable: true
        phone:
          type: string
          description: Primary phone number
          example: +1-555-123-4567
          nullable: true
        status:
          type: string
          description: Vendor status
          example: ACTIVE
          nullable: true
        currency:
          type: string
          description: Preferred currency code (ISO 4217)
          example: USD
          nullable: true
        createdAt:
          type: string
          format: date-time
          description: When the vendor was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the vendor was last updated
          example: '2025-01-15T14:30:00Z'
    VendorPaymentMethodType:
      $ref: '#/components/schemas/PaymentMethodType-2'
    VendorPaymentMethodTypeFilter:
      $ref: '#/components/schemas/PaymentMethodTypeFilter-2'
    VendorPaymentMethod:
      type: object
      required:
        - id
        - vendorId
        - vendor
        - paymentMethodType
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique vendor payment method identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        vendorId:
          type: string
          format: uuid
          readOnly: true
          description: |
            Vendor profile ID (read-only after creation).

            This field cannot be changed after the payment method is created.
          example: 770e8400-e29b-41d4-a716-446655440000
        vendor:
          $ref: '#/components/schemas/VendorReference'
          description: Vendor profile reference with full details
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType-2'
          description: How payment is made
        status:
          type: string
          description: Payment method status
          example: ACTIVE
          nullable: true
        isPreferred:
          type: boolean
          description: Whether this is the preferred payment method for the vendor
          example: true
          nullable: true
        email:
          type: string
          format: email
          description: Email address for payment notifications
          example: payments@vendor.com
          nullable: true
        phone:
          type: string
          description: Phone number for payment contact
          example: +1-555-123-4567
          nullable: true
        companyName:
          type: string
          description: Company name for this payment method (may differ from vendor name)
          example: Vendor Payments LLC
          nullable: true
        username:
          type: string
          description: Username for payment platforms (e.g., Zelle, Venmo)
          example: vendor_payments
          nullable: true
        bankName:
          type: string
          description: Bank name
          example: Chase Bank
          nullable: true
        bankAddress:
          type: string
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
          nullable: true
        accountName:
          type: string
          description: Bank account holder name
          example: Vendor Services Inc
          nullable: true
        accountNumber:
          type: string
          description: Bank account number (masked in responses)
          example: '****1234'
          nullable: true
        abaAch:
          type: string
          description: ABA/ACH routing number for electronic transfers
          example: '021000021'
          nullable: true
        wire:
          type: string
          description: Wire transfer routing number
          example: '026009593'
          nullable: true
        swiftCode:
          type: string
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
          nullable: true
        eftInstitution:
          type: string
          description: EFT institution number (Canadian banking)
          example: '001'
          nullable: true
        eftTransit:
          type: string
          description: EFT transit number (Canadian banking)
          example: '00010'
          nullable: true
        clabe:
          type: string
          description: CLABE number (Mexican banking identifier)
          example: '012180001234567897'
          nullable: true
        currency:
          type: string
          description: Preferred currency code (ISO 4217)
          example: USD
          nullable: true
        paymentTerm:
          description: Payment terms for this payment method
          $ref: '#/components/schemas/PaymentTermReference'
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was soft deleted (null if active)
          example: null
          nullable: true
        deletedBy:
          readOnly: true
          description: User who deleted this payment method
          $ref: '#/components/schemas/UserReference'
          nullable: true
    VendorPaymentMethodInput:
      type: object
      required:
        - vendorId
        - paymentMethodType
      properties:
        vendorId:
          type: string
          format: uuid
          description: |
            Vendor profile ID.

            **IMPORTANT**: This field cannot be changed after creation.
          example: 770e8400-e29b-41d4-a716-446655440000
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType-2'
          description: How payment is made
        status:
          type: string
          description: Payment method status
          example: ACTIVE
        isPreferred:
          type: boolean
          description: Whether this is the preferred payment method
          example: true
        email:
          type: string
          format: email
          description: Email address for payment notifications
          example: payments@vendor.com
        phone:
          type: string
          description: Phone number for payment contact
          example: +1-555-123-4567
        companyName:
          type: string
          description: Company name for this payment method
          example: Vendor Payments LLC
        username:
          type: string
          description: Username for payment platforms
          example: vendor_payments
        bankName:
          type: string
          description: Bank name
          example: Chase Bank
        bankAddress:
          type: string
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
        accountName:
          type: string
          description: Bank account holder name
          example: Vendor Services Inc
        accountNumber:
          type: string
          description: Bank account number
          example: '1234567890'
        abaAch:
          type: string
          description: ABA/ACH routing number
          example: '021000021'
        wire:
          type: string
          description: Wire transfer routing number
          example: '026009593'
        swiftCode:
          type: string
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
        eftInstitution:
          type: string
          description: EFT institution number (Canadian banking)
          example: '001'
        eftTransit:
          type: string
          description: EFT transit number (Canadian banking)
          example: '00010'
        clabe:
          type: string
          description: CLABE number (Mexican banking)
          example: '012180001234567897'
        currency:
          type: string
          description: Preferred currency code (ISO 4217)
          example: USD
        paymentTermId:
          type: string
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
    VendorPaymentMethodPatch:
      type: object
      description: |
        Partial vendor payment method update. All fields are optional.

        **IMPORTANT**: The `vendorId` field cannot be changed after creation.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType-2'
          description: How payment is made
        status:
          type: string
          description: Payment method status
          example: ACTIVE
          nullable: true
        isPreferred:
          type: boolean
          description: Whether this is the preferred payment method
          example: true
          nullable: true
        email:
          type: string
          format: email
          description: Email address for payment notifications
          example: payments@vendor.com
          nullable: true
        phone:
          type: string
          description: Phone number for payment contact
          example: +1-555-123-4567
          nullable: true
        companyName:
          type: string
          description: Company name for this payment method
          example: Vendor Payments LLC
          nullable: true
        username:
          type: string
          description: Username for payment platforms
          example: vendor_payments
          nullable: true
        bankName:
          type: string
          description: Bank name
          example: Chase Bank
          nullable: true
        bankAddress:
          type: string
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
          nullable: true
        accountName:
          type: string
          description: Bank account holder name
          example: Vendor Services Inc
          nullable: true
        accountNumber:
          type: string
          description: Bank account number
          example: '1234567890'
          nullable: true
        abaAch:
          type: string
          description: ABA/ACH routing number
          example: '021000021'
          nullable: true
        wire:
          type: string
          description: Wire transfer routing number
          example: '026009593'
          nullable: true
        swiftCode:
          type: string
          description: SWIFT/BIC code
          example: CHASUS33
          nullable: true
        eftInstitution:
          type: string
          description: EFT institution number
          example: '001'
          nullable: true
        eftTransit:
          type: string
          description: EFT transit number
          example: '00010'
          nullable: true
        clabe:
          type: string
          description: CLABE number
          example: '012180001234567897'
          nullable: true
        currency:
          type: string
          description: Preferred currency code
          example: USD
          nullable: true
        paymentTermId:
          type: string
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
          nullable: true
    VendorPaymentMethodFilter:
      type: object
      description: Filter criteria for vendor payment methods with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/VendorPaymentMethodFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/VendorPaymentMethodFilter'
        not:
          $ref: '#/components/schemas/VendorPaymentMethodFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        vendorId:
          $ref: '#/components/schemas/UUIDFilter'
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodTypeFilter-2'
        status:
          $ref: '#/components/schemas/StringFilter'
        isPreferred:
          $ref: '#/components/schemas/BooleanFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        companyName:
          $ref: '#/components/schemas/StringFilter'
        bankName:
          $ref: '#/components/schemas/StringFilter'
        currency:
          $ref: '#/components/schemas/StringFilter'
        paymentTermId:
          $ref: '#/components/schemas/UUIDFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    VendorPaymentMethodFilterRequest:
      type: object
      description: Request body for filtering vendor payment methods
      properties:
        filter:
          $ref: '#/components/schemas/VendorPaymentMethodFilter'
          description: |
            Filter criteria (optional - omit to return all vendor payment methods).

            Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - vendorId:
                equalTo: 770e8400-e29b-41d4-a716-446655440000
            - isPreferred:
                equalTo: true
        pageSize: 50
    SavedSearchType:
      type: string
      description: |
        Type of entity this saved search applies to. Each type corresponds to a specific entity's search view.

        **Entity Mapping:**
        - `INVOICE`: Customer invoices (AR Invoices) - money owed to you
        - `BILL`: Vendor/Carrier bills (AP Invoices) - money you owe
        - `INVOICE_PAYMENT`: Customer payment groups (AR Payment Groups)
        - `BILL_PAYMENT`: Vendor/Carrier payment groups (AP Payment Groups)
      enum:
        - SHIPMENT
        - INVOICE
        - BILL
        - USER
        - CUSTOMER
        - VENDOR
        - QUOTE
        - COMMISSION
        - CARRIER
        - INVOICE_PAYMENT
        - BILL_PAYMENT
        - LOAD
        - TRUCK_POSTING
        - LOCATION
        - CARRIER_FACTOR
        - COMMISSION_PAYMENT
        - AR_CREDIT_MEMO
        - AP_CREDIT_MEMO
      example: SHIPMENT
    SavedSearchFilter:
      type: object
      description: Filter criteria for saved searches with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/SavedSearchFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/SavedSearchFilter'
        not:
          $ref: '#/components/schemas/SavedSearchFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        preferenceType:
          $ref: '#/components/schemas/StringFilter'
        isPublic:
          $ref: '#/components/schemas/BooleanFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    SavedSearchFilterRequest:
      type: object
      description: Request body for filtering saved searches
      properties:
        filter:
          $ref: '#/components/schemas/SavedSearchFilter'
          description: |
            Filter criteria (optional - omit to return all saved searches).
            Returns only saved searches accessible to the authenticated user.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          preferenceType:
            equalTo: SHIPMENT
          isPublic:
            equalTo: true
        pageSize: 50
    SearchConfigurationState:
      type: object
      description: |
        The saved search configuration state containing criteria, sorting, and display preferences.
        This is stored in the jsonValue field.
      properties:
        searchCriteria:
          type: object
          description: Search criteria configuration
          properties:
            filters:
              type: array
              description: Array of field-level search filters
              items:
                type: object
                required:
                  - field
                  - searchCriteria
                properties:
                  field:
                    type: string
                    description: The field name to filter on
                    example: status
                  searchCriteria:
                    type: object
                    description: The search criteria for this field
                    required:
                      - operator
                    properties:
                      operator:
                        type: string
                        description: Search operator (e.g., EQUALS, ONE_OF, BETWEEN)
                        example: ONE_OF
                      values:
                        type: array
                        description: Array of values for multi-value operators
                        items:
                          oneOf:
                            - type: string
                            - type: number
                            - type: boolean
                        example:
                          - ACTIVE
                          - PENDING
                      value:
                        oneOf:
                          - type: string
                          - type: number
                          - type: boolean
                        description: Single value for single-value operators
                      min:
                        oneOf:
                          - type: string
                          - type: number
                        description: Minimum value for range operators
                      max:
                        oneOf:
                          - type: string
                          - type: number
                        description: Maximum value for range operators
                      minRelative:
                        type: integer
                        description: Relative minimum (e.g., -7 for 7 units ago)
                      minRelativeUnit:
                        type: string
                        description: Time unit for minRelative
                        enum:
                          - YEAR
                          - MONTH
                          - WEEK
                          - DAY
                          - HOUR
                          - MINUTE
                          - SECOND
                      maxRelative:
                        type: integer
                        description: Relative maximum
                      maxRelativeUnit:
                        type: string
                        description: Time unit for maxRelative
                        enum:
                          - YEAR
                          - MONTH
                          - WEEK
                          - DAY
                          - HOUR
                          - MINUTE
                          - SECOND
                      valueRelative:
                        type: integer
                        description: Relative value
                      valueRelativeUnit:
                        type: string
                        description: Time unit for valueRelative
                        enum:
                          - YEAR
                          - MONTH
                          - WEEK
                          - DAY
                          - HOUR
                          - MINUTE
                          - SECOND
        sorting:
          type: array
          description: Sort configuration
          items:
            type: object
            required:
              - id
              - desc
            properties:
              id:
                type: string
                description: Field name to sort by
                example: createdAt
              desc:
                type: boolean
                description: Sort in descending order if true
                example: true
        columnVisibility:
          type: object
          description: Column visibility settings (key is column name, value is visibility)
          additionalProperties:
            type: boolean
          example:
            status: true
            createdAt: true
            updatedAt: false
        columnOrder:
          type: array
          description: Order of columns for display
          items:
            type: string
          example:
            - id
            - name
            - status
            - createdAt
      example:
        searchCriteria:
          filters:
            - field: status
              searchCriteria:
                operator: ONE_OF
                values:
                  - ACTIVE
                  - PENDING
        sorting:
          - id: createdAt
            desc: true
        columnVisibility:
          status: true
          createdAt: true
        columnOrder:
          - id
          - status
          - createdAt
    SavedSearch:
      type: object
      required:
        - id
        - name
        - preferenceType
        - createdAt
        - updatedAt
      description: |
        A saved search configuration that can be used to quickly apply predefined search criteria,
        sorting, and display preferences. Saved searches are stored per organization and can be
        shared publicly or kept private to a specific user.
      properties:
        object:
          type: string
          enum:
            - SAVED_SEARCH
          readOnly: true
          description: Object type identifier
          example: SAVED_SEARCH
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique saved search identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Display name for the saved search
          example: Active Shipments - West Coast
        preferenceType:
          allOf:
            - $ref: '#/components/schemas/SavedSearchType'
          description: |
            The entity type this saved search applies to.
            Must match the search endpoint where this saved search will be used.
        jsonValue:
          allOf:
            - $ref: '#/components/schemas/SearchConfigurationState'
          description: The saved search configuration (criteria, sorting, display preferences)
        isPublic:
          type: boolean
          description: |
            Whether this saved search is visible to all users in the organization.
            If false or null, only the owner can see it.
          example: true
          nullable: true
        ownedByUser:
          type: string
          format: uuid
          readOnly: true
          description: |
            User ID who owns this saved search.
            Null means it's an organization-level saved search.
          example: 550e8400-e29b-41d4-a716-446655440001
          nullable: true
        groupId:
          type: string
          format: uuid
          description: Optional group this saved search belongs to
          example: null
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when saved search was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when saved search was last updated
          example: '2025-01-15T14:30:00Z'
    SavedSearchInput:
      type: object
      required:
        - name
        - preferenceType
        - jsonValue
      description: Input for creating a new saved search
      properties:
        name:
          type: string
          description: Display name for the saved search (required)
          example: Active Shipments - West Coast
        preferenceType:
          allOf:
            - $ref: '#/components/schemas/SavedSearchType'
          description: |
            The entity type this saved search applies to (required).
            Determines which search endpoint can use this saved search.
        jsonValue:
          allOf:
            - $ref: '#/components/schemas/SearchConfigurationState'
          description: The saved search configuration (required)
        isPublic:
          type: boolean
          description: Whether this saved search is visible to all users in the organization
          default: false
          example: true
        groupId:
          type: string
          format: uuid
          description: Optional group this saved search belongs to
      example:
        name: Active Shipments - West Coast
        preferenceType: SHIPMENT
        jsonValue:
          searchCriteria:
            filters:
              - field: status
                searchCriteria:
                  operator: ONE_OF
                  values:
                    - ACTIVE
                    - PENDING
          sorting:
            - id: createdAt
              desc: true
        isPublic: true
    SavedSearchPatch:
      type: object
      description: |
        Partial saved search update. All fields are optional.
        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Display name for the saved search
          example: Updated Shipments View
        jsonValue:
          allOf:
            - $ref: '#/components/schemas/SearchConfigurationState'
          description: The saved search configuration
        isPublic:
          type: boolean
          description: Whether this saved search is visible to all users
          example: true
          nullable: true
        groupId:
          type: string
          format: uuid
          description: Optional group this saved search belongs to
          example: null
          nullable: true
      example:
        name: Updated Shipments View
        isPublic: true
    CustomerSearchCriteria:
      type: object
      description: |
        Search criteria for filtering customers.
        Note: Only active (non-deleted) customers are searchable. Soft-deleted records are automatically excluded.
      properties:
        id:
          $ref: '#/components/schemas/UUIDSearchCriteria'
        friendlyId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        name:
          $ref: '#/components/schemas/TextSearchCriteria'
        dbaName:
          $ref: '#/components/schemas/TextSearchCriteria'
        status:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Customer status (new, contacted, qualified, quoted, nurturing, pending, active, inactive, blocked, closed)
        city:
          $ref: '#/components/schemas/TextSearchCriteria'
        state:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: State/Province code (uppercase)
        location:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Computed field "city, state"
        zip:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        country:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Country code (uppercase)
        teamId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Team ID (internal field groupId)
        teamName:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Team name (internal field groupName)
        userIds:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: IDs of users associated with this customer
        userNames:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Names of users associated with this customer
        accountOwnerId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Primary account owner user ID
        accountOwnerName:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Primary account owner name
        operatedById:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Operations representative user ID
        operatedByName:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Operations representative name
        primaryContactName:
          $ref: '#/components/schemas/TextSearchCriteria'
        primaryContactEmail:
          $ref: '#/components/schemas/TextSearchCriteria'
        primaryContactPhone:
          $ref: '#/components/schemas/TextSearchCriteria'
        serviceTier:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        yearsInBusiness:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        numberOfEmployees:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        industry:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        sic:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Standard Industrial Classification code
        naics:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: North American Industry Classification System code
        paymentTermName:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        creditLimit:
          $ref: '#/components/schemas/FloatSearchCriteria'
        outstandingBalance:
          $ref: '#/components/schemas/FloatSearchCriteria'
        totalRevenue:
          $ref: '#/components/schemas/FloatSearchCriteria'
        totalTransportationCost:
          $ref: '#/components/schemas/FloatSearchCriteria'
        totalGrossProfit:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Computed as totalRevenue - totalTransportationCost
        ordersCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of non-canceled/rejected shipments
        quotesCount:
          $ref: '#/components/schemas/IntSearchCriteria'
        quotesWon:
          $ref: '#/components/schemas/IntSearchCriteria'
        quoteWinRate:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Computed win rate (quotesWon / quotesCount)
        mostRecentOrderCreationAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
          description: Date of the most recent order
        nextFollowUp:
          $ref: '#/components/schemas/DateSearchCriteria'
        lastOutreach:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
        quickbooksCustomerId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: QuickBooks Online customer ID (internal field qboCustomerId)
        tags:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Tag labels associated with the customer
        createdAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
        updatedAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
    CustomerSearchRequest:
      type: object
      description: Request body for searching customers
      properties:
        criteria:
          $ref: '#/components/schemas/CustomerSearchCriteria'
          description: Search criteria to filter customers
        pagination:
          $ref: '#/components/schemas/SearchPaginationInput'
        sort:
          type: array
          items:
            $ref: '#/components/schemas/SearchSortOption'
          maxItems: 3
          description: Sort options for the search results
        savedSearch:
          $ref: '#/components/schemas/SavedSearchLookup'
          description: |
            Optional saved search to load preferences from.
            When provided, the saved search criteria will be loaded and merged with any explicit criteria.
        format:
          type: string
          enum:
            - flat
            - full
          default: flat
          description: |
            Response format:
            - flat: Returns only indexed fields (default, faster)
            - full: Returns complete customer objects
    CustomerSearchRow:
      type: object
      description: |
        Flattened customer data from search index.
        Note: This represents only active customers. Soft-deleted records are never returned.
      properties:
        object:
          type: string
          enum:
            - CUSTOMER_SEARCH_ROW
          description: Object type identifier for discriminating between flat and full response formats
        id:
          type: string
          format: uuid
        friendlyId:
          type: string
          example: CUST-0001
        name:
          type: string
        dbaName:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - new
            - contacted
            - qualified
            - quoted
            - nurturing
            - pending
            - active
            - inactive
            - blocked
            - closed
        city:
          type: string
          nullable: true
        state:
          type: string
          description: State/Province code (uppercase)
          nullable: true
        location:
          type: string
          description: Computed as "city, state"
          nullable: true
        zip:
          type: string
          nullable: true
        country:
          type: string
          description: Country code (uppercase)
          nullable: true
        teamId:
          type: string
          format: uuid
          description: Team ID (maps from groupId)
          nullable: true
        teamName:
          type: string
          description: Team name (maps from groupName)
          nullable: true
        userIds:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of users associated with this customer
        userNames:
          type: array
          items:
            type: string
          description: Names of users associated with this customer (may be hidden in some contexts)
        accountOwnerId:
          type: string
          format: uuid
          nullable: true
        accountOwnerName:
          type: string
          nullable: true
        operatedById:
          type: string
          format: uuid
          nullable: true
        operatedByName:
          type: string
          nullable: true
        primaryContactName:
          type: string
          nullable: true
        primaryContactEmail:
          type: string
          format: email
          nullable: true
        primaryContactPhone:
          type: string
          nullable: true
        serviceTier:
          type: string
          nullable: true
        yearsInBusiness:
          type: string
          nullable: true
        numberOfEmployees:
          type: string
          nullable: true
        industry:
          type: string
          nullable: true
        sic:
          type: string
          description: Standard Industrial Classification code
          nullable: true
        naics:
          type: string
          description: North American Industry Classification System code
          nullable: true
        paymentTermName:
          type: string
          nullable: true
        creditLimit:
          type: number
          format: float
          nullable: true
        outstandingBalance:
          type: number
          format: float
          nullable: true
        totalRevenue:
          type: number
          format: float
          nullable: true
        totalTransportationCost:
          type: number
          format: float
          nullable: true
        totalGrossProfit:
          type: number
          format: float
          description: Computed as totalRevenue - totalTransportationCost
          nullable: true
        ordersCount:
          type: integer
          description: Number of non-canceled/rejected shipments
          nullable: true
        quotesCount:
          type: integer
          nullable: true
        quotesWon:
          type: integer
          nullable: true
        quoteWinRate:
          type: number
          format: float
          description: Win rate percentage (0-100)
          nullable: true
        mostRecentOrderCreationAt:
          type: string
          format: date-time
          nullable: true
        nextFollowUp:
          type: string
          format: date
          nullable: true
        lastOutreach:
          type: string
          format: date-time
          nullable: true
        quickbooksCustomerId:
          type: string
          description: QuickBooks Online customer ID (maps from qboCustomerId)
          nullable: true
        tags:
          type: array
          items:
            type: string
          description: Tag labels
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - object
        - id
        - friendlyId
        - name
        - status
        - createdAt
        - updatedAt
    CustomerSearchResponse:
      type: object
      description: |
        Response for customer search requests.
        Note: Only active (non-deleted) customers are included in results.
      required:
        - data
        - pagination
        - totalResults
      properties:
        data:
          type: array
          description: Search results - either flat rows or full customer objects based on format parameter
          items:
            oneOf:
              - $ref: '#/components/schemas/CustomerSearchRow'
              - $ref: '#/components/schemas/Customer'
            discriminator:
              propertyName: object
              mapping:
                CUSTOMER_SEARCH_ROW: '#/components/schemas/CustomerSearchRow'
                CUSTOMER: '#/components/schemas/Customer'
        pagination:
          $ref: '#/components/schemas/SearchPaginationInfo'
        totalResults:
          type: integer
          description: Total number of matching results (excluding soft-deleted records)
          minimum: 0
    CarrierSearchCriteria:
      type: object
      description: |
        Search criteria for filtering carriers.
        Note: Only active (non-deleted) carriers are searchable. Soft-deleted records are automatically excluded.
      properties:
        id:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Carrier ID (carrierProfileId for onboarded, goldenCarrierId otherwise)
        carrierProfileId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Profile ID for onboarded carriers only
        goldenCarrierId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Golden carrier ID from FMCSA data
        friendlyId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Account ID for onboarded carriers
        name:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Carrier company name
        carrierStatus:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Status within the system (pending, active, inactive, doNotUse, review)
        type:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Carrier type (TL, LTL, LINEHAUL, CARTAGE, AIR, OCEAN, RAIL)
        city:
          $ref: '#/components/schemas/TextSearchCriteria'
        market:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: DAT market
        zone:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: DAT zone
        primaryContactName:
          $ref: '#/components/schemas/TextSearchCriteria'
        primaryContactPhone:
          $ref: '#/components/schemas/TextSearchCriteria'
        primaryContactEmail:
          $ref: '#/components/schemas/TextSearchCriteria'
        fmcsaStatus:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: FMCSA status (active, inactive, no_docket)
        mcNumber:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Motor Carrier number
        dotNumber:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: DOT number
        einNumber:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Employer Identification Number
        safetyRating:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: FMCSA safety rating
        equipments:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Equipment types (VAN, REEFER, FLATBED, POWER_ONLY, SPECIALIZED, CONTAINER, TANKER)
        powerUnits:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of power units
        trucks:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of trucks
        monthsActiveAuthority:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Months of active authority
        highwayId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Highway ID
        highwayRulesAssessment:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Highway rules assessment
        rmisId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: RMIS ID
        rmisOperatingStatus:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: RMIS operating status
        rmisInvitationStatus:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: RMIS invitation status (ERROR, INVITED, SUCCESS)
        mcpStatus:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: MyCarrierPortal invite status
        mcpReviewStatus:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: MyCarrierPortal review status (e.g. ACCEPTABLE, MODERATE, UNACCEPTABLE, UNACCEPTABLE_REVIEW, UNACCEPTABLE_FAIL)
        quickbooksVendorId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: QuickBooks Online vendor ID (internal field qboVendorId)
        factorBankNames:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Factoring company names
        paymentTermName:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Payment term
        quickPayFee:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Quick pay discount rate
        accountOwnerId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Account owner user ID
        accountOwnerName:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Carrier owner name
        loadsCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of loads delivered
        totalMiles:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Total miles driven
        totalRevenue:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Total revenue generated
        totalCostOfGoodsSold:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Total COGS
        ratePerMile:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Average rate per mile
        quotesCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of quotes
        createdAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
          description: Onboarding date
    CarrierSearchRequest:
      type: object
      description: Request body for searching carriers
      properties:
        criteria:
          $ref: '#/components/schemas/CarrierSearchCriteria'
          description: Search criteria to filter carriers
        pagination:
          $ref: '#/components/schemas/SearchPaginationInput'
        sort:
          type: array
          items:
            $ref: '#/components/schemas/SearchSortOption'
          maxItems: 3
          description: Sort options for the search results
        savedSearch:
          $ref: '#/components/schemas/SavedSearchLookup'
          description: |
            Optional saved search to load preferences from.
            When provided, the saved search criteria will be loaded and merged with any explicit criteria.
        format:
          type: string
          enum:
            - flat
            - full
          default: flat
          description: |
            Response format:
            - flat: Returns only indexed fields (default, faster)
            - full: Returns complete carrier objects
    CarrierSearchRow:
      type: object
      description: |
        Flattened carrier data from search index.
        Includes both ONBOARDED carriers and FMCSA records.
      properties:
        object:
          type: string
          enum:
            - CARRIER_SEARCH_ROW
          description: Object type identifier for discriminating between flat and full response formats
        id:
          type: string
          format: uuid
          description: Carrier ID (carrierProfileId if onboarded, goldenCarrierId otherwise)
        carrierProfileId:
          type: string
          format: uuid
          description: Profile ID (only for onboarded carriers)
          nullable: true
        goldenCarrierId:
          type: string
          format: uuid
          description: Golden carrier ID from FMCSA
        friendlyId:
          type: string
          description: Account ID (only for onboarded carriers)
          nullable: true
        name:
          type: string
          description: Carrier company name
        carrierStatus:
          type: string
          enum:
            - pending
            - active
            - inactive
            - doNotUse
            - review
          description: Status (only for onboarded carriers)
          nullable: true
        type:
          type: string
          enum:
            - TL
            - LTL
            - LINEHAUL
            - CARTAGE
            - AIR
            - OCEAN
            - RAIL
          nullable: true
        city:
          type: string
          nullable: true
        market:
          type: string
          description: DAT market
          nullable: true
        zone:
          type: string
          description: DAT zone
          nullable: true
        primaryContactName:
          type: string
          nullable: true
        primaryContactPhone:
          type: string
          nullable: true
        primaryContactEmail:
          type: string
          format: email
          nullable: true
        fmcsaStatus:
          type: string
          enum:
            - active
            - inactive
            - no_docket
          nullable: true
        mcNumber:
          type: string
          nullable: true
        dotNumber:
          type: string
          nullable: true
        einNumber:
          type: string
          nullable: true
        safetyRating:
          type: string
          nullable: true
        equipments:
          type: array
          items:
            type: string
            enum:
              - VAN
              - REEFER
              - FLATBED
              - POWER_ONLY
              - SPECIALIZED
              - CONTAINER
              - TANKER
          description: Equipment types available
        powerUnits:
          type: integer
          nullable: true
        trucks:
          type: integer
          nullable: true
        monthsActiveAuthority:
          type: integer
          description: Months of active authority
          nullable: true
        highwayId:
          type: string
          nullable: true
        highwayRulesAssessment:
          type: string
          nullable: true
        rmisId:
          type: string
          nullable: true
        rmisOperatingStatus:
          type: string
          nullable: true
        rmisInvitationStatus:
          type: string
          enum:
            - ERROR
            - INVITED
            - SUCCESS
          nullable: true
        mcpStatus:
          type: string
          description: |
            MyCarrierPortal invite status. Open-ended passthrough from the MCP
            feed; commonly seen values include COMPLETE, INCOMPLETE, INVITED,
            IN_PROCESS, NOT_INVITED.
          nullable: true
        mcpReviewStatus:
          type: string
          description: |
            MyCarrierPortal risk assessment. Open-ended passthrough from the MCP
            feed; commonly seen values include ACCEPTABLE, MODERATE,
            UNACCEPTABLE, UNACCEPTABLE_REVIEW, UNACCEPTABLE_FAIL.
          nullable: true
        quickbooksVendorId:
          type: string
          description: QuickBooks Online vendor ID
          nullable: true
        factorBankNames:
          type: array
          items:
            type: string
          description: Factoring companies
        paymentTermName:
          type: string
          nullable: true
        quickPayFee:
          type: number
          format: float
          description: Quick pay discount rate
          nullable: true
        accountOwnerId:
          type: string
          format: uuid
          nullable: true
        accountOwnerName:
          type: string
          nullable: true
        loadsCount:
          type: integer
          description: Number of loads delivered
          nullable: true
        totalMiles:
          type: number
          format: float
          nullable: true
        totalRevenue:
          type: number
          format: float
          nullable: true
        totalCostOfGoodsSold:
          type: number
          format: float
          nullable: true
        ratePerMile:
          type: number
          format: float
          description: Average rate per mile
          nullable: true
        quotesCount:
          type: integer
          nullable: true
        createdAt:
          type: string
          format: date-time
          description: Onboarding date
          nullable: true
      required:
        - object
        - id
        - goldenCarrierId
        - name
    CarrierSearchResponse:
      type: object
      description: |
        Response for carrier search requests.
        Note: Only active (non-deleted) carriers are included in results.
      required:
        - data
        - pagination
        - totalResults
      properties:
        data:
          type: array
          description: Search results - either flat rows or full carrier objects based on format parameter
          items:
            oneOf:
              - $ref: '#/components/schemas/CarrierSearchRow'
              - $ref: '#/components/schemas/Carrier'
            discriminator:
              propertyName: object
              mapping:
                CARRIER_SEARCH_ROW: '#/components/schemas/CarrierSearchRow'
                CARRIER: '#/components/schemas/Carrier'
        pagination:
          $ref: '#/components/schemas/SearchPaginationInfo'
        totalResults:
          type: integer
          description: Total number of matching results (excluding soft-deleted records)
          minimum: 0
    VendorSearchCriteria:
      type: object
      description: |
        Search criteria for filtering vendors.
        Note: Only active (non-deleted) vendors are searchable. Soft-deleted records are automatically excluded.
      properties:
        id:
          $ref: '#/components/schemas/UUIDSearchCriteria'
        friendlyId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Vendor ID
        name:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Vendor name
        status:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Status (active, inactive, do_not_use)
        service:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Services provided by the vendor
        taxId:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: EIN or other tax ID
        location:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Computed field "city, state"
        city:
          $ref: '#/components/schemas/TextSearchCriteria'
        state:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        zip:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Postal code
        country:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        primaryContactName:
          $ref: '#/components/schemas/TextSearchCriteria'
        primaryContactEmail:
          $ref: '#/components/schemas/TextSearchCriteria'
        primaryContactPhone:
          $ref: '#/components/schemas/TextSearchCriteria'
        paymentTermName:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        quickbooksVendorId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: QuickBooks Online vendor ID (internal field qboVendorId)
        numberOfTimesUsed:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of times vendor was used
        lastUsed:
          $ref: '#/components/schemas/DateSearchCriteria'
          description: Last date vendor was used
        createdAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
    VendorSearchRequest:
      type: object
      description: Request body for searching vendors
      properties:
        criteria:
          $ref: '#/components/schemas/VendorSearchCriteria'
          description: Search criteria to filter vendors
        pagination:
          $ref: '#/components/schemas/SearchPaginationInput'
        sort:
          type: array
          items:
            $ref: '#/components/schemas/SearchSortOption'
          maxItems: 3
          description: Sort options for the search results
        savedSearch:
          $ref: '#/components/schemas/SavedSearchLookup'
          description: |
            Optional saved search to load preferences from.
            When provided, the saved search criteria will be loaded and merged with any explicit criteria.
        format:
          type: string
          enum:
            - flat
            - full
          default: flat
          description: |
            Response format:
            - flat: Returns only indexed fields (default, faster)
            - full: Returns complete vendor objects
    VendorSearchRow:
      type: object
      description: |
        Flattened vendor data from search index.
        Note: This represents only active vendors. Soft-deleted records are never returned.
      properties:
        object:
          type: string
          enum:
            - VENDOR_SEARCH_ROW
          description: Object type identifier for discriminating between flat and full response formats
        id:
          type: string
          format: uuid
        friendlyId:
          type: string
          description: Vendor ID
        name:
          type: string
        status:
          type: string
          enum:
            - active
            - inactive
            - do_not_use
          nullable: true
        taxId:
          type: string
          description: EIN or other tax ID
          nullable: true
        service:
          type: array
          items:
            type: string
          description: Services provided
        location:
          type: string
          description: Computed as "city, state"
          nullable: true
        city:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        zip:
          type: string
          description: Postal code
          nullable: true
        country:
          type: string
          nullable: true
        primaryContactName:
          type: string
          nullable: true
        primaryContactEmail:
          type: string
          format: email
          nullable: true
        primaryContactPhone:
          type: string
          nullable: true
        paymentTermName:
          type: string
          nullable: true
        quickbooksVendorId:
          type: string
          description: QuickBooks Online vendor ID
          nullable: true
        numberOfTimesUsed:
          type: integer
          description: Number of times used
        lastUsed:
          type: string
          format: date
          description: Last date used
          nullable: true
        createdAt:
          type: string
          format: date-time
      required:
        - object
        - id
        - friendlyId
        - name
        - numberOfTimesUsed
        - createdAt
    VendorSearchResponse:
      type: object
      description: |
        Response for vendor search requests.
        Note: Only active (non-deleted) vendors are included in results.
      required:
        - data
        - pagination
        - totalResults
      properties:
        data:
          type: array
          description: Search results - either flat rows or full vendor objects based on format parameter
          items:
            oneOf:
              - $ref: '#/components/schemas/VendorSearchRow'
              - $ref: '#/components/schemas/Vendor'
            discriminator:
              propertyName: object
              mapping:
                VENDOR_SEARCH_ROW: '#/components/schemas/VendorSearchRow'
                VENDOR: '#/components/schemas/Vendor'
        pagination:
          $ref: '#/components/schemas/SearchPaginationInfo'
        totalResults:
          type: integer
          description: Total number of matching results (excluding soft-deleted records)
          minimum: 0
    UserSearchCriteria:
      type: object
      description: |
        Search criteria for filtering users.
        Note: Only active (non-deleted) users are searchable. Soft-deleted records are automatically excluded.
      properties:
        id:
          $ref: '#/components/schemas/UUIDSearchCriteria'
        name:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: User name
        email:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Email address
        emailVerified:
          $ref: '#/components/schemas/BooleanSearchCriteria'
          description: Whether email is verified
        phone:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Phone number
        status:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Status (pending, active, inactive)
        roles:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: User roles
        visibility:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Visibility level (ALL, LIMITED)
        teamIds:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Team IDs (internal field groupIds)
        teamNames:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Team names (internal field groupNames)
        customersCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of customers (internal field shippersCount)
        quotesCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of quotes
        quotesWon:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of quotes won
        quoteWinRate:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Quote win rate percentage
        ordersCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of shipments
        ordersTotalRevenue:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Total shipment revenue
        ordersTotalTransportationCost:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Total shipment transportation cost
        ordersTotalGrossProfit:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Total shipment gross profit
        averageGrossProfitPerOrder:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Average gross profit per shipment
        carriersCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of carriers
        createdAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
        lastInvitedAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
          description: When the user was last invited
    UserSearchRequest:
      type: object
      description: Request body for searching users
      properties:
        criteria:
          $ref: '#/components/schemas/UserSearchCriteria'
          description: Search criteria to filter users
        pagination:
          $ref: '#/components/schemas/SearchPaginationInput'
        sort:
          type: array
          items:
            $ref: '#/components/schemas/SearchSortOption'
          maxItems: 3
          description: Sort options for the search results
        savedSearch:
          $ref: '#/components/schemas/SavedSearchLookup'
          description: |
            Optional saved search to load preferences from.
            When provided, the saved search criteria will be loaded and merged with any explicit criteria.
        format:
          type: string
          enum:
            - flat
            - full
          default: flat
          description: |
            Response format:
            - flat: Returns only indexed fields (default, faster)
            - full: Returns complete user objects
    UserSearchRow:
      type: object
      description: |
        Flattened user data from search index.
        Note: This represents only active users. Soft-deleted records are never returned.
      properties:
        object:
          type: string
          enum:
            - USER_SEARCH_ROW
          description: Object type identifier for discriminating between flat and full response formats
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          format: email
        emailVerified:
          type: boolean
          description: Whether email is verified
        phone:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - pending
            - active
            - inactive
        roles:
          type: array
          items:
            type: string
          description: User roles
        visibility:
          type: string
          enum:
            - ALL
            - LIMITED
          nullable: true
        teamIds:
          type: array
          items:
            type: string
            format: uuid
          description: Team IDs (maps from groupIds)
        teamNames:
          type: array
          items:
            type: string
          description: Team names (maps from groupNames)
        customersCount:
          type: integer
          description: Number of customers (maps from shippersCount)
        quotesCount:
          type: integer
          nullable: true
        quotesWon:
          type: integer
          nullable: true
        quoteWinRate:
          type: number
          format: float
          description: Win rate percentage
          nullable: true
        ordersCount:
          type: integer
          description: Number of shipments
        ordersTotalRevenue:
          type: number
          format: float
          description: Total shipment revenue
        ordersTotalTransportationCost:
          type: number
          format: float
          description: Total transportation cost
        ordersTotalGrossProfit:
          type: number
          format: float
          description: Total gross profit
        averageGrossProfitPerOrder:
          type: number
          format: float
          description: Average gross profit per shipment
          nullable: true
        carriersCount:
          type: integer
          description: Number of carriers
        createdAt:
          type: string
          format: date-time
        lastInvitedAt:
          type: string
          format: date-time
          nullable: true
      required:
        - object
        - id
        - name
        - email
        - emailVerified
        - status
        - customersCount
        - ordersCount
        - ordersTotalRevenue
        - ordersTotalTransportationCost
        - ordersTotalGrossProfit
        - carriersCount
        - createdAt
    UserSearchResponse:
      type: object
      description: |
        Response for user search requests.
        Note: Only active (non-deleted) users are included in results.
      required:
        - data
        - pagination
        - totalResults
      properties:
        data:
          type: array
          description: Search results - either flat rows or full user objects based on format parameter
          items:
            oneOf:
              - $ref: '#/components/schemas/UserSearchRow'
              - $ref: '#/components/schemas/User'
            discriminator:
              propertyName: object
              mapping:
                USER_SEARCH_ROW: '#/components/schemas/UserSearchRow'
                USER: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/SearchPaginationInfo'
        totalResults:
          type: integer
          description: Total number of matching results (excluding soft-deleted records)
          minimum: 0
    LocationSearchCriteria:
      type: object
      description: |
        Search criteria for filtering locations (shipper/receiver locations).
        Note: Only active (non-deleted) locations are searchable. Soft-deleted records are automatically excluded.
      properties:
        id:
          $ref: '#/components/schemas/UUIDSearchCriteria'
        customerId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Customer ID (internal field shipperProfileId)
        customerName:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Customer name (internal field shipperProfileName)
        customerFriendlyId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Customer company ID (internal field shipperProfileFriendlyId)
        type:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Location type (SHIPPER, RECEIVER, BOTH)
        name:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Location name
        externalId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: External reference ID
        line1:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Address line 1
        line2:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Address line 2
        city:
          $ref: '#/components/schemas/TextSearchCriteria'
        state:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        postalCode:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        country:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        market:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: DAT market
        zone:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: DAT zone
        phoneNumber:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Primary contact phone
        appointmentRequired:
          $ref: '#/components/schemas/BooleanSearchCriteria'
          description: Whether appointments are required (internal field apptReq)
        stopsCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of stops at this location
        createdAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
    LocationSearchRequest:
      type: object
      description: Request body for searching locations
      properties:
        criteria:
          $ref: '#/components/schemas/LocationSearchCriteria'
          description: Search criteria to filter locations
        pagination:
          $ref: '#/components/schemas/SearchPaginationInput'
        sort:
          type: array
          items:
            $ref: '#/components/schemas/SearchSortOption'
          maxItems: 3
          description: Sort options for the search results
        savedSearch:
          $ref: '#/components/schemas/SavedSearchLookup'
          description: |
            Optional saved search to load preferences from.
            When provided, the saved search criteria will be loaded and merged with any explicit criteria.
        format:
          type: string
          enum:
            - flat
            - full
          default: flat
          description: |
            Response format:
            - flat: Returns only indexed fields (default, faster)
            - full: Returns complete location objects
    LocationSearchRow:
      type: object
      description: |
        Flattened location data from search index.
        Note: This represents only active locations. Soft-deleted records are never returned.
      properties:
        object:
          type: string
          enum:
            - LOCATION_SEARCH_ROW
          description: Object type identifier for discriminating between flat and full response formats
        id:
          type: string
          format: uuid
        customerId:
          type: string
          format: uuid
          description: Customer ID (maps from shipperProfileId)
        customerName:
          type: string
          description: Customer name (maps from shipperProfileName)
        customerFriendlyId:
          type: string
          description: Customer company ID (maps from shipperProfileFriendlyId)
        type:
          type: string
          enum:
            - SHIPPER
            - RECEIVER
            - BOTH
          description: Location type
        name:
          type: string
          description: Location name
        externalId:
          type: string
          description: External reference ID
          nullable: true
        line1:
          type: string
          nullable: true
        line2:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        postalCode:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        market:
          type: string
          description: DAT market
          nullable: true
        zone:
          type: string
          description: DAT zone
          nullable: true
        point:
          type: object
          properties:
            lat:
              type: number
              format: float
            lon:
              type: number
              format: float
          description: Geographic coordinates
          nullable: true
        phoneNumber:
          type: string
          description: Primary contact phone
          nullable: true
        appointmentRequired:
          type: boolean
          description: Whether appointments are required (maps from apptReq)
          nullable: true
        stopsCount:
          type: integer
          description: Number of stops
          nullable: true
        createdAt:
          type: string
          format: date-time
      required:
        - object
        - id
        - customerId
        - customerName
        - name
        - createdAt
    LocationSearchResponse:
      type: object
      description: |
        Response for location search requests.
        Note: Only active (non-deleted) locations are included in results.
      required:
        - data
        - pagination
        - totalResults
      properties:
        data:
          type: array
          description: Search results - either flat rows or full location objects based on format parameter
          items:
            oneOf:
              - $ref: '#/components/schemas/LocationSearchRow'
              - $ref: '#/components/schemas/Location'
            discriminator:
              propertyName: object
              mapping:
                LOCATION_SEARCH_ROW: '#/components/schemas/LocationSearchRow'
                LOCATION: '#/components/schemas/Location'
        pagination:
          $ref: '#/components/schemas/SearchPaginationInfo'
        totalResults:
          type: integer
          description: Total number of matching results (excluding soft-deleted records)
          minimum: 0
    GlobalSearchObjectType:
      type: string
      enum:
        - SHIPMENT
        - CUSTOMER
        - CARRIER
        - USER
        - VENDOR
      description: |
        Object types available for global search:
        - `SHIPMENT`: Shipment records
        - `CUSTOMER`: Customer/shipper profiles
        - `CARRIER`: Carrier profiles
        - `USER`: User accounts
        - `VENDOR`: Vendor profiles
    GlobalSearchRequest:
      type: object
      description: Request body for global search across multiple entity types
      required:
        - query
      properties:
        query:
          type: string
          description: |
            Search query string. Searches across default searchable fields for each entity type.

            Supports prefix filtering using "type:query" syntax:
            - `carrier:acme` - searches only carriers for "acme"
            - `shipment:12345` - searches only shipments for "12345"
            - `user:john` - searches only users for "john"
          example: acme corp
        objects:
          type: array
          items:
            $ref: '#/components/schemas/GlobalSearchObjectType'
          description: |
            Optional filter to limit search to specific object types.
            If not provided, searches across all object types.
          example:
            - SHIPMENT
            - CUSTOMER
        pagination:
          $ref: '#/components/schemas/SearchPaginationInput'
    GlobalSearchRow:
      type: object
      description: |
        A single global search result row.
        Results are sorted by object type priority: SHIPMENT, CUSTOMER, CARRIER, USER, VENDOR.
      required:
        - object
        - id
        - entityName
        - title
        - field
      properties:
        object:
          $ref: '#/components/schemas/GlobalSearchObjectType'
          description: The type of object this result represents
        id:
          type: string
          format: uuid
          description: Unique identifier of the matched record
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier if set
          example: ERP-CUST-12345
          nullable: true
        entityName:
          type: string
          description: |
            Internal entity type name (for backwards compatibility).
            Prefer using the `object` field instead.
          example: SHIPPER_PROFILE
        title:
          type: string
          description: Primary display text for the result (e.g., name, friendlyId)
          example: Acme Corporation
        subtitle:
          type: string
          description: Secondary display text (varies by entity type)
          example: CUST-12345
          nullable: true
        field:
          type: string
          description: Name of the field that matched the search query
          example: Name
        highlight:
          type: string
          description: |
            Matched text with highlight markers.
            Contains HTML &lt;em&gt; tags around matched portions.
          example: <em>Acme</em> Corporation
          nullable: true
    GlobalSearchResponse:
      type: object
      description: Response for global search requests
      required:
        - data
        - pagination
        - totalResults
      properties:
        data:
          type: array
          description: |
            Search results sorted by object type priority:
            SHIPMENT → CUSTOMER → CARRIER → USER → VENDOR
          items:
            $ref: '#/components/schemas/GlobalSearchRow'
        pagination:
          $ref: '#/components/schemas/SearchPaginationInfo'
        totalResults:
          type: integer
          description: Total number of matching results across all object types
          minimum: 0
          example: 42
    ShipmentReferenceField:
      type: string
      enum:
        - BOL_NUMBER
        - PICKUP_NUMBER
        - DELIVERY_NUMBER
        - PURCHASE_ORDER_NUMBER
        - GENERAL_LEDGER_CODE
        - CUSTOMER_REFERENCE_NUMBER
        - PRO_NUMBER
        - ITEM_IDENTIFICATION
        - PART_NUMBER
        - ACCOUNT_NUMBER
        - CONSIGNEE_ACCOUNT_NUMBER
        - PICKUP_LOCATION_IDENTIFICATION
        - DELIVER_LOCATION_IDENTIFICATION
        - PRODUCT_IDENTIFICATION
        - OTHER_IDENTIFICATION
        - CONTAINER_NUMBER
        - MACROPOINT_REFERENCE_NUMBER
        - DROP_TRAILER_NUMBER
        - APPOINTMENT_NUMBER
        - MASTER_BILL_OF_LADING_NUMBER
        - HOUSE_BILL_OF_LADING_NUMBER
        - LOCATION_IDENTIFICATION
        - TENDER_METHOD
        - ROUTE_NUMBER
        - SHOW_DECORATOR_NAME
        - SHOW_BOOTH_NUMBER
        - CARE_OF
        - TENDER_ID
        - ORDER_NUMBER
        - SHOW_NAME
        - AES_ITN
        - FIRMS_CODE
        - IT_NUMBER
        - JOB_NUMBER
        - TMS_ID
        - MASTER_AIRWAYBILL_NUMBER
        - HOUSE_AIRWAYBILL_NUMBER
        - AMS_HOUSE_BILL_OF_LADING_NUMBER
        - QUOTE_NUMBER
        - BOOKING_NUMBER
        - PAPS_NUMBER
        - PARS_NUMBER
        - INTERNAL_ID
        - LOT_NUMBER
      description: |
        Reference field types for shipment tracking.

        Common field types:
        - `BOL_NUMBER`: Bill of Lading Number
        - `PRO_NUMBER`: PRO Number (carrier tracking number)
        - `PURCHASE_ORDER_NUMBER`: Purchase Order Number
        - `CUSTOMER_REFERENCE_NUMBER`: Customer Reference Number
        - `CONTAINER_NUMBER`: Container Number
        - `MASTER_BILL_OF_LADING_NUMBER`: Master Bill of Lading Number
        - `HOUSE_BILL_OF_LADING_NUMBER`: House Bill of Lading Number
        - `MASTER_AIRWAYBILL_NUMBER`: Master Airway Bill Number
        - `HOUSE_AIRWAYBILL_NUMBER`: House Airway Bill Number

        Additional field types:
        - `PICKUP_NUMBER`: Pickup Number
        - `DELIVERY_NUMBER`: Delivery Number
        - `GENERAL_LEDGER_CODE`: GL Code
        - `ITEM_IDENTIFICATION`: Item ID
        - `PART_NUMBER`: Part Number
        - `ACCOUNT_NUMBER`: Account Number
        - `CONSIGNEE_ACCOUNT_NUMBER`: Consignee Account Number
        - `PICKUP_LOCATION_IDENTIFICATION`: Pickup Location ID
        - `DELIVER_LOCATION_IDENTIFICATION`: Delivery Location ID
        - `PRODUCT_IDENTIFICATION`: Product ID
        - `OTHER_IDENTIFICATION`: Other ID
        - `MACROPOINT_REFERENCE_NUMBER`: MacroPoint Reference Number
        - `DROP_TRAILER_NUMBER`: Drop Trailer Number
        - `APPOINTMENT_NUMBER`: Appointment Number
        - `LOCATION_IDENTIFICATION`: Location ID
        - `TENDER_METHOD`: Tender Method
        - `ROUTE_NUMBER`: Route Number
        - `SHOW_DECORATOR_NAME`: Show Decorator Name
        - `SHOW_BOOTH_NUMBER`: Show Booth Number
        - `CARE_OF`: Care Of
        - `TENDER_ID`: EDI Tender ID
        - `ORDER_NUMBER`: Order Number
        - `SHOW_NAME`: Show Name
        - `AES_ITN`: AES ITN (Automated Export System Internal Transaction Number)
        - `FIRMS_CODE`: FIRMS Code (Facility Information and Resources Management System)
        - `IT_NUMBER`: IT Number (Immediate Transportation)
        - `JOB_NUMBER`: Job Number
        - `TMS_ID`: TMS ID
        - `AMS_HOUSE_BILL_OF_LADING_NUMBER`: AMS House Bill of Lading Number
        - `QUOTE_NUMBER`: Quote Number
        - `BOOKING_NUMBER`: Booking Number
        - `PAPS_NUMBER`: PAPS Number
        - `PARS_NUMBER`: PARS Number
        - `INTERNAL_ID`: Internal ID
        - `LOT_NUMBER`: Lot Number
    ShipmentTrackSearch:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          minLength: 4
          maxLength: 255
          description: Reference value to search for (minimum 4 characters)
          example: MAWB123456
    ShipmentTrackRequest:
      type: object
      required:
        - searches
      properties:
        searches:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/ShipmentTrackSearch'
          description: |
            Array of search queries. Results are returned in the same order as the input searches.
            Maximum 100 searches per request.
        referenceFields:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentReferenceField'
          description: |
            Optional filter for reference field types to search.
            If omitted, searches all reference field types.

            Common use: limit search to specific field types for faster results
            or to avoid false matches across different reference types.
          example:
            - MASTER_AIRWAYBILL_NUMBER
            - BOL_NUMBER
            - PRO_NUMBER
      example:
        searches:
          - query: MAWB123456
          - query: BOL789
        referenceFields:
          - MASTER_AIRWAYBILL_NUMBER
          - BOL_NUMBER
    ShipmentTrackResult:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: Original search query (always present, even when no match found)
          example: MAWB123456
        id:
          type: string
          format: uuid
          description: Shipment UUID (null if not found)
          example: 550e8400-e29b-41d4-a716-446655440000
          nullable: true
        key:
          type: string
          maxLength: 512
          description: Client-defined key (null if not found or not set)
          example: SHIP-001
          nullable: true
        friendlyId:
          type: string
          description: Human-readable shipment ID (null if not found)
          example: SHP-12345
          nullable: true
        status:
          description: Current shipment status (null if not found)
          example: IN_TRANSIT
          $ref: '#/components/schemas/ShipmentStatus'
          nullable: true
        field:
          description: Reference field type that matched the query (null if not found)
          $ref: '#/components/schemas/ShipmentReferenceField'
          nullable: true
        value:
          type: string
          description: The actual value stored in the matched reference field (null if not found)
          example: MAWB123456
          nullable: true
        origin:
          type: string
          description: |
            Origin city, state/region, and zip code (null if not found).
            Format: "City, ST" or "City, ST ZIP" if zip code is available.
          example: Los Angeles, CA 90210
          nullable: true
        destination:
          type: string
          description: |
            Destination city, state/region, and zip code (null if not found).
            Format: "City, ST" or "City, ST ZIP" if zip code is available.
          example: New York, NY 10001
          nullable: true
        pickUpDate:
          type: string
          format: date
          description: |
            Scheduled or actual pickup date in ISO 8601 date format (YYYY-MM-DD).
            Null if not found or not set.
          example: '2025-01-15'
          nullable: true
        deliveryDate:
          type: string
          format: date
          description: |
            Scheduled or actual delivery date in ISO 8601 date format (YYYY-MM-DD).
            Null if not found or not set.
          example: '2025-01-20'
          nullable: true
        trackingUrl:
          type: string
          format: uri
          description: |
            Direct URL to view shipment details in MVMNT (null if not found).
            Uses the organization's configured domain or defaults to app.mvmnt.io.
          example: https://app.mvmnt.io/shipments/550e8400-e29b-41d4-a716-446655440000
          nullable: true
        truckerToolsUrl:
          type: string
          format: uri
          description: |
            Direct link to the Trucker Tools tracking page for the shipment's
            load, when live tracking is active. The MVMNT `trackingUrl` embeds
            the same map plus shipment milestones; use this one only if you want
            the raw Trucker Tools view.
          nullable: true
    ShipmentTrackResponse:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentTrackResult'
          description: |
            Array of tracking results in the same order as input searches.

            Each result contains the original query plus matching shipment data.
            If no match is found, only the `query` field is populated (all other fields are null).

            If multiple shipments match a query, the most recently created shipment is returned.
      example:
        results:
          - query: MAWB123456
            id: 550e8400-e29b-41d4-a716-446655440000
            key: SHIP-001
            friendlyId: SHP-12345
            status: IN_TRANSIT
            field: MASTER_AIRWAYBILL_NUMBER
            value: MAWB123456
            origin: Los Angeles, CA 90210
            destination: New York, NY 10001
            pickUpDate: '2025-01-15'
            deliveryDate: '2025-01-20'
            trackingUrl: https://app.mvmnt.io/shipments/550e8400-e29b-41d4-a716-446655440000
          - query: NOTFOUND123
            id: null
            key: null
            friendlyId: null
            status: null
            field: null
            value: null
            origin: null
            destination: null
            pickUpDate: null
            deliveryDate: null
            trackingUrl: null
    DocumentType:
      type: string
      enum:
        - INVOICE
        - BILL_OF_LADING
        - RATE_CON
        - PROOF_OF_DELIVERY
        - CERTIFICATE_OF_INSURANCE
        - W9
        - CARRIER_INVOICE
        - LUMPER_RECEIPT
        - DETENTION
        - DELIVERY_ORDER
        - LOAD_TENDER
        - HOUSE_AIRWAY_BILL
        - MASTER_AIRWAY_BILL
        - QUOTE
        - AIR_CARGO_MANIFEST
        - AIR_CHUTE
        - AIR_FREIGHT_DEPARTURE_CARTAGE_ADVICE_WITH_RECEIPT
        - AUTHORITY
        - AUTHORITY_TO_MAKE_ENTRY
        - BROKER_CARRIER_AGREEMENT
        - COI_AUTO
        - COI_BIPD
        - COI_CARGO
        - COMMERCIAL_DRIVERS_LICENSE
        - COMMERCIAL_INVOICE
        - CUSTOMER_ACCESSORIAL_SCHEDULE
        - CUSTOMER_AGREEMENT
        - CUSTOMER_AWARDED_BIDS
        - CUSTOMER_AWARDED_RATES_LANES
        - CUSTOMER_CREDIT_REPORT
        - DELIVERY_ALERT
        - FACTOR_NOTICE_OF_ASSIGNMENT
        - FREIGHT_BILL
        - FUEL_RECEIPT
        - GBL
        - HOUSE_AIRWAY_BILL_LABEL
        - HOUSE_AIRWAY_BILL_LABEL_MULTI
        - IAC_CERTIFICATION
        - INTERNATIONAL_HOUSE_AIRWAY_BILL
        - INTERNATIONAL_MASTER_AIRWAY_BILL
        - LOAD_SUMMARY
        - LOG
        - LOGO
        - LOGO_DOC
        - LOGO_RECTANGLE
        - PACKING_LIST
        - PHOTOGRAPH
        - PROOF_OF_PERFORMANCE
        - REEFER_KEYPAD
        - ROUTING_ALERT
        - SCALE_RECEIPT
        - SEAL
        - SHIPPING_LABEL
        - SIDE_OF_TRUCK
        - SIGNED_CARRIER_AGREEMENT
        - TRIP_SHEET
        - OTHER
      description: |
        Type of document.

        Common types:
        - `INVOICE`: Customer invoice
        - `BILL_OF_LADING`: Bill of lading document
        - `RATE_CON`: Rate confirmation
        - `PROOF_OF_DELIVERY`: Proof of delivery (POD)
        - `CERTIFICATE_OF_INSURANCE`: Certificate of insurance (COI)
        - `W9`: W-9 tax form
        - `CARRIER_INVOICE`: Carrier invoice/bill
        - `LUMPER_RECEIPT`: Lumper receipt
        - `DETENTION`: Detention documentation
        - `DELIVERY_ORDER`: Delivery order
        - `LOAD_TENDER`: Load tender
        - `HOUSE_AIRWAY_BILL`: House airway bill (HAWB)
        - `MASTER_AIRWAY_BILL`: Master airway bill (MAWB)
        - `QUOTE`: Quote document
        - `OTHER`: Other document type

        The remaining values mirror the document types available in the MVMNT
        TMS UI (carrier compliance, air freight, customer agreements, receipts,
        alerts, and branding assets).

        Values outside this list are rejected with 400. Documents created
        internally with other types are returned as `OTHER`.
    DocumentStatus:
      type: string
      enum:
        - PENDING_UPLOAD
        - UPLOADED
      description: |
        Upload status of the document.
        - `PENDING_UPLOAD`: Document record created, file not yet uploaded
        - `UPLOADED`: File has been uploaded to storage
    Document:
      type: object
      required:
        - id
        - type
        - fileName
        - contentType
        - status
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the document
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          maxLength: 512
          description: Client-defined key for external reference
          example: doc-inv-2025-001
          nullable: true
        type:
          $ref: '#/components/schemas/DocumentType'
        fileName:
          type: string
          description: Original file name
          example: invoice-2025-001.pdf
        extension:
          type: string
          description: File extension (without dot)
          example: pdf
        contentType:
          type: string
          description: MIME content type
          example: application/pdf
        fileSize:
          type: integer
          description: File size in bytes
          example: 102400
          nullable: true
        status:
          $ref: '#/components/schemas/DocumentStatus'
        uploadUrl:
          type: string
          format: uri
          description: |
            Pre-signed URL for uploading the file.
            Only present immediately after document creation.
            Expires after 15 minutes.
          example: https://s3.amazonaws.com/bucket/key?signature=...
          nullable: true
        downloadUrl:
          type: string
          format: uri
          description: |
            Pre-signed URL for downloading the file.
            Present when document status is UPLOADED.
            Expires after 1 hour.
          example: https://s3.amazonaws.com/bucket/key?signature=...
          nullable: true
        tags:
          type: object
          additionalProperties: true
          description: Arbitrary key-value tags for the document
          example:
            invoiceNumber: INV-2025-001
            customerPO: PO-12345
          nullable: true
        createdAt:
          type: string
          format: date-time
          description: When the document was created
          example: '2025-01-15T10:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the document was last updated
          example: '2025-01-15T10:35:00Z'
          nullable: true
    DocumentInput:
      type: object
      required:
        - type
        - fileName
        - contentType
      properties:
        key:
          type: string
          maxLength: 512
          description: Optional client-defined key for external reference
          example: doc-inv-2025-001
        type:
          $ref: '#/components/schemas/DocumentType'
        fileName:
          type: string
          minLength: 1
          maxLength: 255
          description: File name (including extension)
          example: invoice-2025-001.pdf
        contentType:
          type: string
          description: MIME content type of the file
          example: application/pdf
        fileSize:
          type: integer
          minimum: 1
          description: File size in bytes (optional, for validation)
          example: 102400
        tags:
          type: object
          additionalProperties: true
          description: Optional key-value tags
          example:
            invoiceNumber: INV-2025-001
    DocumentPatch:
      type: object
      description: |
        Partial document update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        key:
          type: string
          maxLength: 512
          description: Update client-defined key
          nullable: true
        type:
          $ref: '#/components/schemas/DocumentType'
        fileName:
          type: string
          minLength: 1
          maxLength: 255
          description: Update file name
        tags:
          type: object
          additionalProperties: true
          description: Update or clear tags (null to clear)
          nullable: true
    DocumentFilter:
      type: object
      properties:
        entityType:
          $ref: '#/components/schemas/DocumentEntityType'
        entityId:
          type: string
          format: uuid
          description: |
            Scope results to documents attached to this entity. Must be provided
            together with `entityType`. Must appear at the top level of the
            filter (not nested inside `or` or `not` clauses). Combines with the
            other filter fields (they apply on top of the entity scope).
        id:
          $ref: '#/components/schemas/UUIDFilter'
        type:
          $ref: '#/components/schemas/DocumentTypeFilter'
        status:
          $ref: '#/components/schemas/DocumentStatusFilter'
        fileName:
          $ref: '#/components/schemas/StringFilter'
        contentType:
          $ref: '#/components/schemas/StringFilter'
        extension:
          $ref: '#/components/schemas/StringFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        and:
          type: array
          items:
            $ref: '#/components/schemas/DocumentFilter'
        or:
          type: array
          items:
            $ref: '#/components/schemas/DocumentFilter'
        not:
          $ref: '#/components/schemas/DocumentFilter'
      description: Filter criteria for documents
    DocumentFilterRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/DocumentFilter'
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor from previous response
      description: Request body for filtering documents
    QuoteStatus:
      type: string
      enum:
        - CREATED
        - NOT_A_QUOTE
        - DRAFT
        - REQUESTED
        - QUOTED
        - RECEIVED_REPLY
        - SENT_REPLY
        - RECEIVED_COUNTER
        - SENT_COUNTER
        - WON
        - LOST
        - PASS
        - CANCELED
      description: |
        Current status in the quote lifecycle.

        Initial states:
        - `CREATED`: Quote being built (not yet drafted)
        - `NOT_A_QUOTE`: Marked as not an actual quote
        - `DRAFT`: Quote being drafted
        - `REQUESTED`: Customer requested a quote (needs pricing)

        Active states:
        - `QUOTED`: Price sent to customer
        - `RECEIVED_REPLY`: Received reply from customer
        - `SENT_REPLY`: Sent reply to customer
        - `RECEIVED_COUNTER`: Received counter-offer
        - `SENT_COUNTER`: Sent counter-offer

        Final states:
        - `WON`: Customer accepted the quote
        - `LOST`: Quote not accepted
        - `PASS`: Broker declined to quote
        - `CANCELED`: Quote canceled
    QuoteSide:
      type: string
      enum:
        - SELL
        - BUY
      description: |
        Quote direction.
        - `SELL`: Selling to shipper (customer quote)
        - `BUY`: Buying from carrier (carrier quote)
    QuoteLostReason:
      type: string
      enum:
        - EXPIRED
        - NO_REASON
        - NO_RESPONSE
        - TOO_HIGH
        - TOO_SLOW
        - TRUCK_NOT_AVAILABLE
        - WITHDRAWN
        - OTHER
      description: |
        Reason why the quote was lost.
        - `EXPIRED`: Quote expired without response
        - `NO_REASON`: No specific reason given
        - `NO_RESPONSE`: Customer didn't respond
        - `TOO_HIGH`: Price was too high
        - `TOO_SLOW`: Response was too slow
        - `TRUCK_NOT_AVAILABLE`: Capacity not available
        - `WITHDRAWN`: The offer was withdrawn before it was accepted
        - `OTHER`: Other reason (see lostReasonText)
    TransportMode:
      type: string
      enum:
        - FTL
        - TL
        - LTL
        - PTL
        - RLTL
        - AIR
        - OCEAN
        - RAIL
        - INTERMODAL
        - DRAYAGE
        - AUTO
        - EXPEDITED_AIR
        - EXPEDITED_GROUND
      description: |
        Transportation mode. Optional on write — a shipment or load created
        without one is stored with no mode, the same as one created in the TMS.
        - `FTL`: Full Truckload — the value the TMS stores and always returns
        - `TL`: legacy spelling of `FTL`, still accepted on write, never returned
        - `LTL`: Less than Truckload
        - `PTL`: Partial Truckload
        - `RLTL`: Retail LTL
        - `AUTO`: Auto transport
        - `EXPEDITED_AIR`: Expedited air
        - `EXPEDITED_GROUND`: Expedited ground
        - `AIR`: Air freight
        - `OCEAN`: Ocean freight
        - `RAIL`: Rail freight
        - `INTERMODAL`: Intermodal (multiple modes)
        - `DRAYAGE`: Drayage/cartage
    OrderInput:
      type: object
      required:
        - stops
        - mode
      properties:
        mode:
          $ref: '#/components/schemas/TransportMode'
        stops:
          type: array
          items:
            $ref: '#/components/schemas/OrderStopInput'
          minItems: 2
          description: At least origin and destination stops
        freight:
          $ref: '#/components/schemas/OrderFreightInput'
        equipment:
          type: array
          items:
            $ref: '#/components/schemas/ResourceReferenceInput'
          description: Equipment types required
        references:
          type: array
          items:
            type: object
            required:
              - type
              - value
            properties:
              type:
                type: string
                description: Reference type (e.g., BOL_NUMBER, PO_NUMBER)
              value:
                type: string
                description: Reference value
          description: Reference numbers for the order
        specialRequirements:
          type: array
          items:
            $ref: '#/components/schemas/ResourceReferenceInput'
          description: Special requirements (e.g., liftgate, team drivers)
      description: |
        Order definition used when creating Quotes or Shipments.
        Contains route (stops), freight details, and requirements.
    OrderStopInput:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - PICKUP
            - DELIVERY
          description: Type of stop
        location:
          $ref: '#/components/schemas/ResourceReferenceInput'
          description: Reference to an existing location
        address:
          $ref: '#/components/schemas/AddressInput'
          description: Address for ad-hoc stop (if no location reference)
        requestedStartDate:
          type: string
          format: date
          description: Requested start date for the stop
        requestedEndDate:
          type: string
          format: date
          description: Requested end date for the stop
        requestedStartTime:
          type: string
          pattern: ^([01]\d|2[0-3]):([0-5]\d)$
          description: Requested start time (HH:MM format)
        requestedEndTime:
          type: string
          pattern: ^([01]\d|2[0-3]):([0-5]\d)$
          description: Requested end time (HH:MM format)
        appointmentRequired:
          type: boolean
          default: false
          description: Whether an appointment is required
        notes:
          type: string
          maxLength: 2000
          description: Special instructions for the stop
      description: Stop definition for an order
    OrderFreightInput:
      type: object
      properties:
        handlingUnitQuantity:
          type: integer
          minimum: 1
          description: Number of handling units
        handlingUnitType:
          type: string
          description: |
            Handling unit name. Org-configurable list (e.g. Pallet, Skid, Crate,
            Drum, Roll, Gaylord, Totes) — not a closed enum; match the names your
            organization uses in the TMS.
        weight:
          type: number
          minimum: 0
          description: Total weight in pounds
        volume:
          type: number
          minimum: 0
          description: |
            Total volume in cubic feet. Accepted for compatibility but not
            currently persisted.
        length:
          type: number
          minimum: 0
          description: Length in inches
        width:
          type: number
          minimum: 0
          description: Width in inches
        height:
          type: number
          minimum: 0
          description: Height in inches
        commodityDescription:
          type: string
          maxLength: 500
          description: Description of the commodity
        hazmat:
          type: boolean
          default: false
          description: Whether freight is hazardous materials
        stackable:
          type: boolean
          default: true
          description: Whether freight is stackable
      description: Freight details for an order
    Quote:
      type: object
      required:
        - id
        - friendlyId
        - side
        - status
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        friendlyId:
          type: string
          description: Human-readable quote ID (e.g., "Q003602")
          example: Q003602
        key:
          type: string
          description: Client-defined reference identifier for this quote
          example: my-quote-001
          nullable: true
        side:
          $ref: '#/components/schemas/QuoteSide'
        status:
          $ref: '#/components/schemas/QuoteStatus'
        amount:
          type: number
          description: Quoted price
          example: 2500
          nullable: true
        target:
          type: number
          description: Target price for margin calculation
          example: 2200
          nullable: true
        margin:
          type: number
          description: Calculated margin percentage
          example: 12
          nullable: true
        expiresAt:
          type: string
          format: date-time
          description: Quote expiration timestamp
          nullable: true
        customer:
          $ref: '#/components/schemas/CustomerReference'
          description: Customer (for SELL quotes)
        carrier:
          $ref: '#/components/schemas/CarrierReference'
          description: Carrier (for BUY quotes)
        order:
          $ref: '#/components/schemas/OrderSummary'
          description: Order details (route, freight)
        lostReason:
          description: Why the quote was lost
          $ref: '#/components/schemas/QuoteLostReason'
          nullable: true
        lostReasonText:
          type: string
          description: Additional text for lost reason
          nullable: true
        closedTime:
          type: string
          format: date-time
          description: When the quote was closed (won/lost)
          nullable: true
        assignee:
          $ref: '#/components/schemas/UserReference'
          description: Assigned sales rep
        shipmentId:
          type: string
          format: uuid
          description: Shipment ID if converted
          nullable: true
        shipmentKey:
          type: string
          description: Shipment friendly ID if converted
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          nullable: true
    QuoteInput:
      type: object
      required:
        - customer
        - order
      properties:
        customer:
          $ref: '#/components/schemas/ResourceReferenceInput'
          description: Customer reference (for SELL quotes)
        carrier:
          $ref: '#/components/schemas/ResourceReferenceInput'
          description: Carrier reference (for BUY quotes)
        order:
          $ref: '#/components/schemas/OrderInput'
          description: Order details (route, freight)
        amount:
          type: number
          minimum: 0
          description: Quoted price
        expiresAt:
          type: string
          format: date-time
          description: Quote expiration
        assignee:
          $ref: '#/components/schemas/ResourceReferenceInput'
          description: Assigned user
      description: Input for creating a new quote
    QuotePatch:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/QuoteStatus'
        amount:
          type: number
          minimum: 0
          nullable: true
        target:
          type: number
          minimum: 0
          nullable: true
        expiresAt:
          type: string
          format: date-time
          nullable: true
        lostReason:
          $ref: '#/components/schemas/QuoteLostReason'
          description: Required when status is LOST
        lostReasonText:
          type: string
          description: Required when lostReason is OTHER
        assignee:
          $ref: '#/components/schemas/ResourceReferenceInput'
      description: |
        Partial update fields for a quote.

        **Validation rules:**
        - When `status` is `LOST`, `lostReason` is required
        - When `lostReason` is `OTHER`, `lostReasonText` is required
    QuoteFilter:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUIDFilter'
        status:
          $ref: '#/components/schemas/QuoteStatusFilter'
        side:
          $ref: '#/components/schemas/QuoteSideFilter'
        customerId:
          $ref: '#/components/schemas/UUIDFilter'
        carrierId:
          $ref: '#/components/schemas/UUIDFilter'
        assigneeId:
          $ref: '#/components/schemas/UUIDFilter'
        amount:
          $ref: '#/components/schemas/FloatFilter'
        expiresAt:
          $ref: '#/components/schemas/DatetimeFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        and:
          type: array
          items:
            $ref: '#/components/schemas/QuoteFilter'
        or:
          type: array
          items:
            $ref: '#/components/schemas/QuoteFilter'
        not:
          $ref: '#/components/schemas/QuoteFilter'
    QuoteFilterRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/QuoteFilter'
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        cursor:
          type: string
    ConvertToShipmentRequest:
      type: object
      properties:
        additionalOrders:
          type: array
          items:
            $ref: '#/components/schemas/OrderInput'
          description: Optional additional orders to add to the shipment
      description: Request body for converting a quote to a shipment
    ConvertToShipmentResponse:
      type: object
      required:
        - quoteId
        - quoteStatus
        - shipmentId
        - shipmentKey
        - orderId
      properties:
        quoteId:
          type: string
          format: uuid
          description: Quote ID that was converted
        quoteStatus:
          type: string
          enum:
            - WON
          description: Quote status after conversion (always WON)
        shipmentId:
          type: string
          format: uuid
          description: Created shipment ID
        shipmentKey:
          type: string
          description: Created shipment friendly ID
        orderId:
          type: string
          format: uuid
          description: Order ID from the quote
    ShipmentLifecycleStatus:
      type: string
      enum:
        - DRAFT
        - TENDER_PENDING
        - ON_HOLD
        - PLANNING
        - SELECTED
        - BOOKED
        - DISPATCHED
        - LOADING
        - PICKED_UP
        - IN_TRANSIT
        - UNLOADING
        - ARRIVED_AT_DELIVERY_TERMINAL
        - OUT_FOR_DELIVERY
        - RECOVERED
        - DELIVERED
        - CANCELED
        - TENDER_REJECTED
        - CONSOLIDATED
      description: |
        Current status of the shipment lifecycle.

        **Pre-transit:**
        - `DRAFT`: Shipment being created
        - `TENDER_PENDING`: Awaiting carrier tender acceptance
        - `TENDER_REJECTED`: Carrier rejected the tender
        - `ON_HOLD`: Shipment temporarily paused
        - `PLANNING`: Being planned/scheduled
        - `SELECTED`: Carrier selected
        - `BOOKED`: Carrier confirmed booking
        - `DISPATCHED`: Dispatched to carrier

        **In-transit:**
        - `LOADING`: Loading at pickup
        - `PICKED_UP`: Picked up
        - `IN_TRANSIT`: In transit
        - `UNLOADING`: Unloading at delivery
        - `ARRIVED_AT_DELIVERY_TERMINAL`: At delivery terminal (LTL)
        - `OUT_FOR_DELIVERY`: Out for final delivery
        - `RECOVERED`: Shipment has been recovered

        **Final:**
        - `DELIVERED`: Delivered
        - `CANCELED`: Canceled
        - `CONSOLIDATED`: Merged into a consolidated shipment
    OrderBillingStatus:
      type: string
      enum:
        - DOCS_NEEDED
        - NOT_READY_TO_INVOICE
        - READY_TO_INVOICE
        - INVOICED
        - PAID
      description: |
        Billing status for the order (AR side).
        - `DOCS_NEEDED`: Waiting for delivery documents
        - `NOT_READY_TO_INVOICE`: Not ready to invoice
        - `READY_TO_INVOICE`: Ready to generate invoice
        - `INVOICED`: Invoice generated and sent
        - `PAID`: Fully paid
    Order:
      type: object
      properties:
        id:
          type: string
          format: uuid
        friendlyId:
          type: string
          description: Human-readable order ID (e.g., "ORD-12345")
        key:
          type: string
          description: Client-defined reference identifier for this order
          nullable: true
        mode:
          $ref: '#/components/schemas/TransportMode'
        status:
          $ref: '#/components/schemas/ShipmentLifecycleStatus'
        billingStatus:
          $ref: '#/components/schemas/OrderBillingStatus'
        stops:
          type: array
          items:
            $ref: '#/components/schemas/OrderStop'
          description: Flattened stops array
        freight:
          $ref: '#/components/schemas/OrderFreight'
        references:
          type: array
          items:
            $ref: '#/components/schemas/OrderReference'
        charges:
          type: array
          items:
            $ref: '#/components/schemas/OrderCharge'
        equipment:
          type: array
          items:
            type: string
            format: uuid
          description: Equipment ids. Resolve names via the reference-data equipment endpoint.
        specialRequirements:
          type: array
          items:
            type: string
            format: uuid
          description: Special-requirement ids. Resolve names via the reference-data endpoint.
        mileage:
          type: number
          nullable: true
        totalRevenue:
          type: number
          description: Sum of all charges
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          nullable: true
    OrderStop:
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - PICKUP
            - DELIVERY
        sequence:
          type: integer
          description: Stop order in the route
        location:
          $ref: '#/components/schemas/ResourceReference'
        address:
          allOf:
            - $ref: '#/components/schemas/Address'
          description: |
            Full address from the stop's linked location. Absent when the stop
            has no linked shipper location.
        requestedStartDate:
          type: string
          format: date
          nullable: true
        requestedEndDate:
          type: string
          format: date
          nullable: true
        requestedStartTime:
          type: string
          nullable: true
        requestedEndTime:
          type: string
          nullable: true
        actualArrival:
          type: string
          format: date-time
          nullable: true
        actualDeparture:
          type: string
          format: date-time
          nullable: true
        appointmentRequired:
          type: boolean
        notes:
          type: string
          nullable: true
    OrderFreight:
      type: object
      properties:
        handlingUnitQuantity:
          type: integer
          nullable: true
        handlingUnitType:
          type: string
          nullable: true
        weight:
          type: number
          description: Weight in pounds
          nullable: true
        volume:
          type: number
          description: Volume in cubic feet
          nullable: true
        length:
          type: number
          nullable: true
        width:
          type: number
          nullable: true
        height:
          type: number
          nullable: true
        commodityDescription:
          type: string
          nullable: true
        hazmat:
          type: boolean
        stackable:
          type: boolean
    OrderCharge:
      type: object
      properties:
        id:
          type: string
          format: uuid
        chargeCodeId:
          type: integer
          description: Charge code id. Resolve code/name via the reference-data charge-codes endpoint.
          nullable: true
        description:
          type: string
          nullable: true
        amount:
          type: number
        quantity:
          type: number
          default: 1
        rate:
          type: number
          nullable: true
    Shipment:
      type: object
      required:
        - id
        - friendlyId
        - status
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        friendlyId:
          type: string
          description: Human-readable shipment ID (e.g., "SHP-12345")
          example: SHP-12345
        key:
          type: string
          description: Client-defined reference identifier for this shipment
          example: my-shipment-001
          nullable: true
        status:
          $ref: '#/components/schemas/ShipmentLifecycleStatus'
        customer:
          $ref: '#/components/schemas/CustomerReference'
        customerRep:
          $ref: '#/components/schemas/UserReference'
          description: Customer representative
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
          description: Orders in this shipment
        loads:
          type: array
          items:
            $ref: '#/components/schemas/LoadSummary'
          description: Loads for carrier execution
        services:
          type: array
          items:
            $ref: '#/components/schemas/ServiceSummary'
          description: Vended services
        totalRevenue:
          type: number
          description: Sum of all order charges
          nullable: true
        totalCost:
          type: number
          description: Sum of all load and service costs
          nullable: true
        margin:
          type: number
          description: Revenue minus cost
          nullable: true
        marginPercent:
          type: number
          description: Margin as percentage of revenue
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          nullable: true
        deliveredAt:
          type: string
          format: date-time
          nullable: true
    ShipmentInput:
      type: object
      required:
        - customer
        - orders
      properties:
        customer:
          $ref: '#/components/schemas/ResourceReferenceInput'
          description: Customer reference
        customerRep:
          $ref: '#/components/schemas/ResourceReferenceInput'
          description: Assigned customer rep
        orders:
          type: array
          items:
            $ref: '#/components/schemas/OrderInput'
          minItems: 1
          description: Orders to create (at least one required)
        loads:
          type: array
          items:
            $ref: '#/components/schemas/LoadInput'
          description: Optional loads to create
        services:
          type: array
          items:
            $ref: '#/components/schemas/ServiceInput'
          description: Optional services to create
    ShipmentPatch:
      type: object
      properties:
        customer:
          $ref: '#/components/schemas/ResourceReferenceInput'
        customerRep:
          $ref: '#/components/schemas/ResourceReferenceInput'
      description: Partial update fields for a shipment
    ShipmentFilter:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUIDFilter'
        key:
          $ref: '#/components/schemas/StringFilter'
        status:
          $ref: '#/components/schemas/ShipmentStatusFilter'
        customerId:
          $ref: '#/components/schemas/UUIDFilter'
        customerRepId:
          $ref: '#/components/schemas/UUIDFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deliveredAt:
          $ref: '#/components/schemas/DatetimeFilter'
        and:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentFilter'
        or:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentFilter'
        not:
          $ref: '#/components/schemas/ShipmentFilter'
    ShipmentFilterRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/ShipmentFilter'
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        cursor:
          type: string
    CancelShipmentRequest:
      type: object
      properties:
        reason:
          type: string
          maxLength: 1000
          description: Reason for cancellation
      description: Request body for canceling a shipment
    DuplicateShipmentRequest:
      type: object
      properties:
        pickUpDate:
          type: string
          format: date
          description: New pickup date for the duplicate
        deliveryDate:
          type: string
          format: date
          description: New delivery date for the duplicate
      description: Request body for duplicating a shipment
    DuplicateShipmentResponse:
      type: object
      required:
        - originalShipmentId
        - newShipmentId
        - newShipmentKey
      properties:
        originalShipmentId:
          type: string
          format: uuid
        newShipmentId:
          type: string
          format: uuid
        newShipmentKey:
          type: string
    LoadStatus:
      type: string
      enum:
        - SOURCING
        - SELECTED
        - BOOKED
        - DISPATCHED
        - LOADING
        - PICKED_UP
        - IN_TRANSIT
        - UNLOADING
        - ARRIVED_AT_DELIVERY_TERMINAL
        - OUT_FOR_DELIVERY
        - RECOVERED
        - DELIVERED_AWAITING_INVOICE
        - DELIVERED_INVOICE_IN_REVIEW
        - DELIVERED_APPROVED_TO_BE_PAID
        - DELIVERED_PAID
        - COMPLETE
        - SERVICE_FAILURE
        - ON_HOLD
        - CANCELED
      description: |
        Current status of the load.

        **Pre-transit:**
        - `SOURCING`: Looking for carrier
        - `SELECTED`: Carrier selected
        - `BOOKED`: Carrier booked
        - `DISPATCHED`: Dispatched to carrier

        **In-transit:**
        - `LOADING`: Loading at pickup
        - `PICKED_UP`: Picked up
        - `IN_TRANSIT`: In transit
        - `UNLOADING`: Unloading at delivery
        - `ARRIVED_AT_DELIVERY_TERMINAL`: Arrived at delivery terminal
        - `OUT_FOR_DELIVERY`: Out for delivery
        - `RECOVERED`: Recovered after a service issue

        **Delivered (accounts payable lifecycle):**
        - `DELIVERED_AWAITING_INVOICE`: Delivered, awaiting carrier invoice
        - `DELIVERED_INVOICE_IN_REVIEW`: Carrier invoice in review
        - `DELIVERED_APPROVED_TO_BE_PAID`: Approved to be paid
        - `DELIVERED_PAID`: Paid

        **Final / exceptions:**
        - `COMPLETE`: Complete
        - `SERVICE_FAILURE`: Service failure
        - `ON_HOLD`: On hold
        - `CANCELED`: Canceled
    LoadCarrierStatus:
      type: string
      enum:
        - ACTIVE
        - TONU
        - BOUNCED
      description: |
        Status of the carrier assignment.
        - `ACTIVE`: Carrier is actively assigned
        - `TONU`: Truck Ordered Not Used (carrier dispatched but cancelled)
        - `BOUNCED`: Carrier bounced/rejected load
    LoadBillingStatus:
      type: string
      enum:
        - AWAITING_INVOICE
        - INVOICE_IN_REVIEW
        - APPROVED_TO_PAY
        - PAID
      description: |
        Billing status for the load (AP side).
        - `AWAITING_INVOICE`: Waiting for carrier invoice
        - `INVOICE_IN_REVIEW`: Invoice received, under review
        - `APPROVED_TO_PAY`: Approved for payment
        - `PAID`: Paid to carrier
    Load:
      type: object
      required:
        - id
        - status
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        friendlyId:
          type: string
          description: Human-readable load ID (e.g., "LD-12345")
          example: LD-12345
        key:
          type: string
          description: Client-defined reference identifier for this load
          example: my-load-001
          nullable: true
        shipmentId:
          type: string
          format: uuid
          description: Parent shipment
        shipmentKey:
          type: string
          description: Parent shipment human-readable ID (friendlyId)
          nullable: true
        mode:
          $ref: '#/components/schemas/TransportMode'
        status:
          $ref: '#/components/schemas/LoadStatus'
        stops:
          type: array
          items:
            $ref: '#/components/schemas/LoadStop'
          description: Load stops
        carriers:
          type: array
          items:
            $ref: '#/components/schemas/LoadCarrier'
          description: Carrier assignments (flattened from LoadCarriersConnection)
        totalCost:
          type: number
          description: Total carrier costs
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          nullable: true
        pickedUpAt:
          type: string
          format: date-time
          nullable: true
        deliveredAt:
          type: string
          format: date-time
          nullable: true
    LoadCarrier:
      type: object
      properties:
        id:
          type: string
          format: uuid
        carrier:
          $ref: '#/components/schemas/CarrierReference'
        contact:
          type: object
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
            phone:
              type: string
              nullable: true
            email:
              type: string
              nullable: true
        status:
          $ref: '#/components/schemas/LoadCarrierStatus'
        billingStatus:
          $ref: '#/components/schemas/LoadBillingStatus'
        bookedAt:
          type: string
          format: date-time
          nullable: true
        dispatchedAt:
          type: string
          format: date-time
          nullable: true
        removedAt:
          type: string
          format: date-time
          description: |
            When this assignment was removed from the load (bounce, TONU, rebook).
            Removed assignments stay in `carriers` as history but their charges
            are excluded from the load `totalCost`.
          nullable: true
        charges:
          type: array
          items:
            $ref: '#/components/schemas/LoadCarrierCharge'
          description: Flattened charges array
        totalCost:
          type: number
          description: Sum of all charges
          nullable: true
        driverName:
          type: string
          nullable: true
        driverPhone:
          type: string
          nullable: true
        truckNumber:
          type: string
          nullable: true
        trailerNumber:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          nullable: true
    LoadInput:
      type: object
      properties:
        mode:
          $ref: '#/components/schemas/TransportMode'
        orderStopIds:
          type: array
          items:
            type: string
            format: uuid
          description: Order stop IDs to include in this load
        carrier:
          $ref: '#/components/schemas/LoadCarrierInput'
          description: Initial carrier assignment
    LoadCarrierInput:
      type: object
      required:
        - carrier
      properties:
        carrier:
          $ref: '#/components/schemas/ResourceReferenceInput'
          description: Carrier reference
        contact:
          $ref: '#/components/schemas/ResourceReferenceInput'
          description: Carrier contact
        charges:
          type: array
          items:
            type: object
            required:
              - chargeCode
              - amount
            properties:
              chargeCode:
                $ref: '#/components/schemas/ResourceReferenceInput'
              description:
                type: string
              amount:
                type: number
              quantity:
                type: number
                default: 1
        driverName:
          type: string
        driverPhone:
          type: string
        truckNumber:
          type: string
        trailerNumber:
          type: string
    LoadPatch:
      type: object
      properties:
        mode:
          $ref: '#/components/schemas/TransportMode'
    LoadCarrierPatch:
      type: object
      properties:
        contact:
          $ref: '#/components/schemas/ResourceReferenceInput'
        driverName:
          type: string
          nullable: true
        driverPhone:
          type: string
          nullable: true
        truckNumber:
          type: string
          nullable: true
        trailerNumber:
          type: string
          nullable: true
    LoadFilter:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUIDFilter'
        shipmentId:
          $ref: '#/components/schemas/UUIDFilter'
        status:
          $ref: '#/components/schemas/LoadStatusFilter'
        mode:
          type: object
          properties:
            equalTo:
              $ref: '#/components/schemas/TransportMode'
            in:
              type: array
              items:
                $ref: '#/components/schemas/TransportMode'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deliveredAt:
          $ref: '#/components/schemas/DatetimeFilter'
        and:
          type: array
          items:
            $ref: '#/components/schemas/LoadFilter'
        or:
          type: array
          items:
            $ref: '#/components/schemas/LoadFilter'
        not:
          $ref: '#/components/schemas/LoadFilter'
    LoadFilterRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/LoadFilter'
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        cursor:
          type: string
    ReportTonuRequest:
      type: object
      properties:
        reason:
          type: string
          maxLength: 1000
          description: Reason for TONU
        costs:
          type: array
          items:
            type: object
            required:
              - chargeCode
              - amount
            properties:
              chargeCode:
                $ref: '#/components/schemas/ResourceReferenceInput'
              description:
                type: string
              amount:
                type: number
          description: TONU costs to record
        createReplacementLoad:
          type: boolean
          default: false
          description: Whether to create a replacement load
      description: Request body for reporting TONU
    BounceCarrierRequest:
      type: object
      properties:
        reason:
          $ref: '#/components/schemas/LoadCarrierRemovalReason'
        reasonText:
          type: string
          maxLength: 1000
          description: Additional reason details
      description: Request body for bouncing a carrier
    ServiceStatus:
      type: string
      enum:
        - ACTIVE
        - AWAITING_INVOICE
        - INVOICE_IN_REVIEW
        - APPROVED_TO_PAY
        - PAID
        - CANCELED
      description: |
        Current status of the service.

        **Active states:**
        - `ACTIVE`: Service is active/in progress

        **Billing states (AP):**
        - `AWAITING_INVOICE`: Waiting for vendor invoice
        - `INVOICE_IN_REVIEW`: Invoice received, under review
        - `APPROVED_TO_PAY`: Approved for payment
        - `PAID`: Paid to vendor

        **Final states:**
        - `CANCELED`: Service canceled
    Service:
      type: object
      required:
        - id
        - status
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          description: Human-readable service ID
          example: SVC-12345
          nullable: true
        shipmentId:
          type: string
          format: uuid
          description: Parent shipment
        shipmentKey:
          type: string
          description: Parent shipment friendly ID
          nullable: true
        vendor:
          $ref: '#/components/schemas/VendorReference'
        vendorContact:
          type: object
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
            phone:
              type: string
              nullable: true
            email:
              type: string
              nullable: true
        status:
          $ref: '#/components/schemas/ServiceStatus'
        description:
          type: string
          description: Service description
          nullable: true
        charges:
          type: array
          items:
            $ref: '#/components/schemas/ServiceCharge'
          description: Flattened charges array
        totalCost:
          type: number
          description: Sum of all charges
          nullable: true
        scheduledDate:
          type: string
          format: date
          nullable: true
        completedDate:
          type: string
          format: date
          nullable: true
        referenceNumber:
          type: string
          description: Vendor reference number
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          nullable: true
    ServiceInput:
      type: object
      required:
        - vendor
      properties:
        vendor:
          $ref: '#/components/schemas/ResourceReferenceInput'
          description: Vendor reference
        vendorContact:
          $ref: '#/components/schemas/ResourceReferenceInput'
          description: Vendor contact
        description:
          type: string
          maxLength: 2000
        charges:
          type: array
          items:
            type: object
            required:
              - chargeCode
              - amount
            properties:
              chargeCode:
                $ref: '#/components/schemas/ResourceReferenceInput'
              description:
                type: string
              amount:
                type: number
              quantity:
                type: number
                default: 1
        scheduledDate:
          type: string
          format: date
        referenceNumber:
          type: string
    ServicePatch:
      type: object
      description: |
        Partial service update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        vendorContact:
          $ref: '#/components/schemas/ResourceReferenceInput'
        description:
          type: string
          nullable: true
        scheduledDate:
          type: string
          format: date
          nullable: true
        completedDate:
          type: string
          format: date
          nullable: true
        referenceNumber:
          type: string
          nullable: true
    ServiceFilter:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUIDFilter'
        shipmentId:
          $ref: '#/components/schemas/UUIDFilter'
        vendorId:
          $ref: '#/components/schemas/UUIDFilter'
        status:
          $ref: '#/components/schemas/ServiceStatusFilter'
        scheduledDate:
          $ref: '#/components/schemas/DatetimeFilter'
        completedDate:
          $ref: '#/components/schemas/DatetimeFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        and:
          type: array
          items:
            $ref: '#/components/schemas/ServiceFilter'
        or:
          type: array
          items:
            $ref: '#/components/schemas/ServiceFilter'
        not:
          $ref: '#/components/schemas/ServiceFilter'
    ServiceFilterRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/ServiceFilter'
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        cursor:
          type: string
    InvoiceStatus:
      type: string
      enum:
        - DRAFT
        - AWAITING_PAYMENT
        - PARTIALLY_PAID
        - PAID
        - VOIDED
      description: |
        Current status of the invoice.
        - `DRAFT`: Invoice record exists but not finalized
        - `AWAITING_PAYMENT`: Invoice finalized, awaiting payment
        - `PARTIALLY_PAID`: Some payments received, balance remains
        - `PAID`: Fully paid
        - `VOIDED`: Invoice cancelled/voided
    FactoringProvider:
      type: string
      enum:
        - ARTISPAY
        - DENIM
        - HAUL_PAY
        - TRIUMPH
      description: |
        Factoring provider for invoice financing.
        - `DENIM`: Denim factoring
        - `HAULPAY`: HaulPay factoring
    InvoicePayment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        paymentGroupId:
          type: string
          format: uuid
        amount:
          type: number
          description: Amount applied to this invoice
        paymentDate:
          type: string
          format: date
        reference:
          type: string
          description: Check number, transaction ID, etc.
          nullable: true
        paymentMethodType:
          type: string
          description: Payment method (check, ach_wire, etc.)
          nullable: true
    InvoiceCredit:
      type: object
      properties:
        id:
          type: string
          format: uuid
        creditMemoId:
          type: string
          format: uuid
        creditMemoReference:
          type: string
          nullable: true
        amount:
          type: number
          description: Credit amount applied
        appliedAt:
          type: string
          format: date-time
    Invoice:
      type: object
      required:
        - id
        - friendlyId
        - status
        - invoiceDate
        - amount
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        friendlyId:
          type: string
          description: Human-readable invoice ID
          example: INV-00001
        key:
          type: string
          description: Client-defined key
          nullable: true
        orderId:
          type: string
          format: uuid
          description: Associated order ID
        orderKey:
          type: string
          description: Order friendly ID
          nullable: true
        shipmentId:
          type: string
          format: uuid
          description: Associated shipment ID
        shipmentKey:
          type: string
          description: Shipment friendly ID
          nullable: true
        customer:
          $ref: '#/components/schemas/CustomerReference'
        status:
          $ref: '#/components/schemas/InvoiceStatus'
        invoiceDate:
          type: string
          format: date
          description: Date invoice was issued
        dueDate:
          type: string
          format: date
          description: Payment due date
          nullable: true
        amount:
          type: number
          description: Total invoice amount
        currency:
          type: string
          description: Currency code (USD, CAD)
          example: USD
          nullable: true
        reference:
          type: string
          description: External reference number
          nullable: true
        amountPaid:
          type: number
          description: Total payments received
        amountOwed:
          type: number
          description: Outstanding balance
        creditsApplied:
          type: number
          description: Total credits applied
          nullable: true
        paymentTerm:
          $ref: '#/components/schemas/PaymentTermReference'
        payments:
          type: array
          items:
            $ref: '#/components/schemas/InvoicePayment'
          description: Payments applied to this invoice
        credits:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceCredit'
          description: Credits applied to this invoice
        factorName:
          $ref: '#/components/schemas/FactoringProvider'
        factorJobId:
          type: string
          description: External factoring job ID
          nullable: true
        factorStatus:
          type: string
          description: Current factoring status
          nullable: true
        qboId:
          type: string
          description: QuickBooks Online invoice ID
          nullable: true
        documentId:
          type: string
          format: uuid
          description: Generated invoice PDF document ID
          nullable: true
        documentUrl:
          type: string
          description: Download URL for invoice PDF
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          nullable: true
    InvoiceInput:
      type: object
      required:
        - orderId
        - invoiceDate
        - amount
      properties:
        orderId:
          type: string
          format: uuid
          description: Order to invoice
        invoiceDate:
          type: string
          format: date
          description: Invoice date
        dueDate:
          type: string
          format: date
          description: Payment due date
        amount:
          type: number
          description: Invoice amount (typically calculated from order charges)
        reference:
          type: string
          maxLength: 500
          description: External reference number
        currency:
          type: string
          description: Currency code (defaults to customer currency)
        paymentTermId:
          type: string
          format: uuid
          description: Payment term (defaults to customer default)
    InvoicePatch:
      type: object
      properties:
        dueDate:
          type: string
          format: date
          nullable: true
        reference:
          type: string
          nullable: true
        paymentTermId:
          type: string
          format: uuid
    InvoiceFilter:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUIDFilter'
        orderId:
          $ref: '#/components/schemas/UUIDFilter'
        shipmentId:
          $ref: '#/components/schemas/UUIDFilter'
        customerId:
          $ref: '#/components/schemas/UUIDFilter'
        status:
          $ref: '#/components/schemas/InvoiceStatusFilter'
        invoiceDate:
          $ref: '#/components/schemas/DatetimeFilter'
        dueDate:
          $ref: '#/components/schemas/DatetimeFilter'
        amount:
          $ref: '#/components/schemas/FloatFilter'
        amountOwed:
          $ref: '#/components/schemas/FloatFilter'
        overdue:
          type: boolean
          description: Filter to overdue invoices only
        factored:
          type: boolean
          description: Filter to factored invoices only
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        and:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceFilter'
        or:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceFilter'
        not:
          $ref: '#/components/schemas/InvoiceFilter'
    InvoiceFilterRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/InvoiceFilter'
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        cursor:
          type: string
    GenerateInvoiceRequest:
      type: object
      properties:
        invoiceDate:
          type: string
          format: date
          description: Invoice date (defaults to today)
        dueDate:
          type: string
          format: date
          description: Due date (defaults based on payment term)
        attachmentDocumentIds:
          type: array
          items:
            type: string
            format: uuid
          description: Document IDs to attach to invoice PDF
    GenerateInvoiceResponse:
      type: object
      required:
        - invoice
        - document
      properties:
        invoice:
          $ref: '#/components/schemas/Invoice'
        document:
          type: object
          properties:
            id:
              type: string
              format: uuid
            url:
              type: string
              description: Download URL for invoice PDF
    BatchGenerateInvoicesRequest:
      type: object
      required:
        - orderIds
      properties:
        orderIds:
          type: array
          items:
            type: string
            format: uuid
          description: Order IDs to generate invoices for
          maxItems: 100
        sendEmail:
          type: boolean
          default: false
          description: Email invoices to customers after generation
        emailConfig:
          type: object
          properties:
            ccEmails:
              type: array
              items:
                type: string
                format: email
            groupByCustomer:
              type: boolean
              default: true
              description: Group invoices by customer in emails
    BatchGenerateInvoicesResponse:
      type: object
      properties:
        generated:
          type: array
          items:
            type: object
            properties:
              orderId:
                type: string
                format: uuid
              invoiceId:
                type: string
                format: uuid
              documentId:
                type: string
                format: uuid
        failed:
          type: array
          items:
            type: object
            properties:
              orderId:
                type: string
                format: uuid
              error:
                type: string
        emailsSent:
          type: integer
    SendInvoiceEmailRequest:
      type: object
      required:
        - toEmails
      properties:
        toEmails:
          type: array
          items:
            type: string
            format: email
          minItems: 1
        ccEmails:
          type: array
          items:
            type: string
            format: email
        subject:
          type: string
          description: Email subject (defaults to standard invoice subject)
        message:
          type: string
          description: Email body message
    MarkAwaitingPaymentRequest:
      type: object
      properties:
        invoiceDate:
          type: string
          format: date
          description: Invoice date (defaults to today)
        dueDate:
          type: string
          format: date
          description: Due date (defaults based on payment term)
    AgingReportResponse:
      type: object
      required:
        - asOfDate
        - buckets
        - customers
        - totals
      properties:
        asOfDate:
          type: string
          format: date
        buckets:
          type: array
          items:
            type: string
          example:
            - Current
            - 1-30
            - 31-60
            - 61-90
            - 90+
        customers:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              friendlyId:
                type: string
              current:
                type: number
              days1to30:
                type: number
              days31to60:
                type: number
              days61to90:
                type: number
              over90:
                type: number
              total:
                type: number
        totals:
          type: object
          properties:
            current:
              type: number
            days1to30:
              type: number
            days31to60:
              type: number
            days61to90:
              type: number
            over90:
              type: number
            total:
              type: number
    ARPaymentMethodType:
      $ref: '#/components/schemas/PaymentMethodType-3'
    PaymentApplication:
      type: object
      required:
        - id
        - invoiceId
        - amount
      properties:
        id:
          type: string
          format: uuid
        invoiceId:
          type: string
          format: uuid
        invoiceFriendlyId:
          type: string
          nullable: true
        invoiceAmount:
          type: number
          description: Total invoice amount
          nullable: true
        invoiceOpenBalance:
          type: number
          description: Invoice balance before this payment
          nullable: true
        amount:
          type: number
          description: Amount applied to this invoice
    PaymentCreditApplication:
      type: object
      properties:
        id:
          type: string
          format: uuid
        creditMemoId:
          type: string
          format: uuid
        creditMemoReference:
          type: string
          nullable: true
        amount:
          type: number
          description: Credit amount applied in this payment
    Payment:
      type: object
      required:
        - id
        - paymentDate
        - totalAmount
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          description: Human-readable payment key
          example: PMT-00001
          nullable: true
        customer:
          $ref: '#/components/schemas/CustomerReference'
        paymentDate:
          type: string
          format: date
          description: Date payment was received
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType-3'
        reference:
          type: string
          description: Check number, transaction ID, etc.
          nullable: true
        notes:
          type: string
          description: Payment notes
          nullable: true
        currency:
          type: string
          description: Currency code
          example: USD
          nullable: true
        totalAmount:
          type: number
          description: Total payment amount
        applications:
          type: array
          items:
            $ref: '#/components/schemas/PaymentApplication'
          description: Invoices this payment is applied to
        creditApplications:
          type: array
          items:
            $ref: '#/components/schemas/PaymentCreditApplication'
          description: Credits applied in this payment
        overpaymentAmount:
          type: number
          description: Amount in excess of invoice totals
          nullable: true
        overpaymentCreditMemoId:
          type: string
          format: uuid
          description: Credit memo created from overpayment
          nullable: true
        shipmentIds:
          type: array
          items:
            type: string
            format: uuid
          description: Related shipment IDs
        shipmentKeys:
          type: array
          items:
            type: string
          description: Related shipment friendly IDs
        qboId:
          type: string
          description: QuickBooks Online payment ID
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          nullable: true
    PaymentApplicationInput:
      type: object
      required:
        - invoiceId
        - amount
      properties:
        invoiceId:
          type: string
          format: uuid
          description: Invoice to apply payment to
        amount:
          type: number
          minimum: 0.01
          description: Amount to apply to this invoice
    PaymentCreditApplicationInput:
      type: object
      required:
        - creditMemoId
        - amount
      properties:
        creditMemoId:
          type: string
          format: uuid
          description: Credit memo to apply
        amount:
          type: number
          minimum: 0.01
          description: Credit amount to apply
    PaymentInput:
      type: object
      required:
        - customerId
        - paymentDate
        - applications
      properties:
        customerId:
          type: string
          format: uuid
          description: Customer making the payment
        paymentDate:
          type: string
          format: date
          description: Date payment was received
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType-3'
        reference:
          type: string
          maxLength: 500
          description: Check number, transaction ID, etc.
        notes:
          type: string
          maxLength: 2000
          description: Payment notes
        applications:
          type: array
          items:
            $ref: '#/components/schemas/PaymentApplicationInput'
          minItems: 1
          description: Invoices to apply payment to
        creditApplications:
          type: array
          items:
            $ref: '#/components/schemas/PaymentCreditApplicationInput'
          description: Credits to apply in this payment
    PaymentPatch:
      type: object
      properties:
        paymentDate:
          type: string
          format: date
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType-3'
        reference:
          type: string
          nullable: true
        notes:
          type: string
          nullable: true
        applications:
          type: array
          items:
            $ref: '#/components/schemas/PaymentApplicationInput'
          description: Replace all invoice applications
        creditApplications:
          type: array
          items:
            $ref: '#/components/schemas/PaymentCreditApplicationInput'
          description: Replace all credit applications
    PaymentFilter:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUIDFilter'
        customerId:
          $ref: '#/components/schemas/UUIDFilter'
        invoiceId:
          $ref: '#/components/schemas/UUIDFilter'
        shipmentId:
          $ref: '#/components/schemas/UUIDFilter'
        paymentDate:
          $ref: '#/components/schemas/DatetimeFilter'
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodTypeFilter-3'
        totalAmount:
          $ref: '#/components/schemas/FloatFilter'
        reference:
          $ref: '#/components/schemas/StringFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        and:
          type: array
          items:
            $ref: '#/components/schemas/PaymentFilter'
        or:
          type: array
          items:
            $ref: '#/components/schemas/PaymentFilter'
        not:
          $ref: '#/components/schemas/PaymentFilter'
    PaymentFilterRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/PaymentFilter'
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        cursor:
          type: string
    OutstandingInvoicesResponse:
      type: object
      required:
        - invoices
        - totalOutstanding
      properties:
        invoices:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              friendlyId:
                type: string
              amount:
                type: number
              invoiceDate:
                type: string
                format: date
              dueDate:
                type: string
                format: date
                nullable: true
              openBalance:
                type: number
              isOverdue:
                type: boolean
              payments:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    amount:
                      type: number
                    paymentDate:
                      type: string
                      format: date
        totalOutstanding:
          type: number
          description: Total outstanding balance for customer
    CreditMemoStatus:
      type: string
      enum:
        - OPEN
        - PARTIALLY_APPLIED
        - APPLIED
        - VOIDED
      description: |
        Current status of the credit memo (derived from remaining balance).
        - `OPEN`: No applications, full balance available
        - `PARTIALLY_APPLIED`: Some amount applied, balance remains
        - `APPLIED`: Fully applied to invoices
        - `VOIDED`: Credit memo cancelled
    CreditMemoApplication:
      type: object
      required:
        - id
        - invoiceId
        - amount
      properties:
        id:
          type: string
          format: uuid
        invoiceId:
          type: string
          format: uuid
        invoiceFriendlyId:
          type: string
          nullable: true
        paymentId:
          type: string
          format: uuid
          description: Payment through which this credit was applied
        paymentKey:
          type: string
          nullable: true
        amount:
          type: number
          description: Amount applied
        appliedAt:
          type: string
          format: date-time
    CreditMemo:
      type: object
      required:
        - id
        - amount
        - remainingBalance
        - status
        - memoDate
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          description: Client-defined key
          nullable: true
        reference:
          type: string
          description: Reference number
          example: CM-00001
          nullable: true
        customer:
          $ref: '#/components/schemas/CustomerReference'
        amount:
          type: number
          description: Original credit amount
        appliedAmount:
          type: number
          description: Total amount applied to invoices
        remainingBalance:
          type: number
          description: Available balance
        currency:
          type: string
          description: Currency code
          example: USD
          nullable: true
        status:
          $ref: '#/components/schemas/CreditMemoStatus'
        memoDate:
          type: string
          format: date
          description: Credit memo date
        notes:
          type: string
          description: Notes or description
          nullable: true
        sourcePaymentGroupId:
          type: string
          format: uuid
          description: Payment that created this credit (if from overpayment)
          nullable: true
        sourcePaymentKey:
          type: string
          nullable: true
        applications:
          type: array
          items:
            $ref: '#/components/schemas/CreditMemoApplication'
          description: Invoices this credit is applied to
        qboId:
          type: string
          description: QuickBooks Online credit memo ID
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          nullable: true
        voidedAt:
          type: string
          format: date-time
          nullable: true
        voidReason:
          type: string
          nullable: true
        createdBy:
          $ref: '#/components/schemas/UserReference'
    CreditMemoInput:
      type: object
      required:
        - customerId
        - amount
        - memoDate
      properties:
        customerId:
          type: string
          format: uuid
          description: Customer to credit
        amount:
          type: number
          minimum: 0.01
          description: Credit amount
        currency:
          type: string
          description: Currency code (defaults to customer currency)
        memoDate:
          type: string
          format: date
          description: Credit memo date
        reference:
          type: string
          maxLength: 500
          description: Reference number
        notes:
          type: string
          maxLength: 2000
          description: Notes or description
    CreditMemoPatch:
      type: object
      properties:
        reference:
          type: string
          nullable: true
        notes:
          type: string
          nullable: true
        memoDate:
          type: string
          format: date
    CreditMemoFilter:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUIDFilter'
        customerId:
          $ref: '#/components/schemas/UUIDFilter'
        status:
          $ref: '#/components/schemas/CreditMemoStatusFilter'
        memoDate:
          $ref: '#/components/schemas/DatetimeFilter'
        amount:
          $ref: '#/components/schemas/FloatFilter'
        remainingBalance:
          $ref: '#/components/schemas/FloatFilter'
        hasRemainingBalance:
          type: boolean
          description: Filter to credits with available balance
        sourcePaymentGroupId:
          $ref: '#/components/schemas/UUIDFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        and:
          type: array
          items:
            $ref: '#/components/schemas/CreditMemoFilter'
        or:
          type: array
          items:
            $ref: '#/components/schemas/CreditMemoFilter'
        not:
          $ref: '#/components/schemas/CreditMemoFilter'
    CreditMemoFilterRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/CreditMemoFilter'
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        cursor:
          type: string
    ApplyCreditRequest:
      type: object
      required:
        - invoiceId
        - amount
      properties:
        invoiceId:
          type: string
          format: uuid
          description: Invoice to apply credit to
        amount:
          type: number
          minimum: 0.01
          description: Amount to apply
    ApplyCreditResponse:
      type: object
      required:
        - application
        - creditMemo
      properties:
        application:
          $ref: '#/components/schemas/CreditMemoApplication'
        creditMemo:
          $ref: '#/components/schemas/CreditMemo'
    VoidCreditMemoRequest:
      type: object
      properties:
        reason:
          type: string
          maxLength: 1000
          description: Reason for voiding
    AvailableCreditsResponse:
      type: object
      required:
        - availableCredits
        - totalAvailable
      properties:
        availableCredits:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              reference:
                type: string
                nullable: true
              remainingBalance:
                type: number
              currency:
                type: string
              memoDate:
                type: string
                format: date
              notes:
                type: string
                nullable: true
        totalAvailable:
          type: number
          description: Total available credit balance
    BillStatus:
      type: string
      enum:
        - AWAITING_INVOICE
        - IN_REVIEW
        - APPROVED_TO_PAY
        - PAID
      description: |
        Current status of the bill (AP invoice).
        - `AWAITING_INVOICE`: Waiting for carrier/vendor to submit invoice
        - `IN_REVIEW`: Invoice received, under review
        - `APPROVED_TO_PAY`: Approved and ready for payment
        - `PAID`: Fully paid
    BillEntityType:
      type: string
      enum:
        - CARRIER
        - VENDOR
      description: |
        Type of entity the bill is for.
        - `CARRIER`: Bill for a carrier (LoadCarrier)
        - `VENDOR`: Bill for a vendor service (VendedService)
    BillPaymentApplied:
      type: object
      properties:
        id:
          type: string
          format: uuid
        paymentGroupId:
          type: string
          format: uuid
        amount:
          type: number
          description: Amount applied to this bill
        paymentDate:
          type: string
          format: date
        reference:
          type: string
          description: Check number, transaction ID, etc.
          nullable: true
    Bill:
      type: object
      required:
        - id
        - friendlyId
        - status
        - entityType
        - amount
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        friendlyId:
          type: string
          description: Human-readable bill ID
          example: BILL-00001
        key:
          type: string
          description: Client-defined key
          nullable: true
        entityType:
          $ref: '#/components/schemas/BillEntityType'
        loadCarrierId:
          type: string
          format: uuid
          description: Associated load carrier ID (if carrier bill)
          nullable: true
        vendedServiceId:
          type: string
          format: uuid
          description: Associated vended service ID (if vendor bill)
          nullable: true
        carrier:
          $ref: '#/components/schemas/CarrierReference'
        vendor:
          $ref: '#/components/schemas/VendorReference'
        loadId:
          type: string
          format: uuid
          nullable: true
        loadKey:
          type: string
          nullable: true
        shipmentId:
          type: string
          format: uuid
          nullable: true
        shipmentKey:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/BillStatus'
        invoiceDate:
          type: string
          format: date
          description: Date of carrier/vendor invoice
          nullable: true
        dueDate:
          type: string
          format: date
          description: Payment due date
          nullable: true
        amount:
          type: number
          description: Bill amount
        currency:
          type: string
          description: Currency code
          example: USD
          nullable: true
        reference:
          type: string
          description: Carrier/vendor invoice reference number
          nullable: true
        amountPaid:
          type: number
          description: Total payments received
        amountOwed:
          type: number
          description: Outstanding balance
        payments:
          type: array
          items:
            $ref: '#/components/schemas/BillPaymentApplied'
          description: Payments applied to this bill
        paymentTerm:
          $ref: '#/components/schemas/PaymentTermReference'
        carrierFactor:
          $ref: '#/components/schemas/CarrierFactorReference'
        factorJobId:
          type: string
          description: External factoring job ID
          nullable: true
        factorStatus:
          type: string
          description: Current factoring status
          nullable: true
        qboId:
          type: string
          description: QuickBooks Online bill ID
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          nullable: true
    BillInput:
      type: object
      required:
        - entityType
        - entityId
        - invoiceDate
        - amount
      properties:
        entityType:
          $ref: '#/components/schemas/BillEntityType'
        entityId:
          type: string
          format: uuid
          description: LoadCarrier ID or VendedService ID
        invoiceDate:
          type: string
          format: date
          description: Invoice date from carrier/vendor
        dueDate:
          type: string
          format: date
          description: Payment due date
        amount:
          type: number
          description: Invoice amount
        reference:
          type: string
          maxLength: 500
          description: Carrier/vendor invoice reference number
        currency:
          type: string
          description: Currency code (defaults to carrier/vendor currency)
        paymentTermId:
          type: string
          format: uuid
          description: Payment term
    BillPatch:
      type: object
      properties:
        invoiceDate:
          type: string
          format: date
          nullable: true
        dueDate:
          type: string
          format: date
          nullable: true
        amount:
          type: number
        reference:
          type: string
          nullable: true
        paymentTermId:
          type: string
          format: uuid
    BillFilter:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUIDFilter'
        loadCarrierId:
          $ref: '#/components/schemas/UUIDFilter'
        vendedServiceId:
          $ref: '#/components/schemas/UUIDFilter'
        carrierId:
          $ref: '#/components/schemas/UUIDFilter'
        vendorId:
          $ref: '#/components/schemas/UUIDFilter'
        loadId:
          $ref: '#/components/schemas/UUIDFilter'
        shipmentId:
          $ref: '#/components/schemas/UUIDFilter'
        status:
          $ref: '#/components/schemas/BillStatusFilter'
        entityType:
          $ref: '#/components/schemas/BillEntityTypeFilter'
        invoiceDate:
          $ref: '#/components/schemas/DatetimeFilter'
        dueDate:
          $ref: '#/components/schemas/DatetimeFilter'
        amount:
          $ref: '#/components/schemas/FloatFilter'
        overdue:
          type: boolean
          description: Filter to overdue bills only
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        and:
          type: array
          items:
            $ref: '#/components/schemas/BillFilter'
        or:
          type: array
          items:
            $ref: '#/components/schemas/BillFilter'
        not:
          $ref: '#/components/schemas/BillFilter'
    BillFilterRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/BillFilter'
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        cursor:
          type: string
    ApproveBillsRequest:
      type: object
      required:
        - billIds
      properties:
        billIds:
          type: array
          items:
            type: string
            format: uuid
          minItems: 1
          maxItems: 100
          description: Bill IDs to approve
    ApproveBillsResponse:
      type: object
      properties:
        approved:
          type: array
          items:
            type: object
            properties:
              billId:
                type: string
                format: uuid
              status:
                $ref: '#/components/schemas/BillStatus'
        failed:
          type: array
          items:
            type: object
            properties:
              billId:
                type: string
                format: uuid
              error:
                type: string
    RevertBillRequest:
      type: object
      properties:
        reason:
          type: string
          maxLength: 1000
          description: Reason for reverting
    OutstandingBillsResponse:
      type: object
      required:
        - bills
        - totalOutstanding
      properties:
        bills:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              friendlyId:
                type: string
              entityType:
                $ref: '#/components/schemas/BillEntityType'
              carrier:
                $ref: '#/components/schemas/CarrierReference'
              vendor:
                $ref: '#/components/schemas/VendorReference'
              amount:
                type: number
              invoiceDate:
                type: string
                format: date
                nullable: true
              dueDate:
                type: string
                format: date
                nullable: true
              openBalance:
                type: number
              isOverdue:
                type: boolean
        totalOutstanding:
          type: number
          description: Total outstanding balance
    ApAgingReportResponse:
      type: object
      required:
        - asOfDate
        - buckets
        - payees
        - totals
      properties:
        asOfDate:
          type: string
          format: date
        buckets:
          type: array
          items:
            type: string
          example:
            - Current
            - 1-30
            - 31-60
            - 61-90
            - 90+
        payees:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              friendlyId:
                type: string
                nullable: true
              entityType:
                $ref: '#/components/schemas/BillEntityType'
              current:
                type: number
              days1to30:
                type: number
              days31to60:
                type: number
              days61to90:
                type: number
              over90:
                type: number
              total:
                type: number
        totals:
          type: object
          properties:
            current:
              type: number
            days1to30:
              type: number
            days31to60:
              type: number
            days61to90:
              type: number
            over90:
              type: number
            total:
              type: number
    BillPaymentMethodType:
      type: string
      enum:
        - ACH_WIRE
        - CHECK
        - CREDIT_CARD
        - EFT_DIRECT_DEPOSIT
        - E_TRANSFER
        - VENMO
        - ZELLE
      description: |
        Payment method used for the bill payment.
        - `ACH_WIRE`: ACH wire transfer
        - `CHECK`: Paper check
        - `CREDIT_CARD`: Credit card payment
        - `EFT_DIRECT_DEPOSIT`: EFT direct deposit
        - `E_TRANSFER`: Electronic transfer
        - `VENMO`: Venmo payment
        - `ZELLE`: Zelle payment
    BillPaymentRecipientType:
      type: string
      enum:
        - CARRIER
        - VENDOR
      description: |
        Type of recipient for the payment.
        - `CARRIER`: Payment to a carrier
        - `VENDOR`: Payment to a vendor
    BillPaymentApplication:
      type: object
      required:
        - id
        - billId
        - amount
      properties:
        id:
          type: string
          format: uuid
        billId:
          type: string
          format: uuid
          description: Bill (invoice) this payment applies to
        billFriendlyId:
          type: string
          description: Human-readable bill ID
          nullable: true
        amount:
          type: number
          description: Amount applied to this bill
        loadCarrierId:
          type: string
          format: uuid
          description: Associated load carrier (for carrier bills)
          nullable: true
        vendedServiceId:
          type: string
          format: uuid
          description: Associated vended service (for vendor bills)
          nullable: true
        shipmentId:
          type: string
          format: uuid
          nullable: true
        shipmentFriendlyId:
          type: string
          nullable: true
    BillPayment:
      type: object
      required:
        - id
        - paymentDate
        - recipientType
        - totalAmount
        - applications
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          description: Client-defined key
          nullable: true
        recipientType:
          $ref: '#/components/schemas/BillPaymentRecipientType'
        carrier:
          $ref: '#/components/schemas/CarrierReference'
        vendor:
          $ref: '#/components/schemas/VendorReference'
        carrierFactor:
          $ref: '#/components/schemas/CarrierFactorReference-2'
        paymentDate:
          type: string
          format: date
          description: Date the payment was made
        paymentMethodType:
          $ref: '#/components/schemas/BillPaymentMethodType'
        reference:
          type: string
          description: Check number, transaction ID, etc.
          nullable: true
        notes:
          type: string
          description: Additional notes
          nullable: true
        totalAmount:
          type: number
          description: Total payment amount (sum of all applications)
        overpayment:
          type: number
          description: Amount paid in excess of invoice totals
          nullable: true
        overpaymentCreditMemoId:
          type: string
          format: uuid
          description: Credit memo created for overpayment
          nullable: true
        applications:
          type: array
          items:
            $ref: '#/components/schemas/BillPaymentApplication'
          description: Individual bill payments in this group
        qboId:
          type: string
          description: QuickBooks Online bill payment ID
          nullable: true
        syncStatus:
          type: string
          enum:
            - pending
            - synced
            - error
          description: QuickBooks sync status
          nullable: true
        syncError:
          type: string
          description: QuickBooks sync error message
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          nullable: true
    BillPaymentApplicationInput:
      type: object
      required:
        - billId
        - amount
      properties:
        billId:
          type: string
          format: uuid
          description: Bill (invoice) to apply payment to
        amount:
          type: number
          minimum: 0.01
          description: Amount to apply to this bill
    BillPaymentInput:
      type: object
      required:
        - paymentDate
        - applications
      properties:
        paymentDate:
          type: string
          format: date
          description: Date of payment
        paymentMethodType:
          $ref: '#/components/schemas/BillPaymentMethodType'
        carrierFactorId:
          type: string
          format: uuid
          description: Carrier factor to pay (for factored payments)
        reference:
          type: string
          maxLength: 500
          description: Check number, transaction ID, etc.
        notes:
          type: string
          maxLength: 2000
          description: Additional notes
        applications:
          type: array
          items:
            $ref: '#/components/schemas/BillPaymentApplicationInput'
          minItems: 1
          description: Bills to pay
        allowOverpayment:
          type: boolean
          default: false
          description: Allow payment amount to exceed bill totals
    BillPaymentPatch:
      type: object
      properties:
        paymentDate:
          type: string
          format: date
        paymentMethodType:
          $ref: '#/components/schemas/BillPaymentMethodType'
        reference:
          type: string
          nullable: true
        notes:
          type: string
          nullable: true
        applications:
          type: array
          items:
            $ref: '#/components/schemas/BillPaymentApplicationPatch'
          description: Update payment applications
    BillPaymentFilter:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUIDFilter'
        carrierId:
          $ref: '#/components/schemas/UUIDFilter'
        vendorId:
          $ref: '#/components/schemas/UUIDFilter'
        carrierFactorId:
          $ref: '#/components/schemas/UUIDFilter'
        recipientType:
          type: object
          properties:
            equalTo:
              $ref: '#/components/schemas/BillPaymentRecipientType'
            in:
              type: array
              items:
                $ref: '#/components/schemas/BillPaymentRecipientType'
        paymentMethodType:
          $ref: '#/components/schemas/BillPaymentMethodTypeFilter'
        paymentDate:
          $ref: '#/components/schemas/DatetimeFilter'
        totalAmount:
          $ref: '#/components/schemas/FloatFilter'
        reference:
          $ref: '#/components/schemas/StringFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        and:
          type: array
          items:
            $ref: '#/components/schemas/BillPaymentFilter'
        or:
          type: array
          items:
            $ref: '#/components/schemas/BillPaymentFilter'
        not:
          $ref: '#/components/schemas/BillPaymentFilter'
    BillPaymentFilterRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/BillPaymentFilter'
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        cursor:
          type: string
    OutstandingBill:
      type: object
      properties:
        id:
          type: string
          format: uuid
        friendlyId:
          type: string
        entityType:
          $ref: '#/components/schemas/BillEntityType'
        carrier:
          $ref: '#/components/schemas/CarrierReference'
        vendor:
          $ref: '#/components/schemas/VendorReference'
        invoiceDate:
          type: string
          format: date
          nullable: true
        dueDate:
          type: string
          format: date
          nullable: true
        amount:
          type: number
        amountPaid:
          type: number
        openBalance:
          type: number
        isOverdue:
          type: boolean
        shipmentId:
          type: string
          format: uuid
          nullable: true
        shipmentFriendlyId:
          type: string
          nullable: true
    OutstandingBillsForPaymentResponse:
      type: object
      required:
        - bills
        - totalOutstanding
      properties:
        bills:
          type: array
          items:
            $ref: '#/components/schemas/OutstandingBill'
        totalOutstanding:
          type: number
          description: Total outstanding balance
        carrier:
          $ref: '#/components/schemas/CarrierReference'
        vendor:
          $ref: '#/components/schemas/VendorReference'
        carrierFactor:
          $ref: '#/components/schemas/CarrierFactorReference-2'
    SavedSearchLookup:
      type: object
      description: |
        Reference to a saved search by ID or client key.
        Provide either id or key (not both).
      properties:
        id:
          type: string
          format: uuid
          description: Saved search UUID
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          maxLength: 512
          description: Client-defined key for the saved search
          example: my-carrier-search
      example:
        id: 550e8400-e29b-41d4-a716-446655440000
    UUIDFilter:
      type: object
      description: Filter options for UUID fields (all operations)
      properties:
        equalTo:
          type: string
          format: uuid
          description: Exact match
        notEqualTo:
          type: string
          format: uuid
          description: Not equal to
        in:
          type: array
          items:
            type: string
            format: uuid
          description: Matches any UUID in the array
        notIn:
          type: array
          items:
            type: string
            format: uuid
          description: Does not match any UUID in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
    ValidationError:
      type: object
      required:
        - error
        - message
        - details
      properties:
        error:
          type: string
          description: Error code
          example: validation_error
        message:
          type: string
          description: Human-readable error message
        details:
          type: array
          description: Validation error details
          items:
            type: object
            required:
              - field
              - message
            properties:
              field:
                type: string
                description: Field name that failed validation
              message:
                type: string
                description: Validation error message
    WebhookEvent:
      type: string
      description: The type of webhook event
      enum:
        - CARRIER_ACTIVATED
        - CARRIER_CONTACT_CREATED
        - CARRIER_CONTACT_UPDATED
        - CARRIER_CONTACT_DELETED
        - CARRIER_CREATED
        - CARRIER_DEACTIVATED
        - CARRIER_DELETED
        - CARRIER_FACTOR_CREATED
        - CARRIER_FACTOR_UPDATED
        - CARRIER_FACTOR_DELETED
        - CARRIER_INVOICE_CREATED
        - CARRIER_PAYMENT_CREATED
        - CARRIER_PAYMENT_METHOD_CREATED
        - CARRIER_PAYMENT_METHOD_UPDATED
        - CARRIER_PAYMENT_METHOD_DELETED
        - CARRIER_UPDATED
        - COMMISSION_APPROVED
        - COMMISSION_CREATED
        - COMPANY_CREATED
        - COMPANY_UPDATED
        - COMPANY_DELETED
        - CUSTOMER_CREATED
        - CUSTOMER_UPDATED
        - CUSTOMER_DELETED
        - CUSTOMER_CONTACT_CREATED
        - CUSTOMER_CONTACT_UPDATED
        - CUSTOMER_CONTACT_DELETED
        - CUSTOMER_INVOICE_CREATED
        - CUSTOMER_PAYMENT_CREATED
        - DOCUMENT_UPLOADED
        - QUOTE_CREATED
        - QUOTE_LOST
        - QUOTE_QUOTED
        - QUOTE_REQUESTED
        - QUOTE_WON
        - SHIPMENT_BOOKED
        - SHIPMENT_CANCELED
        - SHIPMENT_CHECK_CALL
        - SHIPMENT_CREATED
        - SHIPMENT_DELETED
        - SHIPMENT_DELIVERED
        - SHIPMENT_DISPATCHED
        - SHIPMENT_DRAFT
        - SHIPMENT_IN_TRANSIT
        - SHIPMENT_LOADING
        - SHIPMENT_NEXT_CHECK_CALL_DUE
        - SHIPMENT_NEXT_CHECK_CALL_OVERDUE
        - SHIPMENT_OPEN
        - SHIPMENT_PICK_UP_NEAR_NOT_BOOKED
        - SHIPMENT_PICK_UP_NEAR_NOT_DISPATCHED
        - SHIPMENT_RATE_CON_EXPIRED
        - SHIPMENT_RATE_CON_NOT_SIGNED
        - SHIPMENT_RATE_CON_SIGNED
        - SHIPMENT_TENDER_PENDING
        - SHIPMENT_TENDER_REJECTED
        - SHIPMENT_UNLOADING
        - VENDOR_CREATED
        - VENDOR_UPDATED
        - VENDOR_DELETED
        - VENDOR_CONTACT_CREATED
        - VENDOR_CONTACT_UPDATED
        - VENDOR_CONTACT_DELETED
        - VENDOR_INVOICE_CREATED
        - VENDOR_PAYMENT_CREATED
        - VENDOR_PAYMENT_METHOD_CREATED
        - VENDOR_PAYMENT_METHOD_UPDATED
        - VENDOR_PAYMENT_METHOD_DELETED
        - LOCATION_CREATED
        - LOCATION_UPDATED
        - LOCATION_DELETED
        - LOCATION_CONTACT_CREATED
        - LOCATION_CONTACT_UPDATED
        - LOCATION_CONTACT_DELETED
    WebhookPayload:
      type: object
      required:
        - event
        - timestamp
        - data
      discriminator:
        propertyName: event
        mapping:
          CUSTOMER_CREATED: '#/components/schemas/CustomerChangedPayload'
          CUSTOMER_UPDATED: '#/components/schemas/CustomerChangedPayload'
          CUSTOMER_DELETED: '#/components/schemas/CustomerChangedPayload'
          COMPANY_CREATED: '#/components/schemas/CompanyChangedPayload'
          COMPANY_UPDATED: '#/components/schemas/CompanyChangedPayload'
          COMPANY_DELETED: '#/components/schemas/CompanyChangedPayload'
          CUSTOMER_CONTACT_CREATED: '#/components/schemas/CustomerContactChangedPayload'
          CUSTOMER_CONTACT_UPDATED: '#/components/schemas/CustomerContactChangedPayload'
          CUSTOMER_CONTACT_DELETED: '#/components/schemas/CustomerContactChangedPayload'
          CARRIER_CONTACT_CREATED: '#/components/schemas/CarrierContactChangedPayload'
          CARRIER_CONTACT_UPDATED: '#/components/schemas/CarrierContactChangedPayload'
          CARRIER_CONTACT_DELETED: '#/components/schemas/CarrierContactChangedPayload'
          CARRIER_CREATED: '#/components/schemas/CarrierChangedPayload'
          CARRIER_UPDATED: '#/components/schemas/CarrierChangedPayload'
          CARRIER_DELETED: '#/components/schemas/CarrierChangedPayload'
          CARRIER_ACTIVATED: '#/components/schemas/CarrierChangedPayload'
          CARRIER_DEACTIVATED: '#/components/schemas/CarrierChangedPayload'
          CARRIER_FACTOR_CREATED: '#/components/schemas/CarrierFactorChangedPayload'
          CARRIER_FACTOR_UPDATED: '#/components/schemas/CarrierFactorChangedPayload'
          CARRIER_FACTOR_DELETED: '#/components/schemas/CarrierFactorChangedPayload'
          CARRIER_PAYMENT_METHOD_CREATED: '#/components/schemas/CarrierPaymentMethodChangedPayload'
          CARRIER_PAYMENT_METHOD_UPDATED: '#/components/schemas/CarrierPaymentMethodChangedPayload'
          CARRIER_PAYMENT_METHOD_DELETED: '#/components/schemas/CarrierPaymentMethodChangedPayload'
          VENDOR_CREATED: '#/components/schemas/VendorChangedPayload'
          VENDOR_UPDATED: '#/components/schemas/VendorChangedPayload'
          VENDOR_DELETED: '#/components/schemas/VendorChangedPayload'
          VENDOR_CONTACT_CREATED: '#/components/schemas/VendorContactChangedPayload'
          VENDOR_CONTACT_UPDATED: '#/components/schemas/VendorContactChangedPayload'
          VENDOR_CONTACT_DELETED: '#/components/schemas/VendorContactChangedPayload'
          VENDOR_PAYMENT_METHOD_CREATED: '#/components/schemas/VendorPaymentMethodChangedPayload'
          VENDOR_PAYMENT_METHOD_UPDATED: '#/components/schemas/VendorPaymentMethodChangedPayload'
          VENDOR_PAYMENT_METHOD_DELETED: '#/components/schemas/VendorPaymentMethodChangedPayload'
          LOCATION_CREATED: '#/components/schemas/LocationChangedPayload'
          LOCATION_UPDATED: '#/components/schemas/LocationChangedPayload'
          LOCATION_DELETED: '#/components/schemas/LocationChangedPayload'
          LOCATION_CONTACT_CREATED: '#/components/schemas/LocationContactChangedPayload'
          LOCATION_CONTACT_UPDATED: '#/components/schemas/LocationContactChangedPayload'
          LOCATION_CONTACT_DELETED: '#/components/schemas/LocationContactChangedPayload'
          SHIPMENT_DELIVERED: '#/components/schemas/ShipmentDeliveredPayload'
      properties:
        event:
          $ref: '#/components/schemas/WebhookEvent'
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the event occurred
          example: '2025-01-15T14:30:00Z'
        data:
          type: object
          description: Event-specific data. Structure varies by event type.
          additionalProperties: true
        diff:
          type: array
          description: |
            Array of changes made during an UPDATE operation using json-diff-ts.
            Only present for UPDATE events. Null for CREATE and DELETE events.
            Each change follows the IChange interface from json-diff-ts library.
          items:
            $ref: '#/components/schemas/DiffChange'
          nullable: true
    CustomerChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - CUSTOMER_CREATED
                - CUSTOMER_UPDATED
                - CUSTOMER_DELETED
            data:
              $ref: '#/components/schemas/Customer'
    CompanyChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - COMPANY_CREATED
                - COMPANY_UPDATED
                - COMPANY_DELETED
            data:
              $ref: '#/components/schemas/Company'
    CustomerContactChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - CUSTOMER_CONTACT_CREATED
                - CUSTOMER_CONTACT_UPDATED
                - CUSTOMER_CONTACT_DELETED
            data:
              $ref: '#/components/schemas/CustomerContact'
    CarrierChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - CARRIER_CREATED
                - CARRIER_UPDATED
                - CARRIER_DELETED
            data:
              $ref: '#/components/schemas/Carrier'
    VendorChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - VENDOR_CREATED
                - VENDOR_UPDATED
                - VENDOR_DELETED
            data:
              $ref: '#/components/schemas/Vendor'
    VendorContactChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - VENDOR_CONTACT_CREATED
                - VENDOR_CONTACT_UPDATED
                - VENDOR_CONTACT_DELETED
            data:
              $ref: '#/components/schemas/VendorContact'
    ShipmentDeliveredPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - SHIPMENT_DELIVERED
            data:
              type: object
              required:
                - id
                - friendlyId
              properties:
                id:
                  type: string
                  format: uuid
                  description: Shipment UUID
                  example: 660e8400-e29b-41d4-a716-446655440000
                friendlyId:
                  type: string
                  description: Human-readable shipment ID
                  example: SHP-12345
                key:
                  type: string
                  description: Your system's reference ID for this shipment (if set)
                  example: ERP-SHIP-789
                  nullable: true
    CarrierPaymentMethodReference:
      type: object
      description: |
        Carrier payment method reference for embedding in Carrier responses.
        Identical to CarrierPaymentMethod but excludes the carrier and carrierId fields to avoid circular references.
      required:
        - id
        - paymentRecipientType
        - paymentMethodType
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique carrier payment method identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: CARRIER-PM-001
          nullable: true
        paymentRecipientType:
          $ref: '#/components/schemas/PaymentRecipientType'
          description: Who receives the payment (DIRECT or FACTOR)
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
          description: How payment is made
        status:
          type: string
          description: Payment method status
          example: ACTIVE
          nullable: true
        isPreferred:
          type: boolean
          description: Whether this is the preferred payment method
          example: true
          nullable: true
        email:
          type: string
          format: email
          description: Email address for payment notifications
          example: payments@carrier.com
          nullable: true
        phone:
          type: string
          description: Phone number for payment contact
          example: +1-555-123-4567
          nullable: true
        companyName:
          type: string
          description: Company name for this payment method
          example: Carrier Payments LLC
          nullable: true
        username:
          type: string
          description: Username for payment platforms
          example: carrier_payments
          nullable: true
        bankName:
          type: string
          description: Bank name
          example: Chase Bank
          nullable: true
        bankAddress:
          type: string
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
          nullable: true
        accountName:
          type: string
          description: Bank account holder name
          example: Carrier Transport Inc
          nullable: true
        accountNumber:
          type: string
          description: Bank account number (masked in responses)
          example: '****1234'
          nullable: true
        abaAch:
          type: string
          description: ABA/ACH routing number
          example: '021000021'
          nullable: true
        wire:
          type: string
          description: Wire transfer routing number
          example: '026009593'
          nullable: true
        swiftCode:
          type: string
          description: SWIFT/BIC code
          example: CHASUS33
          nullable: true
        eftInstitution:
          type: string
          description: EFT institution number (Canadian banking)
          example: '001'
          nullable: true
        eftTransit:
          type: string
          description: EFT transit number (Canadian banking)
          example: '00010'
          nullable: true
        clabe:
          type: string
          description: CLABE number (Mexican banking)
          example: '012180001234567897'
          nullable: true
        currency:
          type: string
          description: Preferred currency code
          example: USD
          nullable: true
        carrierFactor:
          description: Factoring company reference (when paymentRecipientType is FACTOR)
          $ref: '#/components/schemas/CarrierFactorReference'
          nullable: true
        paymentTerm:
          description: Payment terms
          $ref: '#/components/schemas/PaymentTermReference'
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was soft deleted
          example: null
          nullable: true
        deletedBy:
          readOnly: true
          description: User who deleted this payment method
          $ref: '#/components/schemas/UserReference'
          nullable: true
    CarrierContactReference:
      type: object
      description: |
        Carrier contact reference for embedding in Carrier responses.
        Identical to CarrierContact but excludes the carrier and carrierId fields to avoid circular references.
      required:
        - id
        - name
        - contactInfo
        - createdAt
      properties:
        object:
          type: string
          enum:
            - CARRIER_CONTACT
          readOnly: true
          description: Object type identifier
          example: CARRIER_CONTACT
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique contact identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CARRIER-CONTACT-001
          nullable: true
        name:
          type: string
          description: Contact person's name
          example: Jane Dispatcher
        contactInfo:
          allOf:
            - $ref: '#/components/schemas/ContactInfo'
          description: Contact information details (email, phone, title)
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/CarrierContactType'
          description: Types/roles this contact serves
          example:
            - DISPATCH
            - AFTER_HOURS
          nullable: true
        invitedUser:
          readOnly: true
          description: User account invited/created for this contact
          $ref: '#/components/schemas/UserReference'
          nullable: true
        deletedBy:
          readOnly: true
          description: User who deleted this contact
          $ref: '#/components/schemas/UserReference'
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was created
          example: '2025-01-15T10:00:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was soft deleted
          example: null
          nullable: true
    AgentCarrier:
      allOf:
        - $ref: '#/components/schemas/CarrierBase'
        - type: object
          description: Agent (interline/partner agent) carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - AGENT
              description: Carrier type discriminator
              example: AGENT
    AgentCarrierInput:
      allOf:
        - $ref: '#/components/schemas/CarrierInputBase'
        - type: object
          description: Input for creating an agent carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - AGENT
              description: Carrier type discriminator (must be AGENT)
              example: AGENT
    AgentCarrierPatch:
      allOf:
        - $ref: '#/components/schemas/CarrierPatchBase'
        - type: object
          description: Partial update for agent carrier
          properties:
            type:
              type: string
              enum:
                - AGENT
              description: Carrier type discriminator (optional - only needed if changing type)
              example: AGENT
    UUIDSearchCriteria:
      type: object
      required:
        - operator
      description: Search criteria for UUID fields
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - ONE_OF
            - NOT_ONE_OF
            - EXISTS
            - DOES_NOT_EXIST
          description: |
            Search operator:
            - `EQUALS`: Exact match
            - `NOT_EQUALS`: Not equal to
            - `ONE_OF`: Matches any UUID in array
            - `NOT_ONE_OF`: Does not match any UUID in array
            - `EXISTS`: Field has a value (not null)
            - `DOES_NOT_EXIST`: Field is null
        values:
          type: array
          items:
            type: string
            format: uuid
          description: Array of UUIDs for ONE_OF or NOT_ONE_OF operators
          example:
            - 550e8400-e29b-41d4-a716-446655440000
            - 550e8400-e29b-41d4-a716-446655440001
      example:
        operator: EQUALS
        values:
          - 550e8400-e29b-41d4-a716-446655440000
    KeywordSearchCriteria:
      type: object
      required:
        - operator
      description: Search criteria for keyword fields (exact match, no partial matching)
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - ONE_OF
            - NOT_ONE_OF
            - EXISTS
            - DOES_NOT_EXIST
          description: |
            Search operator:
            - `EQUALS`: Exact match
            - `NOT_EQUALS`: Not equal to
            - `ONE_OF`: Matches any value in array
            - `NOT_ONE_OF`: Does not match any value in array
            - `EXISTS`: Field has a value (not null)
            - `DOES_NOT_EXIST`: Field is null
        values:
          type: array
          items:
            type: string
          description: Array of values for ONE_OF or NOT_ONE_OF operators
          example:
            - ACTIVE
            - PENDING
      example:
        operator: ONE_OF
        values:
          - ACTIVE
          - PENDING
    TextSearchCriteria:
      type: object
      required:
        - operator
      description: Search criteria for text fields (supports wildcards and partial matching)
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - STARTS_WITH
            - ENDS_WITH
            - INCLUDES
            - ONE_OF
            - NOT_ONE_OF
            - EXISTS
            - DOES_NOT_EXIST
          description: |
            Search operator:
            - `EQUALS`: Exact match
            - `NOT_EQUALS`: Not equal to
            - `STARTS_WITH`: Begins with prefix
            - `ENDS_WITH`: Ends with suffix
            - `INCLUDES`: Contains substring
            - `ONE_OF`: Matches any value in array
            - `NOT_ONE_OF`: Does not match any value in array
            - `EXISTS`: Field has a value (not null)
            - `DOES_NOT_EXIST`: Field is null
        values:
          type: array
          items:
            type: string
          description: Array of values for ONE_OF or NOT_ONE_OF operators
          example:
            - value1
            - value2
      example:
        operator: INCLUDES
        values:
          - search term
    IntSearchCriteria:
      type: object
      required:
        - operator
      description: Search criteria for integer fields
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - GREATER_THAN
            - LESS_THAN
            - BETWEEN
            - NOT_BETWEEN
            - EXISTS
            - DOES_NOT_EXIST
          description: |
            Search operator:
            - `EQUALS`: Exact match
            - `NOT_EQUALS`: Not equal to
            - `GREATER_THAN`: Greater than value
            - `LESS_THAN`: Less than value
            - `BETWEEN`: Between min and max (inclusive)
            - `NOT_BETWEEN`: Not between min and max
            - `EXISTS`: Field has a value (not null)
            - `DOES_NOT_EXIST`: Field is null
        value:
          type: integer
          description: Single value for EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN
        min:
          type: integer
          description: Minimum value for BETWEEN or NOT_BETWEEN
        max:
          type: integer
          description: Maximum value for BETWEEN or NOT_BETWEEN
      example:
        operator: BETWEEN
        min: 10
        max: 100
    FloatSearchCriteria:
      type: object
      required:
        - operator
      description: Search criteria for float/decimal fields
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - GREATER_THAN
            - LESS_THAN
            - BETWEEN
            - NOT_BETWEEN
            - EXISTS
            - DOES_NOT_EXIST
          description: |
            Search operator:
            - `EQUALS`: Exact match
            - `NOT_EQUALS`: Not equal to
            - `GREATER_THAN`: Greater than value
            - `LESS_THAN`: Less than value
            - `BETWEEN`: Between min and max (inclusive)
            - `NOT_BETWEEN`: Not between min and max
            - `EXISTS`: Field has a value (not null)
            - `DOES_NOT_EXIST`: Field is null
        value:
          type: number
          format: float
          description: Single value for EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN
        min:
          type: number
          format: float
          description: Minimum value for BETWEEN or NOT_BETWEEN
        max:
          type: number
          format: float
          description: Maximum value for BETWEEN or NOT_BETWEEN
      example:
        operator: GREATER_THAN
        value: 1000.5
    RelativeTimeUnit:
      type: string
      enum:
        - YEAR
        - MONTH
        - WEEK
        - DAY
        - HOUR
        - MINUTE
        - SECOND
      description: |
        Time unit for relative time calculations:
        - `YEAR`: Years
        - `MONTH`: Months
        - `WEEK`: Weeks
        - `DAY`: Days
        - `HOUR`: Hours
        - `MINUTE`: Minutes
        - `SECOND`: Seconds
    DatetimeSearchCriteria:
      type: object
      required:
        - operator
      description: |
        Search criteria for datetime fields.
        Supports both absolute datetime values and relative time expressions.
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - BEFORE
            - AFTER
            - BETWEEN
            - NOT_BETWEEN
            - EXISTS
            - DOES_NOT_EXIST
          description: |
            Search operator:
            - `EQUALS`: Exact match
            - `NOT_EQUALS`: Not equal to
            - `BEFORE`: Before datetime
            - `AFTER`: After datetime
            - `BETWEEN`: Between min and max (inclusive)
            - `NOT_BETWEEN`: Not between min and max
            - `EXISTS`: Field has a value (not null)
            - `DOES_NOT_EXIST`: Field is null
        value:
          type: string
          format: date-time
          description: Absolute datetime for EQUALS, NOT_EQUALS
          example: '2025-01-15T10:00:00Z'
        min:
          type: string
          format: date-time
          description: Minimum datetime for BETWEEN or NOT_BETWEEN
          example: '2025-01-01T00:00:00Z'
        max:
          type: string
          format: date-time
          description: Maximum datetime for BETWEEN or NOT_BETWEEN
          example: '2025-12-31T23:59:59Z'
        valueRelative:
          type: integer
          description: |
            Relative time from now (negative for past, positive for future).
            Example: -7 with WEEK unit means 7 weeks ago.
        valueRelativeUnit:
          $ref: '#/components/schemas/RelativeTimeUnit'
        minRelative:
          type: integer
          description: Relative time for min boundary
        minRelativeUnit:
          $ref: '#/components/schemas/RelativeTimeUnit'
        maxRelative:
          type: integer
          description: Relative time for max boundary
        maxRelativeUnit:
          $ref: '#/components/schemas/RelativeTimeUnit'
      example:
        operator: AFTER
        value: '2025-01-01T00:00:00Z'
    SearchPaginationInput:
      type: object
      description: Pagination options for search requests
      properties:
        pageNumber:
          type: integer
          minimum: 1
          default: 1
          description: Page number (1-based)
          example: 1
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page (max 250)
          example: 50
      example:
        pageNumber: 1
        pageSize: 50
    SearchSortOption:
      type: object
      required:
        - field
        - order
      description: Sort option for search results
      properties:
        field:
          type: string
          description: Field name to sort by (must be an indexed field)
          example: createdAt
        order:
          type: string
          enum:
            - asc
            - desc
          description: Sort direction (ascending or descending)
          example: desc
      example:
        field: createdAt
        order: desc
    SearchPaginationInfo:
      type: object
      required:
        - pageNumber
        - pageSize
        - totalPages
      description: Pagination information for search results
      properties:
        pageNumber:
          type: integer
          description: Current page number
          example: 1
        pageSize:
          type: integer
          description: Number of results returned on this page
          example: 50
        totalPages:
          type: integer
          description: Total number of pages available
          example: 25
      example:
        pageNumber: 1
        pageSize: 50
        totalPages: 25
    ShowNotes:
      type: string
      enum:
        - ALL
        - SPLIT
      description: |
        Controls whether external notes are shown on all documents or split from carrier-facing notes.
        - `ALL`: Use external notes on customer-facing and carrier-facing documents
        - `SPLIT`: Use external notes on customer-facing documents and carrier notes on carrier-facing documents
    CustomerContactReference:
      type: object
      description: |
        Customer contact reference for embedding in Customer responses.
        Identical to CustomerContact but excludes the customer and customerId fields to avoid circular references.
      required:
        - id
        - name
        - isPrimary
        - contactInfo
        - createdAt
      properties:
        object:
          type: string
          enum:
            - CUSTOMER_CONTACT
          readOnly: true
          description: Object type identifier
          example: CUSTOMER_CONTACT
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique contact identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CONTACT-JOHN-001
          nullable: true
        name:
          type: string
          description: Contact person's name
          example: John Smith
        contactInfo:
          allOf:
            - $ref: '#/components/schemas/ContactInfo'
          description: Contact information details (email, phone, title)
        phoneExtension:
          type: string
          description: Phone extension specific to this contact role
          example: '1234'
          nullable: true
        isPrimary:
          type: boolean
          description: Whether this is the primary contact
          example: true
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/CustomerContactType'
          description: Types/roles this contact serves
          example:
            - BILLING
            - ACCOUNT_MANAGER
          nullable: true
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/CustomerContactNotificationType'
          description: Shipment notification types
          example:
            - SHIPMENT_PICKED_UP
            - SHIPMENT_DELIVERED
          nullable: true
        invitedUser:
          readOnly: true
          description: User account invited/created for this contact
          $ref: '#/components/schemas/UserReference'
          nullable: true
        deletedBy:
          readOnly: true
          description: User who deleted this contact
          $ref: '#/components/schemas/UserReference'
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was created
          example: '2025-01-15T10:00:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was soft deleted
          example: null
          nullable: true
    DateSearchCriteria:
      type: object
      required:
        - operator
      description: |
        Search criteria for date fields (no time component).
        Supports both absolute date values and relative time expressions.
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - BEFORE
            - AFTER
            - BETWEEN
            - NOT_BETWEEN
            - EXISTS
            - DOES_NOT_EXIST
          description: Search operator (same as DatetimeSearchCriteria)
        value:
          type: string
          format: date
          description: Absolute date for EQUALS, NOT_EQUALS
          example: '2025-01-15'
        min:
          type: string
          format: date
          description: Minimum date for BETWEEN or NOT_BETWEEN
          example: '2025-01-01'
        max:
          type: string
          format: date
          description: Maximum date for BETWEEN or NOT_BETWEEN
          example: '2025-12-31'
        valueRelative:
          type: integer
          description: Relative time from now
        valueRelativeUnit:
          $ref: '#/components/schemas/RelativeTimeUnit'
        minRelative:
          type: integer
        minRelativeUnit:
          $ref: '#/components/schemas/RelativeTimeUnit'
        maxRelative:
          type: integer
        maxRelativeUnit:
          $ref: '#/components/schemas/RelativeTimeUnit'
      example:
        operator: BETWEEN
        min: '2025-01-01'
        max: '2025-01-31'
    LocationAddressInput:
      allOf:
        - $ref: '#/components/schemas/AddressInput'
        - type: object
          required:
            - state
            - zipCode
      description: |
        Address for a customer location. Same shape as AddressInput, but `state`
        and `zipCode` are required (location addresses always carry them).
    BooleanSearchCriteria:
      type: object
      required:
        - operator
      description: Search criteria for boolean fields
      properties:
        operator:
          type: string
          enum:
            - 'TRUE'
            - 'FALSE'
          description: |
            Search operator:
            - `TRUE`: Field is true
            - `FALSE`: Field is false
      example:
        operator: 'TRUE'
    EquipmentCategory:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
          description: Category id (use as the `categoryId` list filter)
        name:
          type: string
          description: Category display name
          example: Van
    EquipmentGroup:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
          description: Group id (use as the `groupId` list filter)
        name:
          type: string
          description: Top-level group display name
          example: Trailer
    EquipmentSubcategory:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
          description: Subcategory id (use as the `subcategoryId` list filter)
        name:
          type: string
          description: Subcategory display name
    Equipment:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
          description: Equipment id (referenced by order/load equipment arrays)
        name:
          type: string
          description: Display name (e.g., "Van 53'")
          example: Van 53'
        category:
          description: Equipment category
          $ref: '#/components/schemas/EquipmentCategory'
          nullable: true
        group:
          description: Top-level equipment group
          $ref: '#/components/schemas/EquipmentGroup'
          nullable: true
        subcategory:
          description: Equipment subcategory
          $ref: '#/components/schemas/EquipmentSubcategory'
          nullable: true
    ChargeCode:
      type: object
      required:
        - id
        - code
        - name
        - description
      properties:
        id:
          type: integer
          description: Charge code id (referenced by charge `chargeCodeId` fields)
          example: 1
        code:
          type: string
          description: Short accounting code
          example: LH
        name:
          type: string
          description: Display name
          example: Linehaul
        description:
          type: string
          description: Full description
          example: Linehaul charges
    SpecialRequirementType:
      type: string
      enum:
        - EQUIPMENT
        - DRIVER
        - FREIGHT
        - SHIPPER_LOCATION
      description: |
        What the requirement applies to.
        - `EQUIPMENT`: Equipment accessories (e.g., tarps, straps)
        - `DRIVER`: Driver services (e.g., team service, TWIC)
        - `FREIGHT`: Freight handling characteristics
        - `SHIPPER_LOCATION`: Location constraints
    SpecialRequirement:
      type: object
      required:
        - id
        - name
        - type
      properties:
        id:
          type: string
          format: uuid
          description: Special-requirement id (referenced by order/load specialRequirements arrays)
        name:
          type: string
          description: Display name (e.g., "Tarps")
          example: Tarps
        type:
          $ref: '#/components/schemas/SpecialRequirementType'
    UserReference-2:
      type: object
      description: |
        User reference for embedding in Team responses.
        Identical to User but excludes the teams array to avoid circular references.
      required:
        - id
        - email
        - status
        - roles
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - USER
          readOnly: true
          description: Object type identifier
          example: USER
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique user identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        email:
          type: string
          format: email
          description: User's email address
          example: john.doe@example.com
        name:
          type: string
          description: User's full name
          example: John Doe
          nullable: true
        phone:
          type: string
          description: User's phone number
          example: +1-555-123-4567
          nullable: true
        phoneExt:
          type: string
          description: Phone extension
          example: '123'
          nullable: true
        status:
          $ref: '#/components/schemas/UserStatus'
        roles:
          type: array
          description: User's roles within the organization
          items:
            $ref: '#/components/schemas/UserRole'
          example:
            - CUSTOMER_REP
            - ADMIN
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier for this user
          example: ERP-USER-12345
          nullable: true
        datUsername:
          type: string
          description: DAT (Load Board) integration username
          example: johndoe_dat
          nullable: true
        mcpUsername:
          type: string
          description: MyCarrierPortal integration username
          example: johndoe_mcp
          nullable: true
        avatarId:
          type: string
          format: uuid
          description: Profile avatar document ID
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when user was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when user was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when user was soft-deleted (null if active)
          example: null
          nullable: true
    TeamReference:
      type: object
      description: |
        Team reference for embedding in User responses.
        Identical to Team but excludes the users array to avoid circular references.
      required:
        - id
        - name
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - TEAM
          readOnly: true
          description: Object type identifier
          example: TEAM
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique team identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
          description: Team name
          example: Sales Team - West Coast
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier for this team
          example: ERP-TEAM-WEST
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when team was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when team was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when team was soft-deleted (null if active)
          example: null
          nullable: true
    Currency-2:
      type: string
      description: Currency code
      enum:
        - ARS
        - AUD
        - BRL
        - CAD
        - CNY
        - EUR
        - GBP
        - IDR
        - INR
        - JPY
        - KRW
        - MXN
        - RUB
        - SAR
        - TRY
        - USD
        - ZAR
    CurrencyFilter:
      type: object
      description: Filter for currency enum field
      properties:
        equalTo:
          $ref: '#/components/schemas/Currency-2'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/Currency-2'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/Currency-2'
          description: Matches any value in the list
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/Currency-2'
          description: Does not match any value in the list
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    PaymentMethodType-2:
      type: string
      description: Payment method type
      enum:
        - ACH_WIRE
        - ZELLE
        - VENMO
        - ACH
        - CHECK
        - WIRE
        - CAD_EFT
        - TRIUMPH_PAY
        - COMCHECK
        - EFS
        - ECHECK
      example: ACH
    VendorPaymentMethodReference:
      type: object
      description: |
        Vendor payment method reference for embedding in Vendor responses.
        Identical to VendorPaymentMethod but excludes the vendor and vendorId fields to avoid circular references.
      required:
        - id
        - paymentMethodType
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique vendor payment method identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: VENDOR-PM-001
          nullable: true
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType-2'
          description: How payment is made
        status:
          type: string
          description: Payment method status
          example: ACTIVE
          nullable: true
        isPreferred:
          type: boolean
          description: Whether this is the preferred payment method
          example: true
          nullable: true
        email:
          type: string
          format: email
          description: Email address for payment notifications
          example: payments@vendor.com
          nullable: true
        phone:
          type: string
          description: Phone number for payment contact
          example: +1-555-123-4567
          nullable: true
        companyName:
          type: string
          description: Company name for this payment method
          example: Vendor Payments LLC
          nullable: true
        username:
          type: string
          description: Username for payment platforms
          example: vendor_payments
          nullable: true
        bankName:
          type: string
          description: Bank name
          example: Chase Bank
          nullable: true
        bankAddress:
          type: string
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
          nullable: true
        accountName:
          type: string
          description: Bank account holder name
          example: Vendor Services Inc
          nullable: true
        accountNumber:
          type: string
          description: Bank account number (masked in responses)
          example: '****1234'
          nullable: true
        abaAch:
          type: string
          description: ABA/ACH routing number
          example: '021000021'
          nullable: true
        wire:
          type: string
          description: Wire transfer routing number
          example: '026009593'
          nullable: true
        swiftCode:
          type: string
          description: SWIFT/BIC code
          example: CHASUS33
          nullable: true
        eftInstitution:
          type: string
          description: EFT institution number (Canadian banking)
          example: '001'
          nullable: true
        eftTransit:
          type: string
          description: EFT transit number (Canadian banking)
          example: '00010'
          nullable: true
        clabe:
          type: string
          description: CLABE number (Mexican banking)
          example: '012180001234567897'
          nullable: true
        currency:
          type: string
          description: Preferred currency code
          example: USD
          nullable: true
        paymentTerm:
          description: Payment terms
          $ref: '#/components/schemas/PaymentTermReference'
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was soft deleted
          example: null
          nullable: true
        deletedBy:
          readOnly: true
          description: User who deleted this payment method
          $ref: '#/components/schemas/UserReference'
          nullable: true
    VendorContactReference:
      type: object
      description: |
        Vendor contact reference for embedding in Vendor responses.
        Identical to VendorContact but excludes the vendor and vendorId fields to avoid circular references.
      required:
        - id
        - createdAt
      properties:
        object:
          type: string
          enum:
            - VENDOR_CONTACT
          readOnly: true
          description: Object type identifier
          example: VENDOR_CONTACT
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique contact identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-VENDOR-CONTACT-001
          nullable: true
        email:
          type: string
          format: email
          description: Contact email address
          example: john.smith@abcwarehouse.com
          nullable: true
        phone:
          type: string
          description: Contact phone number
          example: +1-555-123-4567
          nullable: true
        role:
          type: string
          description: Contact role or title (deprecated - use roles array)
          example: Billing Manager
          nullable: true
        roles:
          type: array
          items:
            $ref: '#/components/schemas/VendorContactRole'
          description: Types/roles this contact serves
          example:
            - BILLING
            - AGENT
          nullable: true
        deletedBy:
          readOnly: true
          description: User who deleted this contact
          $ref: '#/components/schemas/UserReference'
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was created
          example: '2025-01-15T10:00:00Z'
        deletedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was soft deleted
          example: null
          nullable: true
    PaymentMethodTypeFilter-2:
      type: object
      description: Filter for payment method type
      properties:
        equalTo:
          $ref: '#/components/schemas/PaymentMethodType-2'
        notEqualTo:
          $ref: '#/components/schemas/PaymentMethodType-2'
        in:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodType-2'
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodType-2'
    ShipmentStatus:
      type: string
      enum:
        - DRAFT
        - TENDER_PENDING
        - ON_HOLD
        - PLANNING
        - SELECTED
        - BOOKED
        - DISPATCHED
        - LOADING
        - PICKED_UP
        - IN_TRANSIT
        - UNLOADING
        - ARRIVED_AT_DELIVERY_TERMINAL
        - OUT_FOR_DELIVERY
        - RECOVERED
        - DELIVERED
        - CANCELED
        - TENDER_REJECTED
        - CONSOLIDATED
      description: |
        Current status of the shipment.

        Lifecycle stages:
        - `DRAFT`: Shipment is being created, not yet ready for processing
        - `TENDER_PENDING`: Awaiting carrier tender acceptance
        - `TENDER_REJECTED`: Carrier rejected the tender
        - `ON_HOLD`: Shipment is temporarily paused
        - `PLANNING`: Shipment is being planned/scheduled
        - `SELECTED`: Carrier has been selected
        - `BOOKED`: Carrier has confirmed the booking
        - `DISPATCHED`: Shipment has been dispatched to carrier

        In-transit stages:
        - `LOADING`: Freight is being loaded at pickup
        - `PICKED_UP`: Freight has been picked up
        - `IN_TRANSIT`: Shipment is in transit
        - `UNLOADING`: Freight is being unloaded at delivery
        - `ARRIVED_AT_DELIVERY_TERMINAL`: Arrived at delivery terminal (LTL)
        - `OUT_FOR_DELIVERY`: Out for final delivery
        - `RECOVERED`: Shipment has been recovered

        Final stages:
        - `DELIVERED`: Shipment has been delivered
        - `CANCELED`: Shipment has been canceled
        - `CONSOLIDATED`: Merged into a consolidated shipment
    DocumentEntityType:
      type: string
      enum:
        - ORDER
        - LOAD
        - SHIPMENT
        - CARRIER
        - CUSTOMER
        - VENDOR
      description: |
        Entity kind for entity-scoped document filtering.
        - `ORDER`: Customer-side documents attached to an order
        - `LOAD`: Carrier-side documents attached to a load's carrier assignments
        - `SHIPMENT`: Everything on the shipment — order and load documents combined
        - `CARRIER`: Documents on a carrier profile
        - `CUSTOMER`: Documents on a customer
        - `VENDOR`: Documents on a vendor
    DocumentTypeFilter:
      type: object
      properties:
        equalTo:
          $ref: '#/components/schemas/DocumentType'
        notEqualTo:
          $ref: '#/components/schemas/DocumentType'
        in:
          type: array
          items:
            $ref: '#/components/schemas/DocumentType'
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/DocumentType'
      description: Filter for document type field
    DocumentStatusFilter:
      type: object
      properties:
        equalTo:
          $ref: '#/components/schemas/DocumentStatus'
        notEqualTo:
          $ref: '#/components/schemas/DocumentStatus'
        in:
          type: array
          items:
            $ref: '#/components/schemas/DocumentStatus'
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/DocumentStatus'
      description: Filter for document status field
    QuoteStatusFilter:
      type: object
      properties:
        equalTo:
          $ref: '#/components/schemas/QuoteStatus'
        notEqualTo:
          $ref: '#/components/schemas/QuoteStatus'
        in:
          type: array
          items:
            $ref: '#/components/schemas/QuoteStatus'
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/QuoteStatus'
    QuoteSideFilter:
      type: object
      properties:
        equalTo:
          $ref: '#/components/schemas/QuoteSide'
        notEqualTo:
          $ref: '#/components/schemas/QuoteSide'
        in:
          type: array
          items:
            $ref: '#/components/schemas/QuoteSide'
    OrderSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
        key:
          type: string
          nullable: true
        mode:
          $ref: '#/components/schemas/TransportMode'
        origin:
          type: object
          properties:
            city:
              type: string
            stateProvince:
              type: string
            postalCode:
              type: string
              nullable: true
        destination:
          type: object
          properties:
            city:
              type: string
            stateProvince:
              type: string
            postalCode:
              type: string
              nullable: true
        pickUpDate:
          type: string
          format: date
          nullable: true
        deliveryDate:
          type: string
          format: date
          nullable: true
        equipment:
          type: array
          items:
            type: string
        weight:
          type: number
          nullable: true
        mileage:
          type: number
          nullable: true
      description: Summary of order details (embedded in Quote response)
    ShipmentSearchCriteria:
      type: object
      description: |
        Search criteria for filtering shipments.
        Note: Only active (non-deleted) shipments are searchable.
      properties:
        id:
          $ref: '#/components/schemas/UUIDSearchCriteria'
        friendlyId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        status:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Shipment status (PENDING, BOOKED, IN_TRANSIT, DELIVERED, CANCELED, etc.)
        orderStatus:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: AR (accounts receivable) status
        loadStatuses:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: AP (accounts payable) statuses for carriers/vendors
        mode:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Transportation mode (TL, LTL, AIR, OCEAN, RAIL)
        tonu:
          $ref: '#/components/schemas/BooleanSearchCriteria'
          description: Truck Order Not Used flag
        pickUp:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Origin city and state
        pickUpCity:
          $ref: '#/components/schemas/TextSearchCriteria'
        pickUpState:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        pickUpZipCode:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        pickUpCountry:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        dropOff:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Destination city and state
        dropOffCity:
          $ref: '#/components/schemas/TextSearchCriteria'
        dropOffState:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        dropOffZipCode:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        dropOffCountry:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        pickUpStartDatetime:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
          description: Scheduled pickup datetime
        dropOffStartDatetime:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
          description: Scheduled delivery datetime
        bookedAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
          description: When carrier was booked
        shipperId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Customer ID
        shipperName:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Customer name
        carrierIds:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Carrier IDs
        carrierNames:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Carrier names
        primaryRepId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
        primaryRepName:
          $ref: '#/components/schemas/TextSearchCriteria'
        bookingRepIds:
          $ref: '#/components/schemas/UUIDSearchCriteria'
        bookingRepNames:
          $ref: '#/components/schemas/TextSearchCriteria'
        groupId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Team ID
        groupName:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Team name
        equipmentType:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        weight:
          $ref: '#/components/schemas/FloatSearchCriteria'
        totalMiles:
          $ref: '#/components/schemas/FloatSearchCriteria'
        revenue:
          $ref: '#/components/schemas/FloatSearchCriteria'
        cost:
          $ref: '#/components/schemas/FloatSearchCriteria'
        profit:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Gross profit
        profitMargin:
          $ref: '#/components/schemas/FloatSearchCriteria'
        referenceValues:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Reference values (PO, BOL, customer ref, etc.)
        customerRef:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        bol:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        po:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        quoteId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
        quoteFriendlyId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        arInvoiceId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
        arInvoiceFriendlyId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        apInvoiceIds:
          $ref: '#/components/schemas/UUIDSearchCriteria'
        apInvoiceFriendlyIds:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        createdAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
        orderCreatedAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
    ShipmentSearchRequest:
      type: object
      description: Request body for searching shipments
      properties:
        criteria:
          $ref: '#/components/schemas/ShipmentSearchCriteria'
          description: Search criteria to filter shipments
        pagination:
          $ref: '#/components/schemas/SearchPaginationInput'
        sort:
          type: array
          items:
            $ref: '#/components/schemas/SearchSortOption'
          maxItems: 3
          description: Sort options for the search results
        savedSearch:
          $ref: '#/components/schemas/SavedSearchLookup'
          description: Optional saved search to load preferences from
        format:
          type: string
          enum:
            - flat
            - full
          default: flat
          description: |
            Response format:
            - flat: Returns only indexed fields (default, faster)
            - full: Returns complete shipment objects
    ShipmentSearchRow:
      type: object
      description: |
        Flattened shipment data from the search index. Pickup location arrays are
        ordered by ascending stop sequence. Drop-off location arrays are ordered by
        descending stop sequence, with the final destination first. For a side with
        multiple stops, its location arrays use matching stop indexes and empty
        strings preserve missing values. For a side with one stop, an individual
        missing field is omitted instead of returned as an array containing an empty
        string, so sibling arrays can be omitted independently.
      properties:
        object:
          type: string
          enum:
            - SHIPMENT_SEARCH_ROW
          description: Object type identifier
        id:
          type: string
          format: uuid
        friendlyId:
          type: string
          example: SHP-0001
        status:
          type: string
        orderStatus:
          type: string
          nullable: true
        mode:
          type: string
          nullable: true
        tonu:
          type: boolean
          nullable: true
        pickUp:
          type: array
          items:
            type: string
          description: Origin city and state values for all pickup stops
          nullable: true
        pickUpCity:
          type: array
          items:
            type: string
          nullable: true
        pickUpState:
          type: array
          items:
            type: string
          nullable: true
        pickUpZipCode:
          type: array
          items:
            type: string
          nullable: true
        pickUpCountry:
          type: array
          items:
            type: string
          nullable: true
        dropOff:
          type: array
          items:
            type: string
          description: Destination city and state values for all drop-off stops
          nullable: true
        dropOffCity:
          type: array
          items:
            type: string
          nullable: true
        dropOffState:
          type: array
          items:
            type: string
          nullable: true
        dropOffZipCode:
          type: array
          items:
            type: string
          nullable: true
        dropOffCountry:
          type: array
          items:
            type: string
          nullable: true
        pickUpStartDatetime:
          type: string
          format: date-time
          nullable: true
        dropOffStartDatetime:
          type: string
          format: date-time
          nullable: true
        bookedAt:
          type: string
          format: date-time
          nullable: true
        shipperId:
          type: string
          format: uuid
        shipperName:
          type: string
        carrierIds:
          type: array
          items:
            type: string
            format: uuid
        carrierNames:
          type: array
          items:
            type: string
        primaryRepId:
          type: string
          format: uuid
          nullable: true
        primaryRepName:
          type: string
          nullable: true
        groupId:
          type: string
          format: uuid
          nullable: true
        groupName:
          type: string
          nullable: true
        equipmentType:
          type: array
          items:
            type: string
        weight:
          type: number
          nullable: true
        totalMiles:
          type: number
        stopsCount:
          type: integer
        revenue:
          type: number
        cost:
          type: number
        profit:
          type: number
          nullable: true
        profitMargin:
          type: number
          nullable: true
        referenceValues:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        orderCreatedAt:
          type: string
          format: date-time
      required:
        - object
        - id
        - friendlyId
        - status
        - shipperId
        - shipperName
        - createdAt
    OrderReference:
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          description: Reference type (e.g., BOL_NUMBER)
        value:
          type: string
          description: Reference value
    LoadCarrierSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
        carrier:
          $ref: '#/components/schemas/CarrierReference'
        status:
          type: string
          enum:
            - ACTIVE
            - TONU
            - BOUNCED
        bookedAt:
          type: string
          format: date-time
          nullable: true
        dispatchedAt:
          type: string
          format: date-time
          nullable: true
        removedAt:
          type: string
          format: date-time
          description: |
            When this carrier was removed from the load (bounce/TONU). Removed
            carriers stay in the array as history, but their charges are NOT
            included in the load's `totalCost`.
          nullable: true
        totalCost:
          type: number
          nullable: true
    LoadSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
        friendlyId:
          type: string
          description: Human-readable load ID (e.g., "LD-12345")
        key:
          type: string
          description: Client-defined reference identifier for this load
          nullable: true
        status:
          $ref: '#/components/schemas/ShipmentLifecycleStatus'
        mode:
          $ref: '#/components/schemas/TransportMode'
        carriers:
          type: array
          items:
            $ref: '#/components/schemas/LoadCarrierSummary'
          description: Flattened carriers array
        totalCost:
          type: number
          nullable: true
    ServiceSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
        key:
          type: string
          nullable: true
        vendor:
          $ref: '#/components/schemas/VendorReference'
        status:
          type: string
          enum:
            - ACTIVE
            - AWAITING_INVOICE
            - INVOICE_IN_REVIEW
            - APPROVED_TO_PAY
            - PAID
            - CANCELED
        cost:
          type: number
          nullable: true
    ShipmentSearchResponse:
      type: object
      description: Response for shipment search requests
      required:
        - data
        - pagination
        - totalResults
      properties:
        data:
          type: array
          description: Search results - either flat rows or full shipment objects based on format parameter
          items:
            oneOf:
              - $ref: '#/components/schemas/ShipmentSearchRow'
              - $ref: '#/components/schemas/Shipment'
            discriminator:
              propertyName: object
              mapping:
                SHIPMENT_SEARCH_ROW: '#/components/schemas/ShipmentSearchRow'
                SHIPMENT: '#/components/schemas/Shipment'
        pagination:
          $ref: '#/components/schemas/SearchPaginationInfo'
        totalResults:
          type: integer
          description: Total number of matching results
          minimum: 0
    ShipmentStatusFilter:
      type: object
      properties:
        equalTo:
          $ref: '#/components/schemas/ShipmentLifecycleStatus'
        notEqualTo:
          $ref: '#/components/schemas/ShipmentLifecycleStatus'
        in:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentLifecycleStatus'
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentLifecycleStatus'
    LoadStatusFilter:
      type: object
      properties:
        equalTo:
          $ref: '#/components/schemas/LoadStatus'
        notEqualTo:
          $ref: '#/components/schemas/LoadStatus'
        in:
          type: array
          items:
            $ref: '#/components/schemas/LoadStatus'
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/LoadStatus'
    LoadStop:
      type: object
      properties:
        id:
          type: string
          format: uuid
        orderStopId:
          type: string
          format: uuid
          description: Reference to the order stop
        sequence:
          type: integer
        type:
          type: string
          enum:
            - PICKUP
            - DELIVERY
        address:
          allOf:
            - $ref: '#/components/schemas/Address'
          description: |
            Full address from the stop's linked location. Absent when the stop
            has no linked shipper location.
        scheduledArrival:
          type: string
          format: date-time
          nullable: true
        actualArrival:
          type: string
          format: date-time
          nullable: true
        actualDeparture:
          type: string
          format: date-time
          nullable: true
    LoadCarrierCharge:
      type: object
      properties:
        id:
          type: string
          format: uuid
        chargeCodeId:
          type: integer
          description: Charge code id. Resolve code/name via the reference-data charge-codes endpoint.
          nullable: true
        description:
          type: string
          nullable: true
        amount:
          type: number
          description: Extended line total (rate × quantity)
        quantity:
          type: number
          default: 1
        rate:
          type: number
          description: Unit rate for one quantity of this charge
          nullable: true
    AddCarrierResponse:
      type: object
      required:
        - loadId
        - loadCarrierId
      properties:
        loadId:
          type: string
          format: uuid
        loadCarrierId:
          type: string
          format: uuid
          description: The new load carrier ID
        loadCarrier:
          $ref: '#/components/schemas/LoadCarrier'
    RebookLoadResponse:
      type: object
      required:
        - originalLoadId
        - newLoadId
      properties:
        originalLoadId:
          type: string
          format: uuid
        newLoadId:
          type: string
          format: uuid
        newLoadKey:
          type: string
          nullable: true
    LoadCarrierRemovalReason:
      type: string
      enum:
        - CAN_NO_LONGER_TAKE_LOAD
        - LOAD_GIVEN_BACK
        - RATE_CON_REJECTED
        - CUSTOMER_NOT_READY_FOR_PU
        - CONSIGNEE_NOT_READY_FOR_DEL
        - FORGOT_TO_BOUNCE_CARRIER
        - OTHER
      description: |
        Reason for removing a carrier from a load. Whether the removal counts as
        a bounce or a TONU is the removal type, tracked separately.
    ServiceStatusFilter:
      type: object
      properties:
        equalTo:
          $ref: '#/components/schemas/ServiceStatus'
        notEqualTo:
          $ref: '#/components/schemas/ServiceStatus'
        in:
          type: array
          items:
            $ref: '#/components/schemas/ServiceStatus'
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/ServiceStatus'
    ServiceCharge:
      type: object
      properties:
        id:
          type: string
          format: uuid
        chargeCode:
          $ref: '#/components/schemas/ResourceReference'
        description:
          type: string
          nullable: true
        amount:
          type: number
        quantity:
          type: number
          default: 1
    InvoiceStatusFilter:
      type: object
      properties:
        equalTo:
          $ref: '#/components/schemas/InvoiceStatus'
        notEqualTo:
          $ref: '#/components/schemas/InvoiceStatus'
        in:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceStatus'
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceStatus'
    PaymentMethodType-3:
      type: string
      enum:
        - ACH_WIRE
        - ZELLE
        - VENMO
        - CHECK
        - EFT_DIRECT_DEPOSIT
        - E_TRANSFER
        - CREDIT_CARD
      description: |
        Payment method type.
        - `ACH_WIRE`: ACH or wire transfer
        - `ZELLE`: Zelle payment
        - `VENMO`: Venmo payment
        - `CHECK`: Paper check
        - `EFT_DIRECT_DEPOSIT`: EFT direct deposit
        - `E_TRANSFER`: Electronic transfer
        - `CREDIT_CARD`: Credit card payment
    PaymentMethodTypeFilter-3:
      type: object
      properties:
        equalTo:
          $ref: '#/components/schemas/PaymentMethodType-3'
        notEqualTo:
          $ref: '#/components/schemas/PaymentMethodType-3'
        in:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodType-3'
    CreditMemoStatusFilter:
      type: object
      properties:
        equalTo:
          $ref: '#/components/schemas/CreditMemoStatus'
        notEqualTo:
          $ref: '#/components/schemas/CreditMemoStatus'
        in:
          type: array
          items:
            $ref: '#/components/schemas/CreditMemoStatus'
    BillStatusFilter:
      type: object
      properties:
        equalTo:
          $ref: '#/components/schemas/BillStatus'
        notEqualTo:
          $ref: '#/components/schemas/BillStatus'
        in:
          type: array
          items:
            $ref: '#/components/schemas/BillStatus'
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/BillStatus'
    BillEntityTypeFilter:
      type: object
      properties:
        equalTo:
          $ref: '#/components/schemas/BillEntityType'
        in:
          type: array
          items:
            $ref: '#/components/schemas/BillEntityType'
    BillPaymentMethodTypeFilter:
      type: object
      properties:
        equalTo:
          $ref: '#/components/schemas/BillPaymentMethodType'
        in:
          type: array
          items:
            $ref: '#/components/schemas/BillPaymentMethodType'
    CarrierFactorReference-2:
      type: object
      properties:
        id:
          type: string
          format: uuid
        companyName:
          type: string
        bankName:
          type: string
          nullable: true
    BillPaymentApplicationPatch:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Existing application ID (for update)
        billId:
          type: string
          format: uuid
          description: Bill ID (for new applications)
        amount:
          type: number
          minimum: 0.01
        delete:
          type: boolean
          description: Set to true to remove this application
    CarrierContactChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - CARRIER_CONTACT_CREATED
                - CARRIER_CONTACT_UPDATED
                - CARRIER_CONTACT_DELETED
            data:
              $ref: '#/components/schemas/CarrierContact'
    CarrierFactorChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - CARRIER_FACTOR_CREATED
                - CARRIER_FACTOR_UPDATED
                - CARRIER_FACTOR_DELETED
            data:
              $ref: '#/components/schemas/CarrierFactor'
    CarrierPaymentMethodChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - CARRIER_PAYMENT_METHOD_CREATED
                - CARRIER_PAYMENT_METHOD_UPDATED
                - CARRIER_PAYMENT_METHOD_DELETED
            data:
              $ref: '#/components/schemas/CarrierPaymentMethod'
    VendorPaymentMethodChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - VENDOR_PAYMENT_METHOD_CREATED
                - VENDOR_PAYMENT_METHOD_UPDATED
                - VENDOR_PAYMENT_METHOD_DELETED
            data:
              $ref: '#/components/schemas/VendorPaymentMethod'
    LocationChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - LOCATION_CREATED
                - LOCATION_UPDATED
                - LOCATION_DELETED
            data:
              $ref: '#/components/schemas/Location'
    LocationContactChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - LOCATION_CONTACT_CREATED
                - LOCATION_CONTACT_UPDATED
                - LOCATION_CONTACT_DELETED
            data:
              $ref: '#/components/schemas/LocationContact'
    DiffOperation:
      type: string
      description: The type of diff operation from json-diff-ts
      enum:
        - REMOVE
        - ADD
        - UPDATE
    DiffChange:
      type: object
      description: |
        Represents a single change from json-diff-ts IChange interface.
        For nested object changes, the changes array will contain child changes.
      required:
        - type
        - key
      properties:
        type:
          $ref: '#/components/schemas/DiffOperation'
        key:
          type: string
          description: The property name that changed
          example: status
        embeddedKey:
          type: string
          description: Optional key used when comparing array elements by identifier
          example: id
        value:
          description: |
            The new value being set.
            - For ADD: The value being added
            - For UPDATE: The new value replacing the old one
            - For REMOVE: Not present
          example: INACTIVE
        oldValue:
          description: |
            The previous value (only present for UPDATE operations).
          example: ACTIVE
        changes:
          type: array
          description: Nested changes for complex objects
          items:
            $ref: '#/components/schemas/DiffChange'
    WebhookDelivery:
      type: object
      description: The top-level webhook delivery payload containing one or more events
      required:
        - sentAt
        - events
      properties:
        sentAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the webhook was sent from MVMNT
          example: '2025-01-15T14:30:00Z'
        events:
          type: array
          description: Array of webhook events (typically contains a single event)
          minItems: 1
          items:
            $ref: '#/components/schemas/WebhookPayload'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 access token obtained via client credentials flow