openapi: 3.1.0
info:
  title: Split commission types
  version: "1"
  description: Manage the commission types you use to split a payment between merchants.
tags:
  - name: Split commission types
    description: Manage the commission types used when splitting a payment between
      merchants.
paths:
  /api/v1/split-commission-types:
    servers:
      - url: https://sandbox-payments.datmanpay.com/rest
        description: Sandbox (base path from docs; verify)
      - url: https://payments.datmanpay.com/rest
        description: Production (base path inferred; verify)
    get:
      operationId: listSplitCommissionTypes
      summary: List split commission types
      description: "Returns the commission types you can use in a split: the `global`
        types every partner can use, and the `custom` types you created. Pass
        `type_id` to return a single type."
      tags:
        - Split commission types
      security:
        - ApiTokenAuth: []
      parameters:
        - name: type_id
          in: query
          required: false
          description: Return only this commission type.
          schema:
            type: integer
          examples:
            single:
              summary: One commission type
              value: 3
      responses:
        "200":
          description: The commission types.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SplitCommissionTypeList"
              examples:
                list:
                  summary: Global and custom types
                  value:
                    requestId: reqid_5b0d6f0e-4c1a-4b8e-9a51-3f3a2d1c7e90
                    outcome: success
                    data:
                      custom:
                        - id: 104
                          commission_type: Packaging_Fee
                          business_provider: OMNICART
                          created_at: 2026-09-01T10:15:00.000Z
                          updated_at: 2026-09-01T10:15:00.000Z
                      global:
                        - id: 1
                          commission_type: Food_Goods
                          business_provider: null
                          created_at: 2023-01-01T00:00:00.000Z
                          updated_at: 2023-01-01T00:00:00.000Z
                        - id: 3
                          commission_type: Delivery_Fee
                          business_provider: null
                          created_at: 2023-01-01T00:00:00.000Z
                          updated_at: 2023-01-01T00:00:00.000Z
        "401":
          $ref: "#/components/responses/SplitCommissionUnauthorized"
        "404":
          description: The commission type doesn't exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OutcomeErrorResponse"
              examples:
                notFound:
                  summary: Type not found
                  value:
                    requestId: reqid_5b0d6f0e-4c1a-4b8e-9a51-3f3a2d1c7e90
                    outcome: failed
                    message: Split commission type not found
        "500":
          $ref: "#/components/responses/SplitCommissionServerError"
    post:
      operationId: createSplitCommissionType
      summary: Create a split commission type
      description: Creates a custom commission type. Names must be unique
        (case-insensitive) among your types, including deleted ones.
      tags:
        - Split commission types
      security:
        - ApiTokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SplitCommissionTypeRequest"
            examples:
              packagingFee:
                summary: Create a packaging fee type
                value:
                  commission_type: Packaging_Fee
      responses:
        "201":
          description: The commission type was created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SplitCommissionTypeResult"
              examples:
                created:
                  summary: Type created
                  value:
                    requestId: reqid_5b0d6f0e-4c1a-4b8e-9a51-3f3a2d1c7e90
                    outcome: success
                    data:
                      id: 104
                      commission_type: Packaging_Fee
                      business_provider: OMNICART
                      created_at: 2026-09-01T10:15:00.000Z
        "400":
          description: The name is missing or already used.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OutcomeErrorResponse"
              examples:
                missing:
                  summary: Name missing
                  value:
                    requestId: reqid_5b0d6f0e-4c1a-4b8e-9a51-3f3a2d1c7e90
                    outcome: failed
                    message: commission_type is required and must be a non-empty string
                duplicate:
                  summary: Name already used
                  value:
                    requestId: reqid_5b0d6f0e-4c1a-4b8e-9a51-3f3a2d1c7e90
                    outcome: failed
                    message: "Duplicate commission_type found. A commission type with the same name
                      already exists with ID: 104"
        "401":
          $ref: "#/components/responses/SplitCommissionUnauthorized"
        "500":
          $ref: "#/components/responses/SplitCommissionServerError"
  /api/v1/split-commission-types/{type_id}:
    servers:
      - url: https://sandbox-payments.datmanpay.com/rest
        description: Sandbox (base path from docs; verify)
      - url: https://payments.datmanpay.com/rest
        description: Production (base path inferred; verify)
    parameters:
      - name: type_id
        in: path
        required: true
        description: The id of one of your custom commission types (above 100).
        schema:
          type: integer
          minimum: 101
        examples:
          custom:
            summary: A custom type
            value: 104
    put:
      operationId: updateSplitCommissionType
      summary: Rename a split commission type
      description: Changes the name of one of your custom commission types. Built-in
        types (id 100 or below) can't be changed.
      tags:
        - Split commission types
      security:
        - ApiTokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SplitCommissionTypeRequest"
            examples:
              rename:
                summary: Rename a type
                value:
                  commission_type: Packaging_Charge
      responses:
        "200":
          description: The commission type was renamed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SplitCommissionTypeResult"
              examples:
                updated:
                  summary: Type renamed
                  value:
                    requestId: reqid_5b0d6f0e-4c1a-4b8e-9a51-3f3a2d1c7e90
                    outcome: success
                    data:
                      id: 104
                      commission_type: Packaging_Charge
                      business_provider: OMNICART
                      created_at: 2026-09-01T10:15:00.000Z
                      updated_at: 2026-10-16T09:30:00.000Z
        "400":
          description: The name is missing or already used, or the type is built in.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OutcomeErrorResponse"
              examples:
                builtIn:
                  summary: Built-in type
                  value:
                    requestId: reqid_5b0d6f0e-4c1a-4b8e-9a51-3f3a2d1c7e90
                    outcome: failed
                    message: You do not have access to update split commission types with ID less
                      than or equal to 100
        "401":
          $ref: "#/components/responses/SplitCommissionUnauthorized"
        "404":
          description: The type doesn't exist or isn't yours.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OutcomeErrorResponse"
              examples:
                notFound:
                  summary: Type not found
                  value:
                    requestId: reqid_5b0d6f0e-4c1a-4b8e-9a51-3f3a2d1c7e90
                    outcome: failed
                    message: Split commission type not found or you do not have permission to update
                      it
        "500":
          $ref: "#/components/responses/SplitCommissionServerError"
    delete:
      operationId: deleteSplitCommissionType
      summary: Delete a split commission type
      description: Deletes one of your custom commission types. Built-in types (id 100
        or below) can't be deleted. A deleted type's name can't be reused.
      tags:
        - Split commission types
      security:
        - ApiTokenAuth: []
      responses:
        "200":
          description: The commission type was deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OutcomeMessageResponse"
              examples:
                deleted:
                  summary: Type deleted
                  value:
                    requestId: reqid_5b0d6f0e-4c1a-4b8e-9a51-3f3a2d1c7e90
                    outcome: success
                    message: Split commission type deleted successfully
        "400":
          description: The type is built in.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OutcomeErrorResponse"
              examples:
                builtIn:
                  summary: Built-in type
                  value:
                    requestId: reqid_5b0d6f0e-4c1a-4b8e-9a51-3f3a2d1c7e90
                    outcome: failed
                    message: You do not have access to delete split commission types with ID less
                      than or equal to 100
        "401":
          $ref: "#/components/responses/SplitCommissionUnauthorized"
        "404":
          description: The type doesn't exist, is already deleted or isn't yours.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OutcomeErrorResponse"
              examples:
                notFound:
                  summary: Type not found
                  value:
                    requestId: reqid_5b0d6f0e-4c1a-4b8e-9a51-3f3a2d1c7e90
                    outcome: failed
                    message: Split commission type not found or already deleted or you do not have
                      permission to delete it
        "500":
          $ref: "#/components/responses/SplitCommissionServerError"
components:
  schemas:
    SplitCommissionType:
      type: object
      properties:
        id:
          type: integer
        commission_type:
          type: string
        business_provider:
          type:
            - string
            - "null"
          description: Your partner name for custom types; `null` for global types.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    SplitCommissionTypeList:
      type: object
      properties:
        requestId:
          type: string
        outcome:
          type: string
          const: success
        data:
          type: object
          properties:
            custom:
              type: array
              items:
                $ref: "#/components/schemas/SplitCommissionType"
            global:
              type: array
              items:
                $ref: "#/components/schemas/SplitCommissionType"
    SplitCommissionTypeRequest:
      type: object
      required:
        - commission_type
      properties:
        commission_type:
          type: string
          minLength: 1
          description: The name of the commission type.
    SplitCommissionTypeResult:
      type: object
      properties:
        requestId:
          type: string
        outcome:
          type: string
          const: success
        data:
          $ref: "#/components/schemas/SplitCommissionType"
    OutcomeMessageResponse:
      type: object
      properties:
        requestId:
          type: string
        outcome:
          type: string
        message:
          type: string
    OutcomeErrorResponse:
      type: object
      required:
        - outcome
        - message
      properties:
        requestId:
          type: string
        outcome:
          type: string
          const: failed
        message:
          type: string
  responses:
    SplitCommissionUnauthorized:
      description: The `api_token` header is missing or invalid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OutcomeErrorResponse"
          examples:
            invalidToken:
              summary: Missing or invalid api_token
              value:
                requestId: reqid_5b0d6f0e-4c1a-4b8e-9a51-3f3a2d1c7e90
                outcome: failed
                message: Token is empty or Invalid token
    SplitCommissionServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OutcomeErrorResponse"
          examples:
            serverError:
              summary: Internal server error
              value:
                requestId: reqid_5b0d6f0e-4c1a-4b8e-9a51-3f3a2d1c7e90
                outcome: failed
                message: Internal server error
  securitySchemes:
    ApiTokenAuth:
      type: apiKey
      in: header
      name: api_token
      description: API token issued by Datman.