return-request-create:
  post:
    tags:
    - Client Order
    summary: Create a return request for a completed order
    x-figma:
      mobile: https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9442-3771&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1
      mobileNodeId: 9442:3771
      web: https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-88314&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038
      webNodeId: 10245:88314
    description: '<div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9442-3771&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      target="_blank" rel="noopener">Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-88314&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      target="_blank" rel="noopener">Web</a></div>


      Client creates a return request for an owned completed/finished and paid order.

      All fields are supplied via **body** (`orderId`, `reason`, optional `attachments`).
      Prefer `multipart/form-data` when uploading attachments.

      Status flow starts at `pending_review`.

      Attachments are optional images (JPEG/PNG/WebP), max 10 files, 5MB each.

      One return request is allowed permanently per original order.
      If a previous return was rejected, create returns `returnAlreadyRejected`.

      Creation is allowed only during the dashboard-configured
      `returnRequestAllowedDays` window. The server counts exact 24-hour days from
      `Order.completedAt` (with `receivedAt`, then `updatedAt`, as legacy fallbacks)
      and returns `returnWindowExpired` after the deadline.

      Wallet refund does **not** happen on create — only on provider accept for wallet-paid orders.

      List/details for returns use the shared endpoints:

      - `GET /orders?type=return`

      - `GET /order?type=return&id=...`

      '
    operationId: createReturnRequest
    security:
    - SecretKeyAuth: []
      ClientBearerAuth: []
    parameters:
    - $ref: ../openapi.yaml#/components/parameters/LangHeader
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required:
            - orderId
            - reason
            properties:
              orderId:
                type: string
                pattern: ^[a-fA-F0-9]{24}$
                description: Original completed order ObjectId owned by the authenticated client.
                example: "665f1c2a9b4e1d0012ab34d0"
              reason:
                type: string
                minLength: 3
                maxLength: 1000
                example: المنتج تالف
              attachments:
                type: string
                format: binary
                description: 'Optional evidence image (JPEG/PNG/WebP, max 5MB).

                  Leave empty if unused. Repeat the same field for up to 10 files.

                  '
          encoding:
            attachments:
              contentType: image/jpeg, image/png, image/webp
        application/json:
          schema:
            type: object
            required:
            - orderId
            - reason
            additionalProperties: false
            properties:
              orderId:
                type: string
                pattern: ^[a-fA-F0-9]{24}$
                description: Original completed order ObjectId owned by the authenticated client.
                example: "665f1c2a9b4e1d0012ab34d0"
              reason:
                type: string
                minLength: 3
                maxLength: 1000
                example: المنتج تالف
            description: JSON body without attachments. Use multipart when uploading files.
    responses:
      '200':
        description: Return request created.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/OrderActionResponse
            example:
              key: success
              message: تم إنشاء طلب الإرجاع بنجاح
              status: 200
      '400':
        description: Validation or business-rule failure.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/ErrorResponse
            examples:
              notCompleted:
                value:
                  key: fail
                  message: يمكن إنشاء طلب الإرجاع فقط بعد اكتمال الطلب
                  status: 400
              duplicate:
                value:
                  key: fail
                  message: يوجد طلب إرجاع لهذا الطلب مسبقاً
                  status: 400
              returnWindowExpired:
                value:
                  key: fail
                  message: انتهت مدة السماح بإرجاع هذا الطلب
                  status: 400
      '419':
        description: Missing/invalid client token.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/ErrorResponse
            example:
              key: unauthorized
              message: غير مسموح لك بتنفيذ هذا الإجراء
              status: 419
      '500':
        description: Server error.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/ErrorResponse
            example:
              key: exception
              message: حدث خطأ، برجاء التواصل مع الدعم
              status: 500
return-request-delivered:
  patch:
    tags:
    - Client Order
    summary: Mark returned product as handed/delivered
    x-figma:
      mobile: https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9449-5037&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1
      mobileNodeId: 9449:5037
      web: https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-93482&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038
      webNodeId: 10245:93482
    description: '<div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9449-5037&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      target="_blank" rel="noopener">Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-93482&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      target="_blank" rel="noopener">Web</a></div>


      Allowed only when status is `accepted`.

      Identifier via query `id` (return request ObjectId).

      This does **not** complete the return request.

      Provider must still confirm receipt.

      '
    operationId: deliverReturnRequest
    security:
    - SecretKeyAuth: []
      ClientBearerAuth: []
    parameters:
    - $ref: ../openapi.yaml#/components/parameters/LangHeader
    - name: id
      in: query
      required: true
      schema:
        type: string
        pattern: ^[a-fA-F0-9]{24}$
      description: Return request ObjectId owned by the authenticated client.
    responses:
      '200':
        description: Client delivery marked.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/OrderActionResponse
            example:
              key: success
              message: تم تأكيد تسليم المنتج بنجاح
              status: 200
      '400':
        description: Invalid state or ownership.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/ErrorResponse
            examples:
              notAccepted:
                value:
                  key: fail
                  message: لا يمكن تأكيد التسليم إلا بعد قبول طلب الإرجاع
                  status: 400
              alreadyDelivered:
                value:
                  key: fail
                  message: قام العميل بتسليم المنتج بالفعل
                  status: 400
      '419':
        description: Missing/invalid client token.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/ErrorResponse
            example:
              key: unauthorized
              message: غير مسموح لك بتنفيذ هذا الإجراء
              status: 419
      '500':
        description: Server error.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/ErrorResponse
            example:
              key: exception
              message: حدث خطأ، برجاء التواصل مع الدعم
              status: 500
return-request-accept:
  patch:
    tags:
    - Provider Order
    summary: Accept a return request
    x-figma:
      mobile: https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25429&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1
      mobileNodeId: 9967:25429
      web: https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87591&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038
      webNodeId: 10760:87591
    description: '<div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25429&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      target="_blank" rel="noopener">Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87591&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      target="_blank" rel="noopener">Web</a></div>


      Allowed only when status is `pending_review`.

      Identifier via query `id` (return request ObjectId).


      Wallet-paid orders:

      - refund `order.total` to client wallet exactly once

      - create one BalanceHistory charge linked to the return request

      - set refundStatus=`refunded`


      Online-paid orders:

      - do **not** invent a gateway refund

      - set refundStatus=`pending_manual`


      Acceptance alone does **not** complete the return.

      Client then sees `canClientMarkDelivered=true`.

      '
    operationId: acceptReturnRequest
    security:
    - SecretKeyAuth: []
      ProviderBearerAuth: []
    parameters:
    - $ref: ../openapi.yaml#/components/parameters/LangHeader
    - name: id
      in: query
      required: true
      schema:
        type: string
        pattern: ^[a-fA-F0-9]{24}$
      description: Return request ObjectId owned by the authenticated provider.
    responses:
      '200':
        description: Return request accepted.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/OrderActionResponse
            examples:
              walletRefunded:
                summary: Wallet-paid order — refund applied immediately
                value:
                  key: success
                  message: تم قبول طلب الإرجاع بنجاح
                  status: 200
              onlinePendingManual:
                summary: Online-paid order — manual refund pending
                value:
                  key: success
                  message: تم قبول طلب الإرجاع بنجاح
                  status: 200
      '400':
        description: Invalid state or ownership.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/ErrorResponse
            example:
              key: fail
              message: لا يمكن اتخاذ هذا الإجراء إلا على طلب قيد المراجعة
              status: 400
      '419':
        description: Missing/invalid provider token.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/ErrorResponse
            example:
              key: unauthorized
              message: غير مسموح لك بتنفيذ هذا الإجراء
              status: 419
      '500':
        description: Server error.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/ErrorResponse
            example:
              key: exception
              message: حدث خطأ، برجاء التواصل مع الدعم
              status: 500
return-request-reject:
  patch:
    tags:
    - Provider Order
    summary: Reject a return request
    x-figma:
      mobile: https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25429&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1
      mobileNodeId: 9967:25429
      web: https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87591&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038
      webNodeId: 10760:87591
    description: '<div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25429&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      target="_blank" rel="noopener">Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87591&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      target="_blank" rel="noopener">Web</a></div>


      Allowed only when status is `pending_review`.

      Body fields: `id` (return request ObjectId) + `reason` (catalogue Reason ObjectId),
      same pattern as PATCH /order/reject (`orderId` + `reason`).

      No refund is issued.

      '
    operationId: rejectReturnRequest
    security:
    - SecretKeyAuth: []
      ProviderBearerAuth: []
    parameters:
    - $ref: ../openapi.yaml#/components/parameters/LangHeader
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required:
            - id
            - reason
            properties:
              id:
                type: string
                pattern: ^[a-fA-F0-9]{24}$
                description: Return request ObjectId owned by the authenticated provider.
                example: "665f1c2a9b4e1d0012ab34e1"
              reason:
                type: string
                pattern: ^[a-fA-F0-9]{24}$
                description: Reason ObjectId from the shared reasons catalogue.
                example: "665f1c2a9b4e1d0012ab34aa"
        application/json:
          schema:
            type: object
            required:
            - id
            - reason
            additionalProperties: false
            properties:
              id:
                type: string
                pattern: ^[a-fA-F0-9]{24}$
                description: Return request ObjectId owned by the authenticated provider.
                example: "665f1c2a9b4e1d0012ab34e1"
              reason:
                type: string
                pattern: ^[a-fA-F0-9]{24}$
                description: Reason ObjectId from the shared reasons catalogue.
                example: "665f1c2a9b4e1d0012ab34aa"
    responses:
      '200':
        description: Return request rejected.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/OrderActionResponse
            example:
              key: success
              message: تم رفض طلب الإرجاع بنجاح
              status: 200
      '400':
        description: Validation or invalid state.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/ErrorResponse
            example:
              key: fail
              message: السبب غير موجود
              status: 400
      '419':
        description: Missing/invalid provider token.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/ErrorResponse
            example:
              key: unauthorized
              message: غير مسموح لك بتنفيذ هذا الإجراء
              status: 419
      '500':
        description: Server error.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/ErrorResponse
            example:
              key: exception
              message: حدث خطأ، برجاء التواصل مع الدعم
              status: 500
return-request-received:
  patch:
    tags:
    - Provider Order
    summary: Mark returned product as received
    x-figma:
      mobile: https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25473&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1
      mobileNodeId: 9967:25473
      web: https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87638&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038
      webNodeId: 10760:87638
    description: '<div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25473&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      target="_blank" rel="noopener">Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87638&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      target="_blank" rel="noopener">Web</a></div>


      Allowed only when status is `client_delivered`.

      Identifier via query `id` (return request ObjectId).

      This is the **final** step and sets status=`completed`.

      '
    operationId: markReturnReceived
    security:
    - SecretKeyAuth: []
      ProviderBearerAuth: []
    parameters:
    - $ref: ../openapi.yaml#/components/parameters/LangHeader
    - name: id
      in: query
      required: true
      schema:
        type: string
        pattern: ^[a-fA-F0-9]{24}$
      description: Return request ObjectId owned by the authenticated provider.
    responses:
      '200':
        description: Return request completed.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/OrderActionResponse
            example:
              key: success
              message: تم تأكيد استلام المنتج بنجاح
              status: 200
      '400':
        description: Invalid state or ownership.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/ErrorResponse
            examples:
              notClientDelivered:
                value:
                  key: fail
                  message: لا يمكن تأكيد الاستلام إلا بعد تسليم العميل للمنتج
                  status: 400
              alreadyReceived:
                value:
                  key: fail
                  message: تم تأكيد الاستلام بالفعل
                  status: 400
      '419':
        description: Missing/invalid provider token.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/ErrorResponse
            example:
              key: unauthorized
              message: غير مسموح لك بتنفيذ هذا الإجراء
              status: 419
      '500':
        description: Server error.
        content:
          application/json:
            schema:
              $ref: ../openapi.yaml#/components/schemas/ErrorResponse
            example:
              key: exception
              message: حدث خطأ، برجاء التواصل مع الدعم
              status: 500
