TWIGZ Backend API Documentation

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"
});

const eligibility = await convex.query("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

Show ReturnItem

productId

Id<'products'>

required

Product ID

quantity

number

required

Quantity to return

reason

string

required

Return reason

imageStorageId

Id<'_storage'>

Optional evidence image

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

const returnRequestId = await convex.mutation("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"
});

const details = await convex.query("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 }
});

const results = await convex.query("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"
});

await convex.mutation("customers.returns.cancelReturn", {
  returnRequestId: "rr123456789"
});

null

Shared Functions

Store Management

Customer Experience

Admin & Platform

HTTP Endpoints

Scheduled Tasks

Database

Development

Customer Returns

Overview

Check Return Eligibility

Initiate Return

Get Return Request

List My Returns

Cancel Return

​Overview

​Check Return Eligibility

​Initiate Return

​Get Return Request

​List My Returns

​Cancel Return

Overview

Check Return Eligibility

Initiate Return

Get Return Request

List My Returns

Cancel Return