# Order Details – View for Return

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /v1/managers/store/orders/{orderId}/view-for-return:
    get:
      summary: Order Details – View for Return
      deprecated: false
      description: |
        Retrieves order details formatted specifically for return processing.

        **This endpoint:**

        - Returns only products that still have remaining returnable quantities
        - **Recalculates:**
            `Order totals`
            `Invoice amounts`
        - Reflects the maximum refundable amount based on remaining items

        **Use this endpoint before:**

        - Creating a reverse order
        - Calculating return totals
        - Performing partial returns

        :::info[]
        ## What This Endpoint Is Used For

        **Typical flow:**

        1. Call **view-for-return**
        2. Select products + quantities
        3. Call `/reverse-credit-note/totals`
        4. Create reverse order
        :::


        <Accordion title="🔑Scopes" defaultOpen>
            
        ` orders.read_write` - Orders Read & Write
         
        </Accordion>

        ## Behavior by Order Status
        **New / Not Delivered**
        - Returns all products
        - Quantities = original quantities

        **Partially Reversed**
        - Returns only remaining quantities
        - Totals recalculated

        **Fully Reversed**

        - `products = []`
        - `products_count = 0`
        - `order_total = 0`

        :::caution[]
        ## Business Logic

        **Remaining Quantity Calculation**

        `remaining_quantity = original_quantity − sum(previous_returns)`

        **Totals**

        - Recalculated based only on remaining items
        - Represents maximum refundable amount
        :::
      tags:
        - Default module/Apps/Merchant APIs/Reverse Orders
      parameters:
        - name: orderId
          in: path
          description: ''
          required: true
          example: '64086815'
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Authorization token is a unique key given to the third-party
            application (Partner) by Zid. It is used to authenticate the API
            requests made by the Partner application. The token verifies the
            partner's identity and ensures they have permission to access Zid's
            API but does not provide any specific user or store information. It
            should be included in the header of API requests when the partner
            application needs to access Zid's API.
          required: true
          example: '{{Autherization}}'
          schema:
            type: string
        - name: X-MANAGER-TOKEN
          in: header
          description: >-
            Unique manager token used to authorize requests at a manager level,
            specific to each partner.
          required: true
          example: '{{Access-Token}}'
          schema:
            type: string
        - name: Accept-Language
          in: header
          description: Language preference.
          required: false
          example: en
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Order details formatted for return processing. Includes only
                  products with remaining returnable quantities and recalculated
                  totals.
                properties:
                  status:
                    type: string
                    description: Response status indicator
                    examples:
                      - object
                  order:
                    $ref: '#/components/schemas/OrderForReturnSerializer'
                  message: &ref_0
                    description: Response message object
                    $ref: '#/components/schemas/ResponseEnvelopMessage'
                x-apidog-orders:
                  - status
                  - order
                  - message
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: Success
        '401':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Response returned when the request cannot be authenticated
                  because the required credentials are missing, invalid, or
                  expired.
                properties:
                  status:
                    type: string
                    description: Indicates the overall status of the API response.
                    examples:
                      - error
                  message:
                    type: object
                    description: >-
                      Contains structured details explaining why the request
                      could not be authenticated.
                    properties:
                      type:
                        type: string
                        description: Indicates the category of the response message.
                        examples:
                          - error
                      code:
                        type: string
                        description: >-
                          A machine-readable code identifying the authentication
                          error. Returns null when no specific code is
                          available.
                        examples:
                          - UNAUTHORIZED
                        nullable: true
                      name:
                        type: string
                        description: >-
                          A short, human-readable title describing the
                          authentication error. Returns null when no title is
                          available.
                        examples:
                          - Unauthorized
                        nullable: true
                      description:
                        type: string
                        description: >-
                          A human-readable explanation of why the request could
                          not be authenticated. Returns null when no detailed
                          explanation is available.
                        examples:
                          - >-
                            Authentication credentials are missing, invalid, or
                            expired.
                        nullable: true
                    required:
                      - type
                      - code
                      - name
                      - description
                    x-apidog-orders:
                      - type
                      - code
                      - name
                      - description
                    x-apidog-ignore-properties: []
                required:
                  - status
                  - message
                x-apidog-orders:
                  - status
                  - message
                examples:
                  - status: error
                    message:
                      type: error
                      code: UNAUTHORIZED
                      name: Unauthorized
                      description: >-
                        Authentication credentials are missing, invalid, or
                        expired.
                x-apidog-ignore-properties: []
              examples:
                '2':
                  summary: Example 1
                  value:
                    status: error
                    message:
                      type: error
                      code: ERROR_SESSION_MISSING
                      name: Sorry
                      description: Please login first.
                '3':
                  summary: Example 2
                  value:
                    status: error
                    message:
                      type: error
                      code: ERROR_SESSION_INVALID
                      name: Sorry
                      description: Login session expired. Please login again.
                '4':
                  summary: Example 3
                  value:
                    status: error
                    message:
                      type: error
                      code: ERROR_SESSION_INVALID
                      name: Sorry
                      description: Invalid authentication
          headers: {}
          x-apidog-name: Unauthorized
        '403':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: object
                    properties:
                      type:
                        type: string
                      code:
                        type: string
                      name:
                        type: string
                      description:
                        type: string
                    required:
                      - type
                      - code
                      - name
                      - description
                    x-apidog-orders:
                      - type
                      - code
                      - name
                      - description
                    x-apidog-ignore-properties: []
                required:
                  - status
                  - message
                x-apidog-orders:
                  - status
                  - message
                x-apidog-ignore-properties: []
              example:
                status: error
                message:
                  type: error
                  code: ERROR_POPUP_OK
                  name: Sorry
                  description: Permission Denied
          headers: {}
          x-apidog-name: Forbidden
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Status of the error.
                  message: *ref_0
                required:
                  - status
                  - message
                x-apidog-orders:
                  - status
                  - message
                x-apidog-ignore-properties: []
              example:
                status: error
                message:
                  type: error
                  code: MSG_HIDDEN
                  name: Error
                  description: Internal Server Error
          headers: {}
          x-apidog-name: Internal Server error
      security: []
      x-apidog-folder: Default module/Apps/Merchant APIs/Reverse Orders
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/613905/apis/api-27774520-run
components:
  schemas:
    ResponseEnvelopMessage:
      type: object
      properties:
        type:
          type: string
          description: Type of response message returned by the API.
          examples:
            - success
        code:
          type: string
          description: Response code returned by the API, if available.
          examples:
            - MSG_POPUP_OK
          nullable: true
        name:
          type: string
          description: Name or title of the response message, if available.
          examples:
            - Coupons
          nullable: true
        description:
          type: string
          description: Detailed description of the response message, if available.
          examples:
            - Coupons created successfully
          nullable: true
      required:
        - type
        - code
        - name
        - description
      description: Additional response metadata.
      x-apidog-orders:
        - type
        - code
        - name
        - description
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    OrderForReturnSerializer:
      type: object
      description: Order information filtered for return operations
      properties:
        id:
          type: integer
          description: Unique order identifier
          examples:
            - 39017136
        invoice_number:
          type: integer
          description: Invoice number
          examples:
            - 39017136
        code:
          type: string
          description: Order reference code
          examples:
            - XAiG6yjJCW
        store_id:
          type: integer
          description: Store identifier
          examples:
            - 1
        order_status:
          type: object
          description: Current order status
          properties:
            name:
              type: string
              examples:
                - Ready
            code:
              type: string
              examples:
                - ready
          x-apidog-orders:
            - name
            - code
          x-apidog-ignore-properties: []
        payment_status:
          type: string
          description: Payment status of the order
          examples:
            - paid
        currency_code:
          type: string
          description: Order currency
          examples:
            - SAR
        order_total:
          type: number
          description: Recalculated total based on remaining returnable products
          examples:
            - 346
        order_total_string:
          type: string
          description: Formatted order total
          examples:
            - 346.00 SAR
        products_count:
          type: integer
          description: Number of products still available for return
          examples:
            - 3
        products_sum_total_string:
          type: string
          description: Formatted subtotal of remaining products
          examples:
            - 300.87 SAR
        products:
          type: array
          description: Products with remaining returnable quantities
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: Order product UUID
                examples:
                  - a1e5eb8f-12a7-4a43-97af-f98e0d9af17b
              order_product_id:
                type: integer
                description: Order product ID used in reverse operations
                examples:
                  - 60564
              name:
                type: string
                description: Product name
                examples:
                  - Test file
              sku:
                type: string
                description: Product SKU
                examples:
                  - Z.1.17314985477182937
              quantity:
                type: integer
                description: >-
                  Remaining quantity available for return (original quantity
                  minus previously returned quantity)
                examples:
                  - 2
              price:
                type: number
                description: Unit price including tax
                examples:
                  - 122.99
              price_string:
                type: string
                description: Formatted unit price
                examples:
                  - 123.00 SAR
              tax_percentage:
                type: number
                description: Tax percentage applied
                examples:
                  - 0.15
              total:
                type: number
                description: Total amount for this product line (quantity × price)
                examples:
                  - 245.99
              total_string:
                type: string
                description: Formatted total amount
                examples:
                  - 246.00 SAR
            x-apidog-orders:
              - id
              - order_product_id
              - name
              - sku
              - quantity
              - price
              - price_string
              - tax_percentage
              - total
              - total_string
            x-apidog-ignore-properties: []
        payment:
          type: object
          description: Payment details with recalculated invoice totals
          properties:
            invoice:
              type: array
              description: Invoice summary based on remaining returnable items
              items:
                type: object
                properties:
                  code:
                    type: string
                    description: Invoice line identifier
                    examples:
                      - sub_totals
                  value:
                    type: number
                    description: Numeric value
                    examples:
                      - 300.87
                  value_string:
                    type: string
                    description: Formatted value
                    examples:
                      - 300.87 SAR
                  title:
                    type: string
                    description: Display title
                    examples:
                      - Subtotal
                x-apidog-orders:
                  - code
                  - value
                  - value_string
                  - title
                x-apidog-ignore-properties: []
          x-apidog-orders:
            - invoice
          x-apidog-ignore-properties: []
      x-apidog-orders:
        - id
        - invoice_number
        - code
        - store_id
        - order_status
        - payment_status
        - currency_code
        - order_total
        - order_total_string
        - products_count
        - products_sum_total_string
        - products
        - payment
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
  securitySchemes: {}
servers:
  - url: https://api.zid.sa/
    description: Prod Env
security: []

```