Create Return Merchandise Authorisation (RMA) for an Invoice:/invoices/{id}/return-merchandise-authorisations
Purpose
This endpoint allows the creation of a Return Merchandise Authorisation (RMA) record associated with a specific invoice. The RMA facilitates tracking of returned items by customers, including the quantity requested for return and identification of items by UUID.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | Unique identifier of the invoice |
Query Parameters
No query parameters required for this endpoint.
Use Case
Businesses use this endpoint when a customer initiates a return for items listed in a previously issued invoice. The system either generates an RMA ID or accepts a custom one, and records item-level return details. This allows proper tracking, approval, and inventory updates for returns based on actual or pending delivery.
Request Body
{
"return_merchandise_authorisations": {
"id": "RMA_ID",
"date": "RETURN_DATE",
"note": "RETURN_NOTE",
"returns": [
{
"rma_quantity": "RETURN_QUANTITY",
"item_uuid": "ITEM_UUID",
"uuid": "INVOICE_LINE_UUID"
}
]
}
}
| Field | Type | Description |
|---|---|---|
| return_merchandise_authorisations | object | Wrapper object for RMA details |
| id | string | Optional custom ID for the RMA; autogenerated if not provided |
| date | string | Date of the RMA (YYYY-MM-DD) |
| note | string | Notes for the return |
| returns | array | List of items being returned |
| returns[].rma_quantity | string | Quantity to be returned |
| returns[].item_uuid | string | UUID of the item being returned |
| returns[].uuid | string | UUID of the corresponding invoice line |
Response
The response confirms successful creation of the RMA and provides a structured summary of the return. It includes return status, related invoice ID, item return details (such as quantity requested and returned), and audit metadata. This structured response enables front-end systems and users to view, process, or update the RMA lifecycle accordingly.
{
"invoice": {
"return_merchandise_authorisation": {
"id": "RMA_ID",
"customer_return_status": "RETURN_STATUS",
"customer_return_date": "RETURN_DATE_ISO8601",
"invoice_id": "INVOICE_ID",
"note": "RETURN_NOTE",
"received_count": "RECEIVED_COUNT",
"returns": [
{
"item_id": "ITEM_ID",
"item_name": "ITEM_NAME",
"item_uuid": "ITEM_UUID",
"rma_returned": "RETURNED_QUANTITY",
"rma_requested": "REQUESTED_QUANTITY",
"uuid": "RETURN_UUID"
}
],
"created_by": "CREATED_BY",
"created_on": "CREATED_ON_ISO8601",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "LAST_UPDATED_ON_ISO8601",
"uuid": "RMA_UUID",
"version": "VERSION_NUMBER"
}
}
}
| Field | Type | Description |
|---|---|---|
| invoice.return_merchandise_authorisation | object | RMA record details for the invoice |
| id | string | RMA ID |
| customer_return_status | string | Status of the customer return (e.g., PENDING, CLOSED) |
| customer_return_date | string | ISO8601 timestamp for the return date |
| invoice_id | string | Invoice ID associated with the RMA |
| note | string | Any notes provided when creating the RMA |
| received_count | string | Number of returned items received |
| returns | array | List of returned items with metadata |
| returns[].item_id | string | ID of the item being returned |
| returns[].item_name | string | Display name of the item |
| returns[].item_uuid | string | UUID of the returned item |
| returns[].rma_returned | string | Quantity returned |
| returns[].rma_requested | string | Quantity requested for return |
| returns[].uuid | string | UUID of the individual return line |
| created_by | string | Creator of the RMA |
| created_on | string | Creation timestamp of the RMA |
| last_updated_by | string | Last user to update the RMA |
| last_updated_on | string | Last updated timestamp |
| uuid | string | UUID of the RMA record |
| version | string | Version number of the RMA record |
Receive Returned Merchandise:/invoices/{id}/return-merchandise-authorisations/{rma_id}/receive
Purpose
Marks selected return merchandise items as received and updates the RMA status accordingly.
Use Case
Used by warehouse or return processing teams to acknowledge that returned items have been physically received.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | Unique identifier of the invoice. |
| rma_id | string | Unique identifier of the return merchandise authorisation. |
Query Parameters
No query parameters required for this endpoint.
Request Body
{
"receive_return_merchandise_authorisations": {
"receive_returns": [
{
"rma_receive_quantity": "RECEIVED_QUANTITY",
"uuid": "RETURN_UUID"
}
]
}
}
| Field | Type | Description |
|---|---|---|
| receive_return_merchandise_authorisations | object | Root object containing return receipt information. |
| receive_returns | array | List of items to mark as received. |
| receive_returns[].rma_receive_quantity | string | Quantity of the item received. |
| receive_returns[].uuid | string | UUID of the individual return line. |
Response
Returns the updated RMA object reflecting received items and updated return status.
{
"return_merchandise_authorisation": {
"id": "RMA_ID",
"customer_return_status": "CLOSED",
"customer_return_date": "RETURN_DATE_ISO",
"invoice_id": "INVOICE_ID",
"note": "RMA_NOTE",
"received_count": "RECEIVED_ITEM_COUNT",
"returns": [
{
"item_id": "ITEM_ID",
"item_name": "ITEM_NAME",
"item_uuid": "ITEM_UUID",
"rma_returned": "QUANTITY_RECEIVED",
"rma_requested": "QUANTITY_REQUESTED",
"uuid": "RETURN_UUID"
}
],
"created_by": "CREATED_BY_USER",
"created_on": "CREATED_TIMESTAMP_ISO",
"last_updated_by": "UPDATED_BY_USER",
"last_updated_on": "UPDATED_TIMESTAMP_ISO",
"uuid": "RMA_UUID",
"version": "VERSION_NUMBER"
}
}
| Field | Type | Description |
|---|---|---|
| return_merchandise_authorisation | object | Contains details of the updated RMA. |
| id | string | Unique RMA identifier. |
| customer_return_status | string | Updated status of the return (e.g., CLOSED). |
| customer_return_date | string | ISO timestamp when the return was created. |
| invoice_id | string | Invoice ID linked to the return. |
| note | string | Note regarding the return. |
| received_count | string | Total number of items confirmed received. |
| returns | array | List of returned items with updated info. |
| returns[].item_id | string | ID of the item returned. |
| returns[].item_name | string | Name of the item. |
| returns[].item_uuid | string | UUID of the returned item. |
| returns[].rma_returned | string | Quantity that was actually returned. |
| returns[].rma_requested | string | Originally requested return quantity. |
| returns[].uuid | string | UUID of the individual return line. |
| created_by | string | User who created the RMA. |
| created_on | string | Timestamp when the RMA was created. |
| last_updated_by | string | User who last updated the RMA. |
| last_updated_on | string | Timestamp of last update. |
| uuid | string | UUID of the RMA object. |
| version | string | Version number for concurrency tracking. |