openapi: 3.1.0
info:
  title: Logitrail Service Catalog
  version: (dev)
  description: Read-only catalog of LogitrailServices (delivery/carrier products)
    available to the calling merchant.
servers:
  - url: https://api-1.test.logitrail.com
    description: Test / Development Server
  - url: https://api-1.logitrail.com
    description: Production Server
paths:
  /v1/logitrail-service-catalog/services:
    get:
      summary: List LogitrailServices available to the merchant
      description: Returns enabled services accessible to the calling merchant.
        Filters by `enabled`, `onlyForMerchants` allow-list, and
        `notForMerchants` deny-list.
      operationId: ListLogitrailServices
      security:
        - idp: []
      parameters:
        - in: header
          name: x-logitrail-merchant-id
          schema:
            type: string
            minLength: 1
            description: Logitrail's Merchant ID.
          required: true
          description: Logitrail's Merchant ID.
      responses:
        "200":
          description: List of services
          content:
            application/json:
              schema:
                type: object
                properties:
                  services:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          pattern: ^[0-9a-f]{24}$
                        code:
                          type: string
                          description: Canonical code (e.g. `POSTIPAKETTI`). Unique.
                        name:
                          type: string
                          description: Human-readable display name.
                        carrier:
                          description: Carrier code (e.g. `posti`). Surfaced to merchants so UIs can
                            render carrier-specific flows.
                          type: string
                        requirePickupPoint:
                          description: When true, callers MUST attach a pickup-point selector when using
                            this service.
                          type: boolean
                        applicableScopes:
                          description: Host record types where this service may be attached. When unset or
                            empty, attachment is rejected for every host. The
                            catalog admin API is the only place where this list
                            is set.
                          type: array
                          items:
                            type: string
                            enum:
                              - order
                              - order_item
                              - inbound_shipment
                              - inbound_shipment_item
                              - customer_return
                              - customer_return_item
                        type:
                          description: Canonical service-type taxonomy. `delivery` = delivery-method
                            service backing an order. `service` = value-added
                            work performed during fulfilment. `material` =
                            stocked physical consumable used at pack-out. Null
                            on legacy rows that pre-date the field.
                          anyOf:
                            - type: string
                              enum:
                                - delivery
                                - service
                                - material
                            - type: "null"
                      required:
                        - id
                        - code
                        - name
                      additionalProperties: false
                required:
                  - services
                additionalProperties: false
        "400":
          description: Validation error, see response body for details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: A brief, human readable error message.
                  error_code:
                    type: string
                    const: VALIDATION_ERROR
                    description: Reason of the error.
                  validation_errors:
                    type: array
                    items: {}
                    description: An array of validation error details.
                required:
                  - message
                  - error_code
                  - validation_errors
                additionalProperties: false
  /v1/logitrail-service-catalog/services/{code}:
    get:
      summary: Get a LogitrailService by canonical code
      description: Returns one service by canonical code (e.g. `POSTIPAKETTI`). 404
        when not found or not allowed for the merchant — the endpoint
        deliberately does not differentiate the two cases.
      operationId: GetLogitrailServiceByCode
      security:
        - idp: []
      parameters:
        - in: header
          name: x-logitrail-merchant-id
          schema:
            type: string
            minLength: 1
            description: Logitrail's Merchant ID.
          required: true
          description: Logitrail's Merchant ID.
      responses:
        "200":
          description: Service details
          content:
            application/json:
              schema:
                type: object
                properties:
                  service:
                    type: object
                    properties:
                      id:
                        type: string
                        pattern: ^[0-9a-f]{24}$
                      code:
                        type: string
                        description: Canonical code (e.g. `POSTIPAKETTI`). Unique.
                      name:
                        type: string
                        description: Human-readable display name.
                      carrier:
                        description: Carrier code (e.g. `posti`). Surfaced to merchants so UIs can
                          render carrier-specific flows.
                        type: string
                      requirePickupPoint:
                        description: When true, callers MUST attach a pickup-point selector when using
                          this service.
                        type: boolean
                      applicableScopes:
                        description: Host record types where this service may be attached. When unset or
                          empty, attachment is rejected for every host. The
                          catalog admin API is the only place where this list is
                          set.
                        type: array
                        items:
                          type: string
                          enum:
                            - order
                            - order_item
                            - inbound_shipment
                            - inbound_shipment_item
                            - customer_return
                            - customer_return_item
                      type:
                        description: Canonical service-type taxonomy. `delivery` = delivery-method
                          service backing an order. `service` = value-added work
                          performed during fulfilment. `material` = stocked
                          physical consumable used at pack-out. Null on legacy
                          rows that pre-date the field.
                        anyOf:
                          - type: string
                            enum:
                              - delivery
                              - service
                              - material
                          - type: "null"
                    required:
                      - id
                      - code
                      - name
                    additionalProperties: false
                required:
                  - service
                additionalProperties: false
        "400":
          description: Validation error, see response body for details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: A brief, human readable error message.
                  error_code:
                    type: string
                    const: VALIDATION_ERROR
                    description: Reason of the error.
                  validation_errors:
                    type: array
                    items: {}
                    description: An array of validation error details.
                required:
                  - message
                  - error_code
                  - validation_errors
                additionalProperties: false
        "404":
          description: Service not found or not allowed for merchant
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: A brief, human readable error message.
                  error_code:
                    type: string
                    const: VALIDATION_ERROR
                    description: Reason of the error.
                  validation_errors:
                    type: array
                    items: {}
                    description: An array of validation error details.
                required:
                  - message
                  - error_code
                  - validation_errors
                additionalProperties: false
components:
  securitySchemes:
    idp:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://idp.logitrail.com/realms/logitrail/protocol/openid-connect/token
          scopes: {}