> ## 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.

# Store Returns

> Review and manage customer return requests for a store

## Overview

Store Returns API allows store owners to list returns, review detailed requests, respond (approve/reject), mark pickups completed (triggering refunds), and configure return policies.

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

## List Store Returns

List return requests for a store with optional status filtering.

<ParamField path="storeId" type="Id<'stores'>">
  Store ID (defaults to authenticated owner's store)
</ParamField>

<ParamField path="status" type="'pending' | 'approved' | 'rejected' | 'picked_up' | 'refunded' | 'cancelled'">
  Optional status filter
</ParamField>

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

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

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

## Get Return Request Details

Get the full details of a return request for store review.

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

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

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

## Respond To Return

Approve or reject a return request.

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

<ParamField path="approved" type="boolean" required>
  Decision: true to approve, false to reject
</ParamField>

<ParamField path="reason" type="string">
  Optional reason (required when rejecting)
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  await convex.mutation(api.stores.returns.respondToReturn, {
    returnRequestId: "rr123456789",
    approved: false,
    reason: "Item used"
  });
  ```

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

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

## Mark Pickup Completed

Mark a return as picked up. This will schedule refund processing.

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

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

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

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

## Update Return Policy

Configure store-level return policy settings.

<ParamField path="storeId" type="Id<'stores'>">
  Store ID (defaults to authenticated owner's store)
</ParamField>

<ParamField path="allowsReturns" type="boolean">
  Whether returns are allowed
</ParamField>

<ParamField path="returnWindowDays" type="number">
  Return window in days (1-90)
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  await convex.mutation(api.stores.returns.updateReturnPolicy, {
    allowsReturns: true,
    returnWindowDays: 14
  });
  ```

  ```javascript JavaScript theme={null}
  await convex.mutation("stores.returns.updateReturnPolicy", {
    allowsReturns: false
  });
  ```
</CodeGroup>

## Update Product Returnability

Toggle whether a product is returnable.

<ParamField path="productId" type="Id<'products'>" required>
  Product ID
</ParamField>

<ParamField path="isReturnable" type="boolean" required>
  Whether product is returnable
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  await convex.mutation(api.stores.returns.updateProductReturnability, {
    productId: "p123",
    isReturnable: true
  });
  ```

  ```javascript JavaScript theme={null}
  await convex.mutation("stores.returns.updateProductReturnability", {
    productId: "p123",
    isReturnable: false
  });
  ```
</CodeGroup>