MasonHub ERP Integration home pagelight logo
  1. Returns
  2. Delete Returns
DELETE
/rmas
curl --request DELETE \
     --url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/rmas \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --data '{
  "customer_identifier": "<string>"
}'

Delete return merchandise authorizations (RMA) that are no longer needed. This endpoint performs a logical deletion for audit purposes.

Only RMAs in open status can be deleted. Returns that have been tendered to carriers or received cannot be removed.

This is a soft delete operation. RMAs are marked as deleted but remain in the system for historical tracking and reconciliation.

​
Request Body Schema

Send an array of objects containing the customer identifiers of RMAs to delete.

customer_identifier
required
string

Unique RMA identifier that matches the existing return you want to delete.

curl -X DELETE "https://app.masonhub.co/{account}/api/v1/rmas" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "customer_identifier": "rma123"
    },
    {
      "customer_identifier": "rma456"
    }
  ]'

{
  "records_submitted": 2,
  "records_processed": 2,
  "records_failed": 0,
  "records_succeeded": 2,
  "results": [
    {
      "customer_identifier": "rma123",
      "status": "deleted",
      "deleted_at": "2018-12-02T14:30:00Z"
    },
    {
      "customer_identifier": "rma456",
      "status": "deleted",
      "deleted_at": "2018-12-02T14:30:00Z"
    }
  ]
}

​
Delete Behavior

When you delete an RMA:

1

Status Validation

System checks that the RMA is in open status

2

Soft Delete

RMA is marked as deleted but remains in the system

3

Label Invalidation

Any associated return labels are invalidated

4

Audit Trail

Deletion is logged for tracking and reconciliation

​
When to Delete RMAs

​
Status Restrictions

RMAs can only be deleted when in open status. Once an RMA moves to:

  • tendered: Package picked up - contact MasonHub support
  • inTransit: Package in transit - deletion not allowed
  • delivered: Package at facility - deletion not allowed
  • received: Items processed - deletion not allowed
  • undeliverable: Terminal status - no deletion needed

​
Return Label Invalidation

When you delete an RMA that has a generated return label:

  • The return label URL is invalidated
  • The tracking number is cancelled (if possible)
  • Customer cannot use the label for shipping

If a customer has already printed and used the label, contact MasonHub support to handle the incoming package.

​
Batch Operations

You can delete multiple RMAs in a single request. The system processes each deletion independently:

  • Full Success: All RMAs deleted successfully (HTTP 200)
  • Partial Success: Some deletions succeeded, others failed (HTTP 207)
  • Full Failure: All deletions failed (HTTP 400)

When batch deleting, check the response carefully. The API returns detailed information about which RMAs were successfully deleted and which failed, including specific error reasons.

​
Best Practices

Check Status First

Verify the RMA is still in open status before attempting to delete.

Handle Partial Success

In batch operations, handle scenarios where some deletions succeed and others fail.

Notify Customers

If a return label was generated, notify customers that the label is no longer valid.

Consider Updates

If RMA details changed, consider updating instead of deleting and recreating.

​
Alternative: Cancelling Returns

Instead of deleting an RMA, you may want to:

​
Recovery from Accidental Deletion

If you accidentally delete an RMA:

  1. You can recreate it using the same customer_identifier as long as no new RMA with that identifier has been created
  2. Historical data from the soft delete is maintained in the system
  3. Contact MasonHub support if you need to recover a deleted RMA

​
Communication Best Practices

When deleting RMAs:

  1. Inform Customers: Notify customers that their return authorization is cancelled
  2. Invalidate Labels: Clearly communicate that any return labels are no longer valid
  3. Provide Alternatives: If the return is still needed, provide new instructions
  4. Track Deletions: Maintain your own records of deleted RMAs for customer service purposes