Customer Returns

A customer return — sometimes called an RMA (return merchandise authorization) — is the formal record of a customer sending goods back. Each return is numbered automatically (e.g. CRA-0001), linked to the customer and optionally to the original sales order, and walked through a status lifecycle from Draft to Completed. As items arrive back in the warehouse the receiving workflow creates new inventory units and updates the return's progress. When the return is approved, a credit memo can be generated in one click.

RMA numbers follow the pattern CRA-XXXX and are assigned automatically on creation. You can also type your own number before saving if your process requires it.

Creating a return #

Open Sales → Customer Returns → New Return and fill in:

• Customer — required; the dropdown is searchable. Selecting a customer filters the Sales Order picker to only that customer's orders.
• Sales Order — optional link to the originating order. Leaving it blank is fine for over-the-counter or informal returns.
• Status — shown on the form but not editable there. A new return starts at Draft; see Status lifecycle for what moves it.
• Reason — Defective, Wrong Item, Damaged in Transit, No Longer Needed, or Other. Optional but useful for reporting.
• Notes (printed on the customer's copy) — free text that appears on the return PDF the customer receives.
• Internal notes (staff only) — free text that is never printed, emailed or shown in the customer portal.
• Total Amount — read-only on the form; it is recalculated from line items every time a line is added, updated, or removed.
• Custom fields — any extra attributes your account has defined for returns appear at the bottom of the form.

Status lifecycle #

A return moves through five statuses:

• Draft — just created; still being set up, no items received yet.
• Submitted — the customer has been authorized to ship the goods back.
• Received — at least one line item has some quantity received.
• Completed — every line item is fully received. The system sets this automatically once the last item is received.
• Cancelled — closed. Cancelled and Completed returns block further receiving.

Two buttons on the return's page move it by hand, for anyone who can edit returns:

• Submit — moves a Draft return to Submitted.
• Cancel Return — moves a Draft, Submitted or Received return to Cancelled. Anything already received stays in stock, and the Generate Credit Memo button is no longer offered for the return.

Received and Completed are set by receiving items on the Receive page. A return requested through the customer portal starts at Submitted. Undo can reverse a Submit or a Cancel.

Return line items #

The Items tab on the return lists what the customer is expected to send back. Each line records:

• Product — which product is being returned.
• Quantity — how many the customer is expected to return.
• Quantity Received — how many have actually arrived. This is updated by the receiving workflow, not by hand.
• Unit Price — the credit value per unit in dollars (stored as cents internally; see the API note below).
• Notes — line-level comments.

The return's Total Amount is the sum of unit_price × quantity across all lines and updates automatically whenever a line changes.

Receiving items back into inventory #

Opening a return that is not yet Completed or Cancelled reveals a Receive Items button in the header. The dedicated Receive page offers a barcode-scan-first interface:

1. Scan a barcode — scan the Product barcode (or type it) to auto-select the matching line. The field clears immediately so you can keep scanning.
2. Enter a quantity — the quantity field is pre-filled with the remaining-to-receive amount for that line; edit it if you're only receiving a partial shipment.
3. Confirm — the system restocks the Units (status In Stock) into the receiving bin, posts a Return In movement against them, increments quantity_received on the line, and refreshes the return's status.

The page shows a running count of received vs. total lines and a recent-receipts feed so you can verify what just came in without scrolling the full table.

Where returned stock lands #

Returned goods are stock arriving, so they land in the receiving bin of a location, exactly as a delivery does — and, exactly as with a delivery, somebody still has to put them away afterwards. The Receive page names the bin before you confirm ("Lands in Downtown Studio › Receiving") and again in the recent-receipts feed, so you always know which shelf to walk the box to.

The location is taken from whichever of these the return states first:

1. The drop-off appointment, if the return was booked as one — where the customer actually brought the goods.
2. The sales order's location — where the goods shipped from.
3. The location you are working at (your active location).

If the location has no nominated receiving bin, wherever that product was last put away at that location is used instead. If none of the three names a location — a multi-location business receiving a return with no appointment and an order that names no location, with no active location selected — the units are restocked without a bin and you'll want to place them by hand.

You can receive the same line in multiple sessions. Each partial receive adds to quantity_received until it reaches the full quantity, at which point the line is considered fully received.

Credit memos #

Once a return is Received (some items back) or Completed (all items back) you can issue a credit memo from the return's view page. The credit memo's amount reflects only the value of items received so far (unit price × quantity_received), so issuing one against a partially-received return credits just the received portion — for a Completed return that equals the full total. The memo is created with status Issued. A return can have at most one credit memo; after it has been generated, the credit memo appears on the return page with a link.

Over the API, POST /customer-returns/{id}/credit-memo issues the memo for the received amount (returns 422 if nothing has been received yet, or if a memo already exists).

The return list #

Sales → Customer Returns shows every return with its RMA #, Customer, linked SO #, Status badge, Reason, and Total. Search by RMA number or customer name, sort by RMA #, Customer, Status, or Total, and use the Trashed filter to view soft-deleted records.

Doing it from the API #

# List returns for a specific customer
curl "https://your-domain.com/api/v1/customer-returns?customer_id=<id>" \
  -H "Authorization: Bearer $TOKEN"

# Create a return
curl -X POST "https://your-domain.com/api/v1/customer-returns" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "<customer-id>",
    "sales_order_id": "<so-id>",
    "reason": "defective",
    "notes": "Customer reported faulty power switch."
  }'

# Submit it (Draft → Submitted); /cancel cancels it
curl -X POST "https://your-domain.com/api/v1/customer-returns/<return-id>/submit" \
  -H "Authorization: Bearer $TOKEN"

# Add a line item (unit_price in cents)
curl -X POST "https://your-domain.com/api/v1/customer-return-items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_return_id": "<return-id>",
    "product_id": "<product-id>",
    "quantity": 2,
    "unit_price": 4999
  }'

Status is read-only on create and update. A request that includes status is refused with 422. Use the submit and cancel endpoints, and receive the items to reach Received and Completed.

quantity_received is read-only on the API. A customer-return-items create or update that sends it is refused with 422, whatever the return's status. It goes up when the goods are received on the Receive page, which puts the units back into stock and records the stock movements; the credit memo is worked out from it. There is no API endpoint for receiving a return yet.

Money fields are integers in cents — unit_price: 4999 means $49.99, and the total_amount on the return is likewise in cents. Filter the list with customer_id and/or status query parameters; results are paginated at 50 per page.