Vendor Returns

A vendor return (also called an RMA — Return Merchandise Authorization) is the formal record of goods you are sending back to a supplier. Whether the items arrived defective, were the wrong product, exceeded what you ordered, or were damaged in transit, a vendor return captures which items are going back, what they cost, and where the process stands — all the way from drafting the return through shipping it out and receiving credit.

Vendor returns complement vendor invoices: where an invoice records what you owe the supplier, a return records what the supplier owes back to you.

Creating a vendor return #

New returns are created from Purchasing → Vendor Returns → New Vendor Return. The header form is brief — the detail lives in the line items you add next.

• Vendor — the supplier you are returning to. Required. Selecting a vendor links the return to that vendor's record in your vendor directory.
• RMA Number — auto-generated in the format RMA-0001 if you leave it blank, or type your own if the vendor has assigned one. You can always update it later once the supplier responds.
• Reason — the primary reason for the return: Defective, Wrong Item, Excess Inventory, Damaged in Transit, or Other. Optional but useful for reporting.
• Notes — free-text field for any instructions, vendor contact details, or special handling requirements.
• Status — set to Draft when the return is created, and shown on the edit form without being editable there. Buttons on the return's page move it; see Lifecycle below. The status is not shown on the creation form at all.
• Total Amount — calculated automatically from the line items; displayed as a read-only field in dollars on the detail page.

Line items (items to return) #

Once the header is saved, use the Items to Return tab to add the individual Products going back. Each line captures:

• Unit — the specific tracked unit being returned, looked up by name or barcode (I-xxxxxxxx). Selecting a unit auto-fills the Product and Unit Cost from the unit record.
• Product — the Product for this line; auto-populated when you choose a unit, or set independently for returns not tied to a specific tracked unit.
• Original PO Line — optionally link the line back to the purchase order line it was received on, for traceability.
• Quantity — how many units (or what amount) are being returned. Supports decimals for partial returns of measured goods.
• Unit Cost — the per-unit cost in dollars for this return line. Over the API, unit_cost is sent and returned in cents (e.g. 2500 = $25.00). Adding or editing a line immediately recalculates the header Total Amount.
• Notes — per-line remarks.

The table shows each line's Product name, the From Bin where the unit currently lives, quantity, unit cost, and notes. Lines can be edited or deleted at any time before the return is shipped; each change recalculates the running total.

Lifecycle: Draft to Completed #

Every vendor return moves through a predictable sequence of statuses shown as a color-coded badge:

• Draft (gray) — the return is being assembled; no inventory movements have been recorded yet. You can add, edit, or remove lines freely.
• Submitted (blue) — the return has been communicated to the vendor and is awaiting their approval or shipping instructions. The Mark as Shipped action becomes available.
• Shipped (amber) — the return has left your warehouse. Triggering Mark as Shipped records a Return Out inventory movement for each line item that has a linked unit, physically removing the goods from their bin in the system.
• Completed (green) — the supplier has acknowledged receipt and any credit or refund has been arranged.
• Cancelled (red) — the return was closed without being completed.

Four buttons on the return's page move it, for anyone who can edit vendor returns:

• Submit — moves a Draft return to Submitted.
• Mark as Shipped — moves a Submitted return to Shipped, and is the only one that writes inventory movements.
• Mark as Completed — moves a Shipped return to Completed.
• Cancel Return — closes a Draft, Submitted or Shipped return. Movements already recorded by shipping stay; the goods really did leave.

Undo can reverse a Submit, a Cancel Return or a Mark as Completed, none of which touch stock.

Mark as Shipped is the only status transition that writes inventory movements. It is only available when the return is in Submitted status. Confirm the action in the modal — it cannot be undone without a manual adjustment.

Inventory impact #

When a return is marked as shipped, Knowledge ERP records a Return Out movement against every line item that points to a specific unit. The movement captures the Product, quantity, source location, and source bin, with the RMA number noted in the movement notes. You can review these in the unit's movement history on Inventory → Units.

Returns that reference only a Product (without a specific unit) do not trigger automatic movements; you will need to post a manual adjustment if you need the quantity change reflected in stock.

The return list and filters #

The return list (Purchasing → Vendor Returns) shows each return's RMA number, vendor, status, reason, total, and creation date, sorted newest first. Filter by Status to focus on returns that need action — for example, all Submitted returns awaiting shipment. Soft-deleted returns are hidden by default; use the Trashed filter to include them.

What lives on the return page #

Open a return to find its header details plus tabs for everything attached:

• Items to Return — the line items, editable until the return ships.
• Attachments — packing slips, vendor correspondence, photos of damage.
• Change History — a full audit trail of every edit, showing who changed what and when.

Printing #

The view page includes a Print action that opens a formatted PDF of the return in a new tab with your browser's print dialogue over it — useful for including in the physical shipment. If the dialogue does not appear, the Print button on that tab opens it. Download PDF on the same tab saves the file, for emailing to the vendor.

How vendor returns relate to other modules #

• Vendors — the parent vendor record stores contact details and purchase history. See Vendors & Contacts.
• Purchase Orders — each return line can reference the original PO line it was received on, keeping the inbound and outbound paper trail linked. See Purchase Orders.
• Vendor Invoices — once a return is completed, any vendor credit should be reconciled against open vendor invoices. See Vendor Invoices & Payments.
• Units — shipment creates Return Out movements on the specific units sent back. See Units.

Doing it from the API #

# List returns, filtered by vendor and status
curl "https://your-domain.com/api/v1/vendor-returns?vendor_id=<id>&status=submitted" \
  -H "Authorization: Bearer $TOKEN"

# Create a new vendor return
curl -X POST "https://your-domain.com/api/v1/vendor-returns" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "<vendor-id>",
    "reason": "defective",
    "notes": "Batch arrived with cracked housings — RMA requested per email 2026-06-01"
  }'

# Add a line item (unit_cost in cents: 4500 = $45.00)
curl -X POST "https://your-domain.com/api/v1/vendor-return-items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_return_id": "<return-id>",
    "product_id": "<product-id>",
    "quantity": 3,
    "unit_cost": 4500
  }'

# Submit it (Draft to Submitted); /cancel and /complete move it on
curl -X POST "https://your-domain.com/api/v1/vendor-returns/<return-id>/submit" \
  -H "Authorization: Bearer $TOKEN"

Status is read-only on create and update. A request that includes status is refused with 422. Use POST /vendor-returns/{id}/submit, /cancel and /complete. Shipped is reached only by Mark as Shipped in the panel, which records the stock movements; there is no API endpoint for shipping a return.

Money fields (unit_cost, total_amount) are integers in cents over the API (4500 = $45.00). The UI always displays dollars.