TWIGZ Backend API Documentation

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.

storeId

Id<'stores'>

Store ID (defaults to authenticated owner’s store)

status

Optional status filter

paginationOpts

PaginationOptions

required

Pagination configuration

const results = await convex.query(api.stores.returns.listStoreReturns, {
  status: "pending",
  paginationOpts: { numItems: 20, cursor: null }
});

const results = await convex.query("stores.returns.listStoreReturns", {
  paginationOpts: { numItems: 20, cursor: null }
});

Get Return Request Details

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

returnRequestId

Id<'returnRequests'>

required

Return request ID

const details = await convex.query(api.stores.returns.getReturnRequestDetails, {
  returnRequestId: "rr123456789"
});

const details = await convex.query("stores.returns.getReturnRequestDetails", {
  returnRequestId: "rr123456789"
});

Respond To Return

Approve or reject a return request.

returnRequestId

Id<'returnRequests'>

required

Return request ID

approved

boolean

required

Decision: true to approve, false to reject

reason

string

Optional reason (required when rejecting)

await convex.mutation(api.stores.returns.respondToReturn, {
  returnRequestId: "rr123456789",
  approved: false,
  reason: "Item used"
});

await convex.mutation("stores.returns.respondToReturn", {
  returnRequestId: "rr123456789",
  approved: true
});

null

Mark Pickup Completed

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

returnRequestId

Id<'returnRequests'>

required

Return request ID

await convex.mutation(api.stores.returns.markPickupCompleted, {
  returnRequestId: "rr123456789"
});

await convex.mutation("stores.returns.markPickupCompleted", {
  returnRequestId: "rr123456789"
});

null

Update Return Policy

Configure store-level return policy settings.

storeId

Id<'stores'>

Store ID (defaults to authenticated owner’s store)

allowsReturns

boolean

Whether returns are allowed

returnWindowDays

number

Return window in days (1-90)

await convex.mutation(api.stores.returns.updateReturnPolicy, {
  allowsReturns: true,
  returnWindowDays: 14
});

await convex.mutation("stores.returns.updateReturnPolicy", {
  allowsReturns: false
});

Update Product Returnability

Toggle whether a product is returnable.

productId

Id<'products'>

required

Product ID

isReturnable

boolean

required

Whether product is returnable

await convex.mutation(api.stores.returns.updateProductReturnability, {
  productId: "p123",
  isReturnable: true
});

await convex.mutation("stores.returns.updateProductReturnability", {
  productId: "p123",
  isReturnable: false
});

Shared Functions

Store Management

Customer Experience

Admin & Platform

HTTP Endpoints

Scheduled Tasks

Database

Development

Store Returns

Overview

List Store Returns

Get Return Request Details

Respond To Return

Mark Pickup Completed

Update Return Policy

Update Product Returnability

​Overview

​List Store Returns

​Get Return Request Details

​Respond To Return

​Mark Pickup Completed

​Update Return Policy

​Update Product Returnability

Overview

List Store Returns

Get Return Request Details

Respond To Return

Mark Pickup Completed

Update Return Policy

Update Product Returnability