Things to know about repayment requests
A repayment request represents a return. What every integration should know before working with returns: what a repayment request contains, its lifecycle status, the statuses of the return shipping and the return reasons.
What a repayment request contains
The RepaymentRequest object is the root of everything the API exposes about a return. Its main parts:
- Identifiers:
numberis the code identifying the request;orderis the order the goods come from. An order can have more than one repayment request over time. status: where the return is in its lifecycle, see Statuses below.causal: the reason of the return and how it is refunded, see Return reasons below.lines: the order lines selected for the return, oneRepaymentLineeach, with quantity, SKU and unit prices: what the customer is expected to send back.returnedLines: the warehouse evaluation of the goods that came back, oneRepaymentReturnedLinefor each line of the return (linepoints to it), plus the rows the warehouse adds for items that were not expected as part of the return (lineis null andquantityExpectedis 0).quantityReceivedandquantityCompliantare null until the warehouse records the reception. The warehouse fills them with the mutations of Manage returned lines.shipping: the return shipping (RepaymentShipping), travelling from the customer back to the warehouse: sender address, carrier and tracking data,statusandbookingStatus(see Return shipping statuses below), the destinationwarehouse, itsparcelsand its documents, the shippinglabelsand theproforma. It can be null.fiscalDocument: the credit note issued for the return, see Get repayment documents.refundTransactions: the refund payment transactions linked to the return, see Payments.- Dates:
createdAtandupdatedAt; useupdatedAtto pick up what changed since your last poll, see Query repayment requests.
The RepaymentRequest reference documents every field; Get repayment request details shows a complete query.
Statuses
A repayment request exposes a single RepaymentStatus through RepaymentRequest.status. Typical progression:
The meaning of each status is documented on the RepaymentStatus enum reference. Note the draft status, not part of the flow above: ignore repayment requests in that status. OMS can notify your integration every time a repayment request enters a status — see the RepaymentRequest status change webhook events.
Return shipping statuses
The return shipping (RepaymentRequest.shipping) uses the same ShippingStatus values documented for order shippings — read them in the context of a return, where the parcel travels from the customer back to the warehouse (e.g. delivered means the returned goods reached the warehouse).
The return shipping also carries a bookingStatus, the state of the booking process that produces the shipping label (waybill) for the return — the same ShippingBookingStatus values as order shippings, null until the booking starts.
Return reasons
Every repayment request carries the reason of the return in causal, a RepaymentCausal object: description is the reason as configured in OMS and refundKind states how that reason is refunded (see RepaymentCausalRefundKind).
The reasons are configured in OMS by Calicantus, shared by every project, and the list can change over time. These are the reasons configured today:
- Defective/Damaged product
- Warehouse error
- returned inventory
- Missing delivery
- Invoice request
- Out of stock
- Customer cancelled
- Partial refund
- Withdrawal right
- Fraud & Chargeback
- System error - Test
- Invoice correction
- return/replacement
- Product trial
- No payment
- Warranty
- Sales note adjustment
- VAT refund
- Sales note request
- Returned empty
- Customs duty refused
A reason does not always imply goods coming back: a request with the reason "Customer cancelled" opened before the order is shipped refunds the order without a return shipping, and the order keeps its completed status — see Order statuses.
If your integration needs to match on a specific reason (for example to trigger an operation of yours), agree on it with Calicantus.