Return merchandise authorisations

Authorise customer returns against fulfilled invoices, approve or reject them, receive returned stock and keep notes.

A return merchandise authorisation (RMA) records the goods a customer may return from a fulfilled invoice. These endpoints create, update, approve, reject and delete RMAs, receive the returned stock, and manage the RMA’s notes. This area has 19 endpoints, each available in all seven SDKs.

Receiving returned stock commits it, and a received RMA cannot be deleted.

At a glance

Endpoint	Method	Path	What it does
List RMAs	GET	/return_merchandise_authorisations	Lists return merchandise authorisations (RMAs), one page at a time.
Create an RMA	POST	/return_merchandise_authorisations	Creates an RMA against a fulfilled invoice.
Retrieve an RMA	GET	/return_merchandise_authorisations/{rma_id}	Returns one RMA with its lines and receipts.
List an RMA’s receipts through its invoice	GET	/invoices/{invoice_id}/return_merchandise_authorisations/{rma_code}/receive	Lists the stock receipts of one RMA, found through its invoice.
Retrieve an RMA receipt through its invoice	GET	/invoices/{invoice_id}/return_merchandise_authorisations/{rma_code}/receive/{receive_uuid}	Returns one stock receipt of an RMA, found through its invoice.
Create an RMA note	POST	/return_merchandise_authorisations/{rma_id}/notes	Adds a text note to an RMA.
Receive returned stock for an RMA	POST	/return_merchandise_authorisations/{rma_id}/receive	Records returned stock against an RMA and returns the RMA.
Delete an RMA	DELETE	/return_merchandise_authorisations/{rma_id}	Deletes a draft RMA and returns no body.
Update an RMA	PATCH	/return_merchandise_authorisations/{rma_id}	Changes an RMA’s date, note or returns.
Approve an RMA	POST	/return_merchandise_authorisations/{rma_id}/approve	Approves an RMA that is waiting for approval.
Delete an RMA note	DELETE	/return_merchandise_authorisations/{rma_id}/notes/{note_id}	Deletes a note from an RMA and returns no body.
Delete an RMA note file	DELETE	/return_merchandise_authorisations/{rma_id}/notes/{note_id}/files/{file_id}	Deletes an attachment from an RMA note and returns no body.
Reject an RMA	POST	/return_merchandise_authorisations/{rma_id}/reject	Rejects an RMA that is waiting for approval.
List RMA notes	GET	/return_merchandise_authorisations/{rma_code}/notes	Lists an RMA’s notes, one page at a time.
Retrieve an RMA note	GET	/return_merchandise_authorisations/{rma_code}/notes/{note_id}	Returns one note of an RMA under note.
List RMA note files	GET	/return_merchandise_authorisations/{rma_code}/notes/{note_id}/files	Lists the attachments of one RMA note.
Retrieve an RMA note file	GET	/return_merchandise_authorisations/{rma_code}/notes/{note_id}/files/{file_id}	Returns one attachment of an RMA note under file.
List an RMA’s receipts	GET	/return_merchandise_authorisations/{rma_code}/receive	Lists the stock receipts of an RMA, one page at a time.
Retrieve an RMA receipt	GET	/return_merchandise_authorisations/{rma_code}/receive/{receive_uuid}	Returns one stock receipt of an RMA under receive_rma.

Before you call

Register your API credentials once when your app starts, as shown in Authentication. Every SDK sample on these pages then gets its client in one line. With cURL, send the access token in an Authorization header: Authorization: Bearer $ACCESS_TOKEN.

Things to know

• Writes take the RMA’s id; the reads under it take its code. Update, delete, approve, reject, receive and the note writes need the rma_ id and refuse a code. The note and receipt reads resolve the RMA by code and return 404 for an rma_ id.
• An RMA needs a fulfilled invoice. The create body names the invoice by its internal id, inv_ followed by the invoice’s uuid without hyphens, and each return line by a fulfilled invoice line’s id.
• A new RMA has status active and return_status pending. The create call returns a short record (id, code, status, version); read the RMA for the rest.
• Approve and reject take no body and can notify approvers. Both are refused with 422 when the RMA has no pending approval.
• Notes are JSON, not forms, and carry no file. Create an RMA note takes {"note": {"note": "..."}} and no attachment.
• Listings page by cursor. Pass limit and the previous page’s pagination.next_cursor as cursor, and stop when has_more is false.