Skip to main content
The Returns API handles product return transactions with manager approval workflows and automatic inventory restocking.

​
Get all returns

Retrieve all return transactions. 
GET /api/returns

​
Response

Returns an array of return objects with full details.
​
id
integer
Unique return identifier
​
returnId
string
Unique return ID (format: RET-YYYYMMDD-XXXXXXXX)
​
originalSaleId
integer
ID of the original sale
​
returnDate
string
ISO 8601 timestamp of return
​
status
string
Return status (Completed, Pending, Cancelled)
​
totalRefundAmount
decimal
Total refund amount
​
processedByEmployeeId
integer
Employee who processed the return
​
approvedByEmployeeId
integer
Manager who approved the return (if required)
​
managerApprovalRequired
boolean
Whether manager approval was required
​
notes
string
Additional notes
​
returnItems
array
Array of returned items

​
Example request

curl -X GET "https://api.example.com/api/returns" \
  -H "Content-Type: application/json"

​
Get return by ID

Retrieve details of a specific return. 
GET /api/returns/{id}

​
Path parameters

​
id
integer
required
Return ID

​
Example request

curl -X GET "https://api.example.com/api/returns/1" \
  -H "Content-Type: application/json"

​
Process return

Create a new return transaction. 
POST /api/returns

​
Request body

​
originalSaleId
integer
required
ID of the original sale
​
processedByEmployeeId
integer
required
Employee processing the return
​
managerPin
string
Manager PIN for approval (required if approval is needed)
​
notes
string
Additional notes about the return
​
returnItems
array
required
Array of items being returned

​
Return item structure

​
originalSaleItemId
integer
required
ID of the original sale item
​
returnQuantity
integer
required
Quantity being returned
​
lineTotal
decimal
required
Refund amount for this item
​
condition
string
default:"good"
Item condition: good or defective
​
reason
string
required
Reason for return

​
Example request

curl -X POST "https://api.example.com/api/returns" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 2" \
  -H "X-User-Name: Cashier" \
  -d '{
    "originalSaleId": 123,
    "processedByEmployeeId": 2,
    "managerPin": "123456",
    "notes": "Customer not satisfied with product quality",
    "returnItems": [
      {
        "originalSaleItemId": 456,
        "returnQuantity": 1,
        "lineTotal": 24.99,
        "condition": "good",
        "reason": "Customer changed mind"
      }
    ]
  }'

​
Return validation

The system validates:
  • Original sale exists
  • Return time limit (if configured in system settings)
  • Return quantity doesn’t exceed available quantity
  • No duplicate returns for the same items
  • Manager approval requirements based on amount

​
Manager approval

Manager approval is required when:
  • System setting RequireManagerApprovalForReturns is enabled
  • Return amount exceeds ReturnManagerApprovalAmount threshold

​
Inventory restocking

If system setting RestockReturnedItems is enabled and item condition is good, the product quantity is automatically increased.

​
Response

{
  "id": 1,
  "returnId": "RET-20240228-A1B2C3D4",
  "originalSaleId": 123,
  "returnDate": "2024-02-28T14:30:00Z",
  "status": "Completed",
  "totalRefundAmount": 24.99,
  "processedByEmployeeId": 2,
  "approvedByEmployeeId": 1,
  "managerApprovalRequired": true,
  "notes": "Customer not satisfied with product quality",
  "returnItems": [
    {
      "id": 1,
      "originalSaleItemId": 456,
      "productId": 5,
      "productName": "Premium Coffee Beans",
      "returnQuantity": 1,
      "unitPrice": 24.99,
      "lineTotal": 24.99,
      "condition": "good",
      "reason": "Customer changed mind",
      "restockedToInventory": true
    }
  ]
}

​
Error handling

The returns endpoint provides detailed error messages:

​
Return period expired

{
  "error": "Return period expired. Returns allowed within 30 days."
}

​
Insufficient quantity

{
  "error": "Cannot return 2 of Premium Coffee Beans. Only 1 available to return (originally bought 1, already returned 0)."
}

​
Manager PIN required

{
  "error": "Manager PIN is required for this return amount."
}

​
Invalid manager PIN

{
  "error": "Invalid manager PIN. Please verify the PIN and try again."
}

​
System settings integration

The returns system respects these system settings:
  • EnableReturns: Master toggle for returns functionality
  • ReturnTimeLimitDays: Maximum days after sale to allow returns
  • RequireManagerApprovalForReturns: Require approval for all returns
  • ReturnManagerApprovalAmount: Minimum amount requiring approval
  • RestockReturnedItems: Automatically restock items in good condition

Build docs developers (and LLMs) love

Get started for freeTalk to us