Skip to main content

​
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.
​
orderId
Id<'orders'>
required
Order ID to check
const eligibility = await convex.query(api.customers.returns.checkReturnEligibility, {
  orderId: "o123456789"
});

{
  "isEligible": true,
  "returnableItems": [
    {
      "productId": "p123",
      "productName": "Pizza Margherita",
      "quantity": 1,
      "unitPrice": 15.99,
      "isReturnable": true
    }
  ],
  "returnWindowEndsAt": 1641081600000,
  "hasActiveReturn": false
}

​
Initiate Return

Create a return request for specific items from an order.
​
orderId
Id<'orders'>
required
Order ID
​
items
Array<ReturnItem>
required
Items to return
const returnRequestId = await convex.mutation(api.customers.returns.initiateReturn, {
  orderId: "o123456789",
  items: [
    { productId: "p123", quantity: 1, reason: "Damaged on arrival" }
  ]
});

"rr123456789"

​
Get Return Request

Fetch full details of a return request.
​
returnRequestId
Id<'returnRequests'>
required
Return request ID
const details = await convex.query(api.customers.returns.getReturnRequest, {
  returnRequestId: "rr123456789"
});

​
List My Returns

List a customer’s return requests with pagination.
​
paginationOpts
PaginationOptions
required
Pagination configuration
const results = await convex.query(api.customers.returns.listMyReturns, {
  paginationOpts: { numItems: 20, cursor: 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"
}

​
Cancel Return

Cancel a pending return request.
​
returnRequestId
Id<'returnRequests'>
required
Return request ID
await convex.mutation(api.customers.returns.cancelReturn, {
  returnRequestId: "rr123456789"
});

null