Phasio Manufacturer Customer Organisation Controller API

openapi: 3.2.0
info:
  title: Phasio Manufacturer Customer Organisation Controller API
  description: This is the API documentation for the Phasio application.
  version: '1.0'
servers:
- url: https://m-api.eu.phas.io
  description: Generated server url
security:
- Phasio API Bearer Token: []
tags:
- name: Manufacturer Customer Organisation Controller
  description: API for managing customer organizations
paths:
  /api/manufacturer/v1/organisation/{organisationId}/metadata/key/{metadataKey}:
    put:
      tags:
      - Manufacturer Customer Organisation Controller
      summary: Upsert customer organisation metadata by key
      description: Sets the value for a metadata key on a customer organisation, creating the entry if it does not already exist. Intended for external systems that track their own key but do not know the corresponding internal metadata ID.
      operationId: upsertMetadataByKey
      parameters:
      - name: organisationId
        in: path
        description: ID of the organisation
        required: true
        schema:
          type: integer
          format: int64
        example: 1
      - name: metadataKey
        in: path
        description: Metadata key to set
        required: true
        schema:
          type: string
        example: shopifyCustomerId
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetCustomerOrganisationMetadataValueDto'
        required: true
      responses:
        '200':
          description: Metadata upserted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerOrganisationMetadataDto'
        '404':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/organisation/{organisationId}/metadata:
    post:
      tags:
      - Manufacturer Customer Organisation Controller
      summary: Add metadata to a customer organisation
      description: Adds a new metadata entry (key/value pair) to a customer organisation. Keys must be unique per organisation.
      operationId: addMetadata
      parameters:
      - name: organisationId
        in: path
        description: ID of the organisation to add metadata to
        required: true
        schema:
          type: integer
          format: int64
        example: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerOrganisationMetadataDto'
        required: true
      responses:
        '200':
          description: Metadata added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerOrganisationMetadataDto'
        '404':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Metadata key already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/organisation/{organisationId}:
    get:
      tags:
      - Manufacturer Customer Organisation Controller
      summary: Get a customer organization by ID
      description: Retrieves details of a specific customer organization
      operationId: get_3
      parameters:
      - name: organisationId
        in: path
        description: ID of the organization to retrieve
        required: true
        schema:
          type: integer
          format: int64
        example: 1
      responses:
        '200':
          description: Organization retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerOrganisationDto'
        '401':
          description: Unauthorized - missing operator context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    delete:
      tags:
      - Manufacturer Customer Organisation Controller
      summary: Delete a customer organization
      description: Soft deletes a customer organization and hard deletes all contained customers
      operationId: deleteCustomerOrganisation
      parameters:
      - name: organisationId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Organization deleted successfully
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CustomerOrganisationDto'
        '404':
          description: Organization not found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CustomerOrganisationDto'
    patch:
      tags:
      - Manufacturer Customer Organisation Controller
      summary: Update a customer organization
      description: Updates details of an existing customer organization
      operationId: update
      parameters:
      - name: organisationId
        in: path
        description: ID of the organization to update
        required: true
        schema:
          type: integer
          format: int64
        example: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganisationUpdateDto'
        required: true
      responses:
        '200':
          description: Organization updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerOrganisationDto'
        '400':
          description: Invalid organization payload or payment term ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Organization or payment term not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Organization name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/organisation/{organisationId}/metadata/{metadataId}:
    delete:
      tags:
      - Manufacturer Customer Organisation Controller
      summary: Delete customer organisation metadata
      description: Removes a metadata entry from a customer organisation.
      operationId: deleteMetadata
      parameters:
      - name: organisationId
        in: path
        description: ID of the organisation
        required: true
        schema:
          type: integer
          format: int64
        example: 1
      - name: metadataId
        in: path
        description: ID of the metadata entry to delete
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Metadata deleted successfully
        '404':
          description: Metadata not found for the given organisation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    patch:
      tags:
      - Manufacturer Customer Organisation Controller
      summary: Update customer organisation metadata
      description: Partially updates an existing metadata entry on a customer organisation. Only supplied fields are modified.
      operationId: updateMetadata
      parameters:
      - name: organisationId
        in: path
        description: ID of the organisation
        required: true
        schema:
          type: integer
          format: int64
        example: 1
      - name: metadataId
        in: path
        description: ID of the metadata entry to update
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerOrganisationMetadataDto'
        required: true
      responses:
        '200':
          description: Metadata updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerOrganisationMetadataDto'
        '404':
          description: Metadata not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Metadata key already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/organisation:
    get:
      tags:
      - Manufacturer Customer Organisation Controller
      summary: Get customer organisation summaries
      description: Retrieves a list of customer organisation summaries
      operationId: getCustomerOrganisationSummaries
      responses:
        '200':
          description: Customer organisations retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomerOrganisationSummaryDto'
        '401':
          description: Unauthorized - missing operator context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/organisation/paginated:
    get:
      tags:
      - Manufacturer Customer Organisation Controller
      summary: Get customer organisations with filtering
      description: Retrieves a paginated list of customer organisations with optional filtering and search using RSQL
      operationId: getCustomerOrganisationsPaginated
      parameters:
      - name: filter
        in: query
        description: filter specification
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: Zero-based page index (0..N)
        required: false
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: size
        in: query
        description: The size of the page to be returned
        required: false
        schema:
          type: integer
          default: 30
          minimum: 1
      - name: sort
        in: query
        description: 'Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.'
        required: false
        schema:
          type: array
          default:
          - updateDt,DESC
          items:
            type: string
      - name: search
        in: query
        description: Optional search term
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Customer organisations retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paginated'
        '400':
          description: Invalid filter specification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized - missing operator context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/organisation/customer/{customerId}:
    get:
      tags:
      - Manufacturer Customer Organisation Controller
      summary: Get organization by customer ID
      description: Retrieves the organization associated with a specific customer
      operationId: getByCustomer
      parameters:
      - name: customerId
        in: path
        description: ID of the customer to get organization for
        required: true
        schema:
          type: integer
          format: int64
        example: 1
      responses:
        '200':
          description: Organization retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerOrganisationDto'
        '401':
          description: Unauthorized - missing operator context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    OrganisationUpdateDto:
      type: object
      properties:
        name:
          type: string
        canAccessDashboard:
          type: boolean
        taxExempt:
          type: boolean
        language:
          type: string
        accountingSystemId:
          type: string
        isApproved:
          type: boolean
        customerType:
          type: string
          enum:
          - PRO_FORMA
          - ACCOUNT
          - INTERNAL
        paymentTermId:
          type: string
          format: uuid
        clearPaymentTerm:
          type: boolean
        incoterm:
          type: string
          enum:
          - EXW
          - FCA
          - CPT
          - CIP
          - DAP
          - DPU
          - DDP
          - FAS
          - FOB
          - CFR
          - CIF
        clearIncoterm:
          type: boolean
        companyName:
          type: string
          description: Name synced to the accounting system; may repeat across organisations
      required:
      - clearIncoterm
      - clearPaymentTerm
    CustomerDto:
      type: object
      properties:
        email:
          type: string
        customerId:
          type: integer
          format: int64
        organisationId:
          type: integer
          format: int64
        organisationName:
          type: string
        isApproved:
          type: boolean
        firstName:
          type: string
        lastName:
          type: string
        phoneNumber:
          type: string
        notificationPreference:
          type: string
        discountId:
          type: integer
          format: int64
        discountPercentage:
          type: number
        language:
          type: string
      required:
      - customerId
      - firstName
      - isApproved
      - lastName
      - notificationPreference
      - organisationId
      - phoneNumber
    UpdateCustomerOrganisationMetadataDto:
      type: object
      properties:
        metadataKey:
          type: string
        value:
          type: string
    CreateCustomerOrganisationMetadataDto:
      type: object
      properties:
        metadataKey:
          type: string
        value:
          type: string
      required:
      - metadataKey
      - value
    Paginated:
      type: object
      properties:
        content:
          type: array
          items: {}
        totalElements:
          type: integer
        totalPages:
          type: integer
        pageNumber:
          type: integer
        pageSize:
          type: integer
        isEmpty:
          type: boolean
        isFirst:
          type: boolean
        isLast:
          type: boolean
      required:
      - content
      - isEmpty
      - isFirst
      - isLast
      - pageNumber
      - pageSize
      - totalElements
      - totalPages
    OperatorAddressDto:
      allOf:
      - $ref: '#/components/schemas/AddressDto'
      required:
      - addressId
      - addressType
      - city
      - company
      - country
      - countryAlpha2Code
      - countryAlpha3Code
      - email
      - isBillingAddress
      - isDeleted
      - isShippingAddress
      - name
      - phone
      - residential
      - street1
      - street2
      - zip
    PaymentTermDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        accountingSystemTermId:
          type: string
      required:
      - id
      - name
    CustomerOrganisationAddressDto:
      allOf:
      - $ref: '#/components/schemas/AddressDto'
      required:
      - addressId
      - addressType
      - city
      - company
      - country
      - countryAlpha2Code
      - countryAlpha3Code
      - email
      - isBillingAddress
      - isDeleted
      - isShippingAddress
      - name
      - phone
      - residential
      - street1
      - street2
      - zip
    CustomerOrganisationDto:
      type: object
      properties:
        id:
          type: integer
          format: int64
        hasCustomPricing:
          type: boolean
        name:
          type: string
        companyName:
          type: string
        taxExempt:
          type: boolean
        isApproved:
          type: boolean
        customerType:
          type: string
        paymentTerm:
          $ref: '#/components/schemas/PaymentTermDto'
        incoterm:
          type: string
          enum:
          - EXW
          - FCA
          - CPT
          - CIP
          - DAP
          - DPU
          - DDP
          - FAS
          - FOB
          - CFR
          - CIF
        createdAt:
          type: string
          format: date-time
        updateDt:
          type: string
          format: date-time
        customers:
          type: array
          items:
            $ref: '#/components/schemas/CustomerDto'
        addresses:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/CustomerOrganisationAddressDto'
            - $ref: '#/components/schemas/OperatorAddressDto'
        encryptionKeyId:
          type: string
        firstTouchSource:
          type: string
        language:
          type: string
        accountingSystemId:
          type: string
        deleted:
          type: boolean
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/CustomerOrganisationMetadataDto'
      required:
      - addresses
      - createdAt
      - customerType
      - customers
      - deleted
      - hasCustomPricing
      - id
      - isApproved
      - metadata
      - taxExempt
      - updateDt
    CustomerOrganisationSummaryDto:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        taxExempt:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updateDt:
          type: string
          format: date-time
        firstTouchSource:
          type: string
        language:
          type: string
        isApproved:
          type: boolean
        accountingSystemId:
          type: string
      required:
      - createdAt
      - taxExempt
      - updateDt
    SetCustomerOrganisationMetadataValueDto:
      type: object
      properties:
        value:
          type: string
      required:
      - value
    ApiError:
      type: object
      additionalProperties: true
      description: Stable error contract. `error` is a SCREAMING_SNAKE code that clients match on; `message` is a human-readable sentence. Some errors add extra string fields (for example organisationId).
      properties:
        error:
          type: string
          example: ORDER_NOT_FOUND
        message:
          type: string
          example: Order not found
      required:
      - error
      - message
    CustomerOrganisationMetadataDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        metadataKey:
          type: string
        value:
          type: string
      required:
      - id
      - metadataKey
      - value
    AddressDto:
      type: object
      discriminator:
        propertyName: addressType
        mapping:
          OPERATOR: '#/components/schemas/OperatorAddressDto'
          CUSTOMER_ORGANISATION: '#/components/schemas/CustomerOrganisationAddressDto'
      properties:
        addressId:
          type: integer
          format: int64
        isBillingAddress:
          type: boolean
        isShippingAddress:
          type: boolean
        street1:
          type: string
        street2:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        countryAlpha2Code:
          type: string
        countryAlpha3Code:
          type: string
        jurisdictionIsoCode:
          type: string
        zip:
          type: string
        name:
          type: string
        company:
          type: string
        phone:
          type: string
        email:
          type: string
        residential:
          type: boolean
        addressType:
          type: string
        isDeleted:
          type: boolean
        taxId:
          type: string
      required:
      - addressId
      - addressType
      - city
      - company
      - country
      - countryAlpha2Code
      - countryAlpha3Code
      - email
      - isBillingAddress
      - isDeleted
      - isShippingAddress
      - name
      - phone
      - residential
      - street1
      - street2
      - zip
  securitySchemes:
    Phasio_API_Bearer_Token:
      type: http
      name: Authorization
      in: header
      scheme: bearer
      bearerFormat: JWT