A valid request URL is required to generate request examples{
"transaction": {
"id": "ret-ok",
"number": "R-ret-ok",
"storeId": "store-1",
"sellerId": "user-camille",
"customerId": null,
"status": "completed",
"type": "return",
"lines": [
{
"skuId": "f139995b359e2702f33b391acb3d42a419197a7b2c09d04c1fe6d97ecefe4feb",
"quantity": 1,
"unitPrice": 1800
}
],
"totals": {
"subtotal": 1800,
"total": -1800,
"itemCount": 1,
"lineCount": 1
}
},
"originalTransactionId": "sale-return-seed",
"refundMethod": "cash",
"reason": "damaged"
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123,
"fieldErrors": [
{
"field": "<string>",
"message": "<string>"
}
]
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}Process a return (retour / avoir)
Processes a refund (retour) of selected lines from an original charge transaction (vente), at the price they were sold, and settles the money back through the chosen refundMethod (201). refundMethod is one of: cash (drawer pay-out), card (reversal to the payment card), store_credit (an in-store avoir / credit note), or exchange (goods swapped, no money moved). Reach for it to refund or exchange goods at the counter. A cash refund debits the store’s active register drawer and the returned units re-increment on-hand stock (both idempotent by the return id). Note: store_credit RECORDS the refund as an avoir here but does NOT mint the redeemable instrument — issuing the spendable credit note / gift card is a SEPARATE call (the giftcard/credits domain). A line is bounded by what the original sale has ALREADY refunded, not merely by what it sold: a sale of 3 units returned in full cannot be returned again under a fresh return id. An excess refuses the WHOLE request and names the quantity still refundable — nothing is partially honoured, so a caller that wants the remainder asks for that quantity explicitly. Failure conditions: 400 on a malformed body; 404 when the originalTransactionId names no known charge; 409 when the return id already exists; 422 when the return breaks an invariant (returning more units than were sold, or more than the sale has left to refund).
A valid request URL is required to generate request examples{
"transaction": {
"id": "ret-ok",
"number": "R-ret-ok",
"storeId": "store-1",
"sellerId": "user-camille",
"customerId": null,
"status": "completed",
"type": "return",
"lines": [
{
"skuId": "f139995b359e2702f33b391acb3d42a419197a7b2c09d04c1fe6d97ecefe4feb",
"quantity": 1,
"unitPrice": 1800
}
],
"totals": {
"subtotal": 1800,
"total": -1800,
"itemCount": 1,
"lineCount": 1
}
},
"originalTransactionId": "sale-return-seed",
"refundMethod": "cash",
"reason": "damaged"
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123,
"fieldErrors": [
{
"field": "<string>",
"message": "<string>"
}
]
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}Authorizations
Authorization: Bearer <token>. Accepts EITHER a Keycloak access token (scopes-in-token) OR an opaque POS session token; both resolve to the same pos.* scope vocabulary the route guards enforce.
Body
11111cash, card, store_credit, exchange 1Show child attributes
Show child attributes
11Response
The processed return: the signed refund transaction plus its refund metadata.