> ## Documentation Index
> Fetch the complete documentation index at: https://twigz.arqqin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Returns

> Create and manage return requests for delivered orders

## Overview

Customer Returns API lets customers check eligibility, initiate returns, view details, list their returns with pagination, and cancel pending requests.

**Location:** `convex/customers/returns.ts`

## Check Return Eligibility

Verify if an order is eligible for return and which items can be returned.

<ParamField path="orderId" type="Id<'orders'>" required>
  Order ID to check
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const eligibility = await convex.query(api.customers.returns.checkReturnEligibility, {
    orderId: "o123456789"
  });
  ```

  ```javascript JavaScript theme={null}
  const eligibility = await convex.query("customers.returns.checkReturnEligibility", {
    orderId: "o123456789"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "isEligible": true,
    "returnableItems": [
      {
        "productId": "p123",
        "productName": "Pizza Margherita",
        "quantity": 1,
        "unitPrice": 15.99,
        "isReturnable": true
      }
    ],
    "returnWindowEndsAt": 1641081600000,
    "hasActiveReturn": false
  }
  ```
</ResponseExample>

## Initiate Return

Create a return request for specific items from an order.

<ParamField path="orderId" type="Id<'orders'>" required>
  Order ID
</ParamField>

<ParamField path="items" type="Array<ReturnItem>" required>
  Items to return

  <Expandable title="ReturnItem">
    <ParamField path="productId" type="Id<'products'>" required>Product ID</ParamField>
    <ParamField path="quantity" type="number" required>Quantity to return</ParamField>
    <ParamField path="reason" type="string" required>Return reason</ParamField>
    <ParamField path="imageStorageId" type="Id<'_storage'>">Optional evidence image</ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const returnRequestId = await convex.mutation(api.customers.returns.initiateReturn, {
    orderId: "o123456789",
    items: [
      { productId: "p123", quantity: 1, reason: "Damaged on arrival" }
    ]
  });
  ```

  ```javascript JavaScript theme={null}
  const returnRequestId = await convex.mutation("customers.returns.initiateReturn", {
    orderId: "o123456789",
    items: [
      { productId: "p123", quantity: 1, reason: "Damaged on arrival" }
    ]
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  "rr123456789"
  ```
</ResponseExample>

## Get Return Request

Fetch full details of a return request.

<ParamField path="returnRequestId" type="Id<'returnRequests'>" required>
  Return request ID
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const details = await convex.query(api.customers.returns.getReturnRequest, {
    returnRequestId: "rr123456789"
  });
  ```

  ```javascript JavaScript theme={null}
  const details = await convex.query("customers.returns.getReturnRequest", {
    returnRequestId: "rr123456789"
  });
  ```
</CodeGroup>

## List My Returns

List a customer's return requests with pagination.

<ParamField path="paginationOpts" type="PaginationOptions" required>
  Pagination configuration
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const results = await convex.query(api.customers.returns.listMyReturns, {
    paginationOpts: { numItems: 20, cursor: null }
  });
  ```

  ```javascript JavaScript theme={null}
  const results = await convex.query("customers.returns.listMyReturns", {
    paginationOpts: { numItems: 20, cursor: null }
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "page": [
      {
        "_id": "rr123",
        "orderId": "o123",
        "store": { "_id": "s1", "name": "Mario's Pizza", "logoUrl": null },
        "status": "pending",
        "itemsCount": 1,
        "totalRefundAmount": 15.99,
        "createdAt": 1640995200000
      }
    ],
    "isDone": false,
    "continueCursor": "eyJmIjoyMH0"
  }
  ```
</ResponseExample>

## Cancel Return

Cancel a pending return request.

<ParamField path="returnRequestId" type="Id<'returnRequests'>" required>
  Return request ID
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  await convex.mutation(api.customers.returns.cancelReturn, {
    returnRequestId: "rr123456789"
  });
  ```

  ```javascript JavaScript theme={null}
  await convex.mutation("customers.returns.cancelReturn", {
    returnRequestId: "rr123456789"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  null
  ```
</ResponseExample>