Get Return Merchandise Authorisations (RMAs)
Function: return_merchandise_authorisations.list()
Purpose
This SDK function retrieves a list of all return merchandise authorisation (RMA) records available in the system using the list() method of the ExsitedSDK. It provides summary-level information for each RMA, such as date, reference note, return status, and associated invoice or item details.
Parameters
No parameters required for this endpoint.
Use Case
The return_merchandise_authorisations.list() function is used to fetch a comprehensive list of all RMAs created within the system. This is especially useful in support tools, warehouse dashboards, or finance modules where teams need to monitor returns, track processing statuses, or audit customer-initiated merchandise returns. For example, customer service representatives may use this to review pending RMAs, while warehouse personnel may filter for approved returns to initiate restocking or disposal processes. The function provides a central, real-time view of return activities and helps improve response time, tracking accuracy, and accountability across departments.
def return_merchandise_authorisations_list():
SDKConfig.PRINT_REQUEST_DATA = False
SDKConfig.PRINT_RAW_RESPONSE = False
token_file_path = "TOKEN_FILE_PATH" # e.g., "shared_token.json"
file_token_mgr = FileTokenManager(token_file_path)
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(
request_token_dto = CommonData.get_request_token_dto(),
file_token_mgr = file_token_mgr
)
try:
response = exsited_sdk.return_merchandise_authorisations.list()
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)
Response
The response is a list of return merchandise authorisation records. Each entry typically contains fields like rma_id, note, date, status, invoice_id, and a list of returned items. This data can be used to populate RMA tracking tables, generate return reports, or trigger downstream actions based on the current status (e.g., "PENDING", "RECEIVED", "COMPLETED"). If the user lacks proper permissions or the backend encounters an error, an ABException will be raised, including validation errors and raw response data for diagnostics.
ReturnMerchandiseAuthorisationListDTO(
returnMerchandiseAuthorisations = [
ReturnMerchandiseAuthorisationDTO(
id = "RMA_ID_1",
customerReturnStatus = "RETURN_STATUS_1",
customerReturnDate = "RETURN_DATE_1",
invoiceId = "INVOICE_ID_1",
note = "RMA_NOTE_1",
receivedCount = "RECEIVED_COUNT_1",
returns = [
ReturnItemDTO(
itemId = "ITEM_ID_1",
itemName = "ITEM_NAME_1",
itemUuid = "ITEM_UUID_1",
rmaReturned = "RMA_RETURNED_QUANTITY_1",
rmaRequested = "RMA_REQUESTED_QUANTITY_1",
uuid = "RETURN_ITEM_UUID_1"
)
],
createdBy = "CREATED_BY_1",
createdOn = "CREATED_ON_1",
lastUpdatedBy = "LAST_UPDATED_BY_1",
lastUpdatedOn = "LAST_UPDATED_ON_1",
uuid = "RMA_UUID_1",
version = "RMA_VERSION_1"
),
ReturnMerchandiseAuthorisationDTO(
id = "RMA_ID_2",
customerReturnStatus = "RETURN_STATUS_2",
customerReturnDate = "RETURN_DATE_2",
invoiceId = "INVOICE_ID_2",
note = "RMA_NOTE_2",
receivedCount = "RECEIVED_COUNT_2",
returns = [
ReturnItemDTO(
itemId = "ITEM_ID_2",
itemName = "ITEM_NAME_2",
itemUuid = "ITEM_UUID_2",
rmaReturned = "RMA_RETURNED_QUANTITY_2",
rmaRequested = "RMA_REQUESTED_QUANTITY_2",
uuid = "RETURN_ITEM_UUID_2"
)
],
createdBy = "CREATED_BY_2",
createdOn = "CREATED_ON_2",
lastUpdatedBy = "LAST_UPDATED_BY_2",
lastUpdatedOn = "LAST_UPDATED_ON_2",
uuid = "RMA_UUID_2",
version = "RMA_VERSION_2"
),
ReturnMerchandiseAuthorisationDTO(
id = "RMA_ID_3",
customerReturnStatus = "RETURN_STATUS_3",
customerReturnDate = "RETURN_DATE_3",
invoiceId = "INVOICE_ID_3",
note = "RMA_NOTE_3",
receivedCount = "RECEIVED_COUNT_3",
returns = [
ReturnItemDTO(
itemId = "ITEM_ID_3",
itemName = "ITEM_NAME_3",
itemUuid = "ITEM_UUID_3",
rmaReturned = "RMA_RETURNED_QUANTITY_3",
rmaRequested = "RMA_REQUESTED_QUANTITY_3",
uuid = "RETURN_ITEM_UUID_3"
)
],
createdBy = "CREATED_BY_3",
createdOn = "CREATED_ON_3",
lastUpdatedBy = "LAST_UPDATED_BY_3",
lastUpdatedOn = "LAST_UPDATED_ON_3",
uuid = "RMA_UUID_3",
version = "RMA_VERSION_3"
)
],
pagination = PaginationDTO(
records = TOTAL_RECORDS,
limit = PAGE_LIMIT,
offset = PAGE_OFFSET,
previousPage = "PREVIOUS_PAGE_URL",
nextPage = "NEXT_PAGE_URL"
)
)
Creating Return Merchandise Authorisation (RMA) for an Invoice
Function: invoice_rma_create()
Purpose
This SDK function creates a return merchandise authorisation (RMA) against a specific invoice using the invoice_rma_create() method of the ExsitedSDK. It enables the system to log customer returns, update item statuses, and begin refund or replacement workflows based on specified item and invoice details.
Parameters
| Parameter | Type | Description |
|---|---|---|
| date | String (YYYY-MM-DD) | Date of return creation. Example: "2025-07-05" |
| note | String | Optional note or reference for the return. Example: "rma #1" |
| returns | List of RmaReturnDataDTO | List of items being returned. Each return must specify quantity and UUIDs. |
| returns[].itemUuid | String | UUID of the item to be returned. |
| returns[].uuid | String | UUID of the invoice line (line item being returned). |
| returns[].rmaQuantity | String | Quantity being returned for the line item. Example: "1" |
Use Case
The invoice_rma_create() function is used when a customer initiates a return request for one or more items on an invoice. This is common in retail, wholesale, and subscription-based platforms that support product returns, exchanges, or refund processing. For example, a support agent or automated system may use this function to create an RMA for items with defects, incorrect shipments, or customer dissatisfaction. It allows precise mapping of the return to invoice lines and item UUIDs, improving traceability, inventory adjustment, and downstream refund workflows. This function supports regulatory compliance, better return tracking, and customer satisfaction workflows.
def return_merchandise_authorisations_create():
SDKConfig.PRINT_REQUEST_DATA = True
SDKConfig.PRINT_RAW_RESPONSE = True
token_file_path = "TOKEN_FILE_PATH" # e.g., "shared_token.json"
file_token_mgr = FileTokenManager(token_file_path)
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(
request_token_dto = CommonData.get_request_token_dto(),
file_token_mgr = file_token_mgr
)
try:
request_data = CreateReturnMerchandiseAuthorisationDTO(
returnMerchandiseAuthorisations = ReturnMerchandiseAuthorisationCreationDTO(
date = "RMA_DATE", # e.g., "2025-07-05"
note = "RMA_NOTE", # e.g., "rma #1"
returns = [
RmaReturnDataDTO(
itemUuid = "ITEM_UUID", # e.g., "2a311b7e-e5ff-4ad0-8b50-f96fb2089945"
uuid = "INVOICE_LINE_UUID", # e.g., "23049994-955c-41a3-bfa5-9f807fbdefa5"
rmaQuantity = "RMA_QUANTITY" # e.g., "1"
)
]
)
)
response = exsited_sdk.return_merchandise_authorisations.invoice_rma_create(
id = "INVOICE_ID", # e.g., "INV-MS4455-3492"
request_data = request_data
)
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)
Response
The response includes the generated RMA record linked to the provided invoice, typically containing attributes such as rma_id, customer_return_status, customer_return_date, returns, and status fields. These indicate the state of the return (e.g., "PENDING") and provide traceability for follow-up actions such as refunds or restocking. If the invoice ID is invalid, the item UUID is not part of the invoice, or permission is lacking, an ABException is raised with structured validation errors and raw backend output.
InvoiceReturnMerchandiseAuthorisationDetailsDTO(
invoice = ReturnMerchandiseAuthorisationDetailsDTO(
returnMerchandiseAuthorisation = ReturnMerchandiseAuthorisationDTO(
id = "RMA_ID",
customerReturnStatus = "RETURN_STATUS",
customerReturnDate = "RETURN_DATE",
invoiceId = "INVOICE_ID",
note = "RMA_NOTE",
receivedCount = "RECEIVED_COUNT",
returns = [
ReturnItemDTO(
itemId = "ITEM_ID",
itemName = "ITEM_NAME",
itemUuid = "ITEM_UUID",
rmaReturned = "RMA_RETURNED_QUANTITY",
rmaRequested = "RMA_REQUESTED_QUANTITY",
uuid = "RETURN_ITEM_UUID"
)
],
createdBy = "CREATED_BY",
createdOn = "CREATED_ON",
lastUpdatedBy = "LAST_UPDATED_BY",
lastUpdatedOn = "LAST_UPDATED_ON",
uuid = "RMA_UUID",
version = "RMA_VERSION"
)
)
)
Get Return Merchandise Authorisation by ID
Function: return_merchandise_authorisations.details()
Purpose
This SDK function retrieves the full details of a specific return merchandise authorisation (RMA) record using the details() method of the ExsitedSDK. It returns all attributes associated with the RMA, including return date, status, item details, linked invoice information, and internal notes.
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Unique identifier of the RMA record. Example: "RMA_ID" |
Use Case
The return_merchandise_authorisations.details() function is used when a detailed view of a single return request is required for processing, auditing, or user support. For example, warehouse staff may use it to confirm which items need to be inspected or restocked, while support agents may review it to process a refund or replacement. The detailed payload ensures that all aspects of the return, from item UUIDs to customer return status and invoice references, are clearly visible for operational decision-making.
def return_merchandise_authorisations_details():
SDKConfig.PRINT_REQUEST_DATA = False
SDKConfig.PRINT_RAW_RESPONSE = False
token_file_path = "TOKEN_FILE_PATH" # e.g., "shared_token.json"
file_token_mgr = FileTokenManager(token_file_path)
exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(
request_token_dto = CommonData.get_request_token_dto(),
file_token_mgr = file_token_mgr
)
try:
response = exsited_sdk.return_merchandise_authorisations.details(
id = "RMA_ID" # e.g., "RMA-00485331"
)
print(response)
except ABException as ab:
print(ab)
print(ab.get_errors())
print(ab.raw_response)
Response
The response returns a single RMA object containing all available details related to that merchandise return. Key fields include id (e.g., "RMA-00485331"), customerReturnStatus (such as "PENDING", "RECEIVED", or "CLOSED"), customerReturnDate, note, and the associated invoiceId. It also includes a list of returned items under the returns field, where each item contains its itemId, itemName, itemUuid, rmaReturned, and rmaRequested quantities. Additionally, the response may include tracking UUIDs, timestamps, and metadata useful for workflow progression, inventory actions, or financial reconciliation. This detailed structure ensures teams have full visibility into return activity for operational, legal, or customer service purposes.
ReturnMerchandiseAuthorisationDetailsDTO(
returnMerchandiseAuthorisation = ReturnMerchandiseAuthorisationDTO(
id = "RMA_ID",
customerReturnStatus = "RETURN_STATUS",
customerReturnDate = "RETURN_DATE",
invoiceId = "INVOICE_ID",
note = "RETURN_NOTE",
receivedCount = "RECEIVED_COUNT",
returns = [
ReturnItemDTO(
itemId = "ITEM_ID",
itemName = "ITEM_NAME",
itemUuid = "ITEM_UUID",
rmaReturned = "RMA_RETURNED_QUANTITY",
rmaRequested = "RMA_REQUESTED_QUANTITY",
uuid = "RETURN_ITEM_UUID"
)
],
createdBy = "CREATED_BY",
createdOn = "CREATED_ON",
lastUpdatedBy = "LAST_UPDATED_BY",
lastUpdatedOn = "LAST_UPDATED_ON",
uuid = "RMA_UUID",
version = "RMA_VERSION"
)
)