REST API

Alongside the GraphQL API, the RMA extension exposes a full REST API. It covers complete CRUD access for returns, items, messages, attachments, and every dictionary (statuses, reasons, conditions, resolutions, custom fields, return addresses, quick responses, workflow rules) from the admin side, dedicated actions for changing RMA status and confirming shipping, a set of "my RMA" endpoints so logged-in customers can manage their own returns, and a single anonymous endpoint that lets a guest look up an RMA by its guest ID. Use this API to integrate RMA data with external systems (ERPs, helpdesks, marketplaces) or to build a custom storefront return flow.

Authentication

This API uses three different authentication levels, depending on the route:

• Admin / integration token — all /V1/mirasvit-rma/* routes require a bearer token issued to an admin user or an integration, and the ACL resource listed for that route (each section below states which one). See Magento's Authentication guide for how to obtain an admin/integration token.
• Customer token — all /V1/mine/rma/* routes require a bearer token issued to a logged-in customer (resource ref="self" in webapi.xml), and always operate on that customer's own RMAs. See Magento's customer token guide for how to obtain one.
• Anonymous — the single /V1/guest/rma/{guestId} route (resource ref="anonymous") requires no token at all. Anyone who has the guestId value can call it, so treat that value like a secret — see the Guest RMA Lookup section below.

Filtering, sorting, and pagination

Every getList-style endpoint (and the customer getMyRmaList, getMyRmaItems, getMyRmaMessages endpoints) accepts a standard Magento searchCriteria query parameter for filtering, sorting, and pagination. Refer to Magento's Search using REST APIs guide for the full searchCriteria[filter_groups]/searchCriteria[sort_orders]/searchCriteria[pageSize] syntax — it isn't re-documented here.

RMA

Required ACL resource: Mirasvit_Rma::rma_rma for reads, Mirasvit_Rma::add to create/update, Mirasvit_Rma::delete to delete.

Method	URL	Description
GET	/V1/mirasvit-rma/rmas	Get a list of RMAs (accepts searchCriteria)
GET	/V1/mirasvit-rma/rmas/{rmaId}	Get a single RMA by ID
POST	/V1/mirasvit-rma/rmas	Create a new RMA
PUT	/V1/mirasvit-rma/rmas/{rmaId}	Update an existing RMA
DELETE	/V1/mirasvit-rma/rmas/{rmaId}	Delete an RMA

Rma object

Attribute	Data Type	Description
id	Int	RMA ID
increment_id	String	RMA number (e.g. RMA-1)
guest_id	String	Guest lookup token, present only on guest-submitted RMAs (see Guest RMA Lookup)
firstname	String	Customer first name
lastname	String	Customer last name
company	String	Customer company
telephone	String	Customer phone number
email	String	Customer email
street	String	Return contact street address
city	String	Return contact city
region	String	Return contact region name
region_id	Int	Return contact region ID
country_id	String	Return contact country code
postcode	String	Return contact postcode
customer_id	Int	Customer ID, null for a guest RMA
status_id	Int	Status ID, see Statuses
store_id	Int	Store view ID the RMA was created in
is_resolved	Boolean	Whether the RMA is in a resolved (closed-out) status
created_at	String	Created at date
updated_at	String	Updated at date
is_gift	Boolean	Whether the return concerns a gift order
is_admin_read	Boolean	Whether an admin user has opened/read the RMA
user_id	Int	Admin user ID who last acted on the RMA
last_reply_name	String	Name of the author of the last reply
ticket_id	Int	Linked Helpdesk ticket ID, if the Helpdesk integration is used
exchange_order_ids	Int[]	IDs of exchange orders created for this RMA
replacement_order_ids	Int[]	IDs of replacement orders created for this RMA (see RMA Actions)
credit_memo_ids	Int[]	IDs of credit memos created for this RMA
return_address	String	Resolved return address text shown to the customer
status_history	Object[]	History of status changes for the RMA
code	String	Read-only computed status code

info

Older versions of this module returned a top-level order_id on the RMA object. That field was removed — an RMA can span items from multiple orders, so the order reference now lives on each RMA item (order_item_id/order_id) instead of on the RMA itself.

RMA Items

Required ACL resource: Mirasvit_Rma::rma_rma for reads, Mirasvit_Rma::add to create/update, Mirasvit_Rma::delete to delete.

Method	URL	Description
GET	/V1/mirasvit-rma/items	Get a list of RMA items (accepts searchCriteria)
GET	/V1/mirasvit-rma/items/{itemId}	Get a single RMA item by ID
POST	/V1/mirasvit-rma/items	Create a new RMA item
PUT	/V1/mirasvit-rma/items/{itemId}	Update an existing RMA item
DELETE	/V1/mirasvit-rma/items/{itemId}	Delete an RMA item

Item object

Attribute	Data Type	Description
id	Int	Item ID
rma_id	Int	Parent RMA ID
order_item_id	Int	Order item ID this return line refers to
order_id	Int	Order ID this return line refers to
product_sku	String	Product SKU
name	String	Product name
reason_id	Int	Reason ID, see Reasons
resolution_id	Int	Resolution ID, see Resolutions
condition_id	Int	Condition ID, see Conditions
qty_requested	Int	Quantity requested to return
to_stock	Boolean	Whether the returned quantity should be returned to stock
product_options	Object[]	Selected product options (configurable/bundle/etc.)
created_at	String	Created at date
updated_at	String	Updated at date

RMA Messages

Required ACL resource: Mirasvit_Rma::rma_rma for reads, Mirasvit_Rma::add to create/update, Mirasvit_Rma::delete to delete.

Method	URL	Description
GET	/V1/mirasvit-rma/messages	Get a list of RMA messages (accepts searchCriteria)
GET	/V1/mirasvit-rma/messages/{messageId}	Get a single message by ID
POST	/V1/mirasvit-rma/messages	Create a new message
PUT	/V1/mirasvit-rma/messages/{messageId}	Update an existing message
DELETE	/V1/mirasvit-rma/messages/{messageId}	Delete a message

Message object

Attribute	Data Type	Description
id	Int	Message ID
rma_id	Int	Parent RMA ID
user_id	Int	Admin user ID, if the message was posted by staff
customer_id	Int	Customer ID, if the message was posted by the customer
customer_name	String	Display name of the message author
text	String	Message text
is_html	Boolean	Whether text contains HTML
is_visible_in_frontend	Boolean	Whether the message is visible to the customer on the storefront
is_customer_notified	Boolean	Whether the customer was emailed about this message
is_read	Boolean	Whether the message has been read
email_id	Int	Linked outbound email ID, if one was sent for this message
created_at	String	Created at date
updated_at	String	Updated at date

RMA Attachments

Required ACL resource: Mirasvit_Rma::rma_rma for reads, Mirasvit_Rma::add to create/update, Mirasvit_Rma::delete to delete.

Method	URL	Description
GET	/V1/mirasvit-rma/attachments	Get a list of attachments (accepts searchCriteria)
GET	/V1/mirasvit-rma/attachments/{attachmentId}	Get a single attachment by ID
POST	/V1/mirasvit-rma/attachments	Create (upload) a new attachment
PUT	/V1/mirasvit-rma/attachments/{attachmentId}	Update an existing attachment
DELETE	/V1/mirasvit-rma/attachments/{attachmentId}	Delete an attachment

Attachment object

Attribute	Data Type	Description
id	Int	Attachment ID
item_type	String	Type of entity the attachment is linked to (e.g. message)
item_id	Int	ID of the linked entity (e.g. the message ID)
uid	String	Unique attachment identifier
name	String	Original file name
type	String	MIME type
size	Int	File size, in bytes
body	String	File content, base64-encoded
created_at	String	Created at date

RMA Actions

Required ACL resource: Mirasvit_Rma::add.

Method	URL	Description
POST	/V1/mirasvit-rma/rmas/{rmaId}/status	Change the status of a single RMA
POST	/V1/mirasvit-rma/rmas/mass-status	Change the status of multiple RMAs at once
POST	/V1/mirasvit-rma/rmas/{rmaId}/mark-read	Mark a single RMA as read/unread
POST	/V1/mirasvit-rma/rmas/mass-mark-read	Mark multiple RMAs as read/unread at once
POST	/V1/mirasvit-rma/rmas/{rmaId}/replacement-order	Create a replacement order for an RMA

Request bodies

Endpoint	Body	Returns
.../{rmaId}/status	{"statusId": 3}	Updated Rma object
.../mass-status	{"rmaIds": [1, 2, 3], "statusId": 3}	true on success
.../{rmaId}/mark-read	{"isRead": true}	true on success
.../mass-mark-read	{"rmaIds": [1, 2, 3], "isRead": true}	true on success
.../{rmaId}/replacement-order	(no body)	The new replacement order ID (Int)

RMA Shipping

Required ACL resource: Mirasvit_Rma::add.

Method	URL	Description
POST	/V1/mirasvit-rma/rmas/{rmaId}/confirm-shipping	Confirm that the customer has shipped the return package

This endpoint takes no request body beyond the {rmaId} path parameter and returns true on success.

Statuses

Required ACL resource: Mirasvit_Rma::rma_dictionary_status for all methods (read and write).

Method	URL	Description
GET	/V1/mirasvit-rma/statuses	Get a list of statuses (accepts searchCriteria)
GET	/V1/mirasvit-rma/statuses/{statusId}	Get a single status by ID
POST	/V1/mirasvit-rma/statuses	Create a new status
PUT	/V1/mirasvit-rma/statuses/{statusId}	Update an existing status
DELETE	/V1/mirasvit-rma/statuses/{statusId}	Delete a status

The fields returned by this endpoint match those documented in Statuses, with these REST field names: name, code, color, sort_order, is_active, is_visible, is_show_shipping, is_main_branch, children_ids, customer_message, admin_message, history_message.

Reasons

Required ACL resource: Mirasvit_Rma::rma_dictionary_reason.

Method	URL	Description
GET	/V1/mirasvit-rma/reasons	Get a list of reasons (accepts searchCriteria)
GET	/V1/mirasvit-rma/reasons/{reasonId}	Get a single reason by ID
POST	/V1/mirasvit-rma/reasons	Create a new reason
PUT	/V1/mirasvit-rma/reasons/{reasonId}	Update an existing reason
DELETE	/V1/mirasvit-rma/reasons/{reasonId}	Delete a reason

The fields returned by this endpoint match those documented in Reasons: name, sort_order, is_active.

Conditions

Required ACL resource: Mirasvit_Rma::rma_dictionary_condition.

Method	URL	Description
GET	/V1/mirasvit-rma/conditions	Get a list of conditions (accepts searchCriteria)
GET	/V1/mirasvit-rma/conditions/{conditionId}	Get a single condition by ID
POST	/V1/mirasvit-rma/conditions	Create a new condition
PUT	/V1/mirasvit-rma/conditions/{conditionId}	Update an existing condition
DELETE	/V1/mirasvit-rma/conditions/{conditionId}	Delete a condition

The fields returned by this endpoint match those documented in Conditions: name, sort_order, is_active.

Resolutions

Required ACL resource: Mirasvit_Rma::rma_dictionary_resolution.

Method	URL	Description
GET	/V1/mirasvit-rma/resolutions	Get a list of resolutions (accepts searchCriteria)
GET	/V1/mirasvit-rma/resolutions/{resolutionId}	Get a single resolution by ID
POST	/V1/mirasvit-rma/resolutions	Create a new resolution
PUT	/V1/mirasvit-rma/resolutions/{resolutionId}	Update an existing resolution
DELETE	/V1/mirasvit-rma/resolutions/{resolutionId}	Delete a resolution

The fields returned by this endpoint match those documented in Resolutions, with these REST field names: name, code, sort_order, is_active, exchange_order_enabled, replacement_order_enabled, creditmemo_enabled.

Custom Fields

Required ACL resource: Mirasvit_Rma::rma_dictionary_field.

Method	URL	Description
GET	/V1/mirasvit-rma/fields	Get a list of custom fields (accepts searchCriteria)
GET	/V1/mirasvit-rma/fields/{fieldId}	Get a single custom field by ID
POST	/V1/mirasvit-rma/fields	Create a new custom field
PUT	/V1/mirasvit-rma/fields/{fieldId}	Update an existing custom field
DELETE	/V1/mirasvit-rma/fields/{fieldId}	Delete a custom field

The fields returned by this endpoint match those documented in Custom Fields, with these REST field names: name, code, type, accessory, values, description, is_active, sort_order, is_required_staff, is_required_customer, is_visible_customer, is_editable_customer, visible_customer_status, is_show_in_confirm_shipping.

Return Addresses

Required ACL resource: Mirasvit_Rma::rma_return_addresses.

Method	URL	Description
GET	/V1/mirasvit-rma/addresses	Get a list of return addresses (accepts searchCriteria)
GET	/V1/mirasvit-rma/addresses/{addressId}	Get a single return address by ID
POST	/V1/mirasvit-rma/addresses	Create a new return address
PUT	/V1/mirasvit-rma/addresses/{addressId}	Update an existing return address
DELETE	/V1/mirasvit-rma/addresses/{addressId}	Delete a return address

The fields returned by this endpoint match those documented in Return Addresses, with these REST field names: name, address, sort_order, is_active.

Quick Responses

Required ACL resource: Mirasvit_Rma::rma_dictionary_template.

Method	URL	Description
GET	/V1/mirasvit-rma/quick-responses	Get a list of quick responses (accepts searchCriteria)
GET	/V1/mirasvit-rma/quick-responses/{responseId}	Get a single quick response by ID
POST	/V1/mirasvit-rma/quick-responses	Create a new quick response
PUT	/V1/mirasvit-rma/quick-responses/{responseId}	Update an existing quick response
DELETE	/V1/mirasvit-rma/quick-responses/{responseId}	Delete a quick response

The fields returned by this endpoint match those documented in Quick Responses: name, template, is_active.

Workflow Rules

Required ACL resource: Mirasvit_Rma::rma_rule.

Method	URL	Description
GET	/V1/mirasvit-rma/rules	Get a list of workflow rules (accepts searchCriteria)
GET	/V1/mirasvit-rma/rules/{ruleId}	Get a single workflow rule by ID
POST	/V1/mirasvit-rma/rules	Create a new workflow rule
PUT	/V1/mirasvit-rma/rules/{ruleId}	Update an existing workflow rule
DELETE	/V1/mirasvit-rma/rules/{ruleId}	Delete a workflow rule

The fields returned by this endpoint match those documented in Workflow Rules, with these REST field names: name, event, is_active, conditions_serialized, status_id, sort_order, is_stop_processing, is_resolved, email_subject, email_body, is_send_owner, is_send_department, is_send_user, is_send_attachment, other_email, user_id.

Offline Orders

Required ACL resource: Mirasvit_Rma::rma_api_offline_order.

Method	URL	Description
GET	/V1/mirasvit-rma/offline-orders	Get a list of offline orders (accepts searchCriteria)
GET	/V1/mirasvit-rma/offline-orders/{offlineOrderId}	Get a single offline order by ID
POST	/V1/mirasvit-rma/offline-orders	Create a new offline order
PUT	/V1/mirasvit-rma/offline-orders/{offlineOrderId}	Update an existing offline order
DELETE	/V1/mirasvit-rma/offline-orders/{offlineOrderId}	Delete an offline order

An "offline order" represents a purchase made outside Magento (e.g. in a physical store) that a customer wants to return through the Allow RMA for offline orders flow, see Configuration Settings.

OfflineOrder object

Attribute	Data Type	Description
offline_order_id	Int	Offline order ID
receipt_number	String	Receipt/order number entered by the customer
customer_id	Int	Customer ID the offline order is associated with
store_id	Int	Store view ID
is_offline	Boolean	Always true for entities created through this endpoint

Offline Items

Required ACL resource: Mirasvit_Rma::rma_api_offline_item.

Method	URL	Description
GET	/V1/mirasvit-rma/offline-items	Get a list of offline order items (accepts searchCriteria)
GET	/V1/mirasvit-rma/offline-items/{itemId}	Get a single offline order item by ID
POST	/V1/mirasvit-rma/offline-items	Create a new offline order item
PUT	/V1/mirasvit-rma/offline-items/{itemId}	Update an existing offline order item
DELETE	/V1/mirasvit-rma/offline-items/{itemId}	Delete an offline order item

OfflineItem object

Attribute	Data Type	Description
offline_item_id	Int	Offline item ID
rma_id	Int	Parent RMA ID
offline_order_id	Int	Parent offline order ID, see Offline Orders
name	String	Product name entered by the customer
reason_id	Int	Reason ID, see Reasons
resolution_id	Int	Resolution ID, see Resolutions
condition_id	Int	Condition ID, see Conditions
qty_requested	Int	Quantity requested to return
created_at	String	Created at date
updated_at	String	Updated at date

Customer RMA Endpoints

These routes require a customer token (see Authentication above) and always operate on the logged-in customer's own RMAs — there is no separate ACL resource, since resource ref="self" restricts every request to the calling customer.

Method	URL	Description
GET	/V1/mine/rma/rmas	Get a list of the current customer's RMAs (accepts searchCriteria)
GET	/V1/mine/rma/rmas/{rmaId}	Get one of the current customer's RMAs by ID
POST	/V1/mine/rma/rmas	Create a new RMA for the current customer, using an Rma object as the body
POST	/V1/mine/rma/rmas/{rmaId}/messages	Add a message to one of the current customer's RMAs, body {"messageText": "..."}, returns a Message object
GET	/V1/mine/rma/rmas/{rmaId}/messages	Get the messages of one of the current customer's RMAs (accepts searchCriteria)
POST	/V1/mine/rma/rmas/{rmaId}/items	Add an item to one of the current customer's RMAs, using an Item object as the body
GET	/V1/mine/rma/rmas/{rmaId}/items	Get the items of one of the current customer's RMAs (accepts searchCriteria)
POST	/V1/mine/rma/rmas/{rmaId}/confirm-shipping	Confirm shipping for one of the current customer's RMAs, no body, returns true on success

These endpoints reuse the same Rma, Item, and Message objects documented above in the admin sections, since they are backed by the same underlying data interfaces (RmaInterface, ItemInterface, MessageInterface).

Guest RMA Lookup

Method	URL	Description
GET	/V1/guest/rma/{guestId}	Look up an RMA by its guest ID

This is the only fully anonymous endpoint in the API — resource ref="anonymous" in webapi.xml means it needs no bearer token at all. {guestId} is the RMA's guest_id value, a token generated for guest-submitted RMAs (see the guest_id field of the Rma object) and normally delivered to the guest by email when their return is created, so they can check its status without creating an account. Because no authentication is required, anyone who obtains a guestId value can read that RMA — treat it as a bearer credential and never expose it (for example, in logs or shareable links) beyond the guest it belongs to. The response is a single Rma object.