MasonHub ERP Integration home pagelight logo
  1. Returns
  2. Update Returns
PUT
/rmas
curl --request PUT \
     --url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/rmas \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --data '{
  "customer_identifier": "<string>",
  "return_type": "<string>",
  "line_items": [],
  "manifest_id": "<string>",
  "generate_return_label": "true",
  "customer_instructions": "<string>",
  "customer_address_name": "<string>",
  "customer_address_street_line_one": "<string>",
  "customer_address_street_line_two": "<string>",
  "customer_address_city": "<string>",
  "customer_address_state": "<string>",
  "customer_address_postal_code": "<string>",
  "customer_address_country_code": "<string>"
}'

Update existing return merchandise authorizations (RMA) with new information. This endpoint supports batch updates of multiple returns in a single request.

Updates require a full replacement of the RMA data. Include all fields in your request, not just the ones you want to change.

Only RMAs in certain statuses can be updated. Once a return is received and processed, it cannot be modified.

​
Request Body Schema

Send an array of complete RMA objects. The schema is identical to creating returns.

​
Required Fields

customer_identifier
required
string

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

return_type
required
string

Type of return. Options:

  • rma_submitted_by_customer - Customer-initiated return
  • quality_control - Quality control return
  • damaged_in_transit - Damaged during shipping
  • wrong_item_shipped - Incorrect item shipped
line_items
required
array

Array of items being returned. Each item must include:

  • customer_sku_id (string, required): Your SKU identifier
  • quantity (integer, required): Quantity being returned
  • return_reason_code (string, required): Reason for return
  • return_inventory_status (string, required): Target inventory status
  • customer_order_id (string, optional): Original order reference
  • return_notes (string, optional): Additional notes

​
Optional Fields

manifest_id
string

Manifest identifier for grouping related returns.

generate_return_label
default:true
boolean

Whether to generate a DHL return label. Requires complete customer address when true.

customer_instructions
string

Special handling instructions for warehouse team.

​
Customer Address Fields

customer_address_name
string

Customer name. Required if generate_return_label is true.

customer_address_street_line_one
string

Street address line 1. Required if generate_return_label is true.

customer_address_street_line_two
string

Street address line 2 (apartment, suite, etc.). Optional.

customer_address_city
string

City. Required if generate_return_label is true.

customer_address_state
string

State or province code. Required if generate_return_label is true.

customer_address_postal_code
string

Postal/ZIP code. Required if generate_return_label is true.

customer_address_country_code
string

Country code. Required if generate_return_label is true.

curl -X PUT "https://app.masonhub.co/{account}/api/v1/rmas" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "customer_identifier": "rma123",
      "return_type": "rma_submitted_by_customer",
      "generate_return_label": true,
      "customer_address_name": "John Smith",
      "customer_address_street_line_one": "100 First Ave",
      "customer_address_street_line_two": "Apt 18",
      "customer_address_city": "New York",
      "customer_address_state": "NY",
      "customer_address_postal_code": "10016",
      "customer_address_country_code": "US",
      "customer_instructions": "Updated: Dry clean before restocking",
      "line_items": [
        {
          "customer_order_id": "54321",
          "customer_sku_id": "shirts872340",
          "quantity": 2,
          "return_reason_code": "tooBig",
          "return_notes": "Updated quantity - both items too large",
          "return_inventory_status": "quality-control"
        }
      ]
    }
  ]'

{
  "records_submitted": 1,
  "records_processed": 1,
  "records_failed": 0,
  "records_succeeded": 1,
  "results": [
    {
      "customer_identifier": "rma123",
      "status": "success",
      "uri": "https://app.masonhub.co/demo_account/api/v1/rmas?cid=rma123",
      "updated_at": "2018-12-02T14:30:00Z"
    }
  ]
}

​
Update Behavior

When you update an RMA:

1

Status Validation

System checks that the RMA is in an updatable status

2

Full Replacement

All fields are replaced with the new data (not a partial update)

3

Label Regeneration

If address changes and generate_return_label is true, a new label is generated

4

Validation

All business rules and validations are re-applied

​
Common Update Scenarios

​
Status Restrictions

RMAs can only be updated in these statuses:

  • open: RMA created, not yet tendered
  • tendered: Package picked up (limited updates)
  • inTransit: Package in transit (limited updates)

RMAs cannot be updated once they reach:

  • delivered: Package at facility - contact support
  • received: Items processed - updates not allowed
  • undeliverable: Terminal status - create new RMA if needed

​
Return Label Regeneration

When updating an RMA with generate_return_label: true:

If the customer address changes, a new return label will be automatically generated with a new tracking number. The old label will be invalidated.

To prevent label regeneration when updating other fields:

{
  "customer_identifier": "rma123",
  "generate_return_label": false,
  // ... other fields
}

​
Best Practices

Check Status First

Verify the RMA is still in an updatable status before attempting changes.

Include All Fields

Always send complete RMA data, not just changed fields.

Validate SKUs

Ensure all line item SKUs exist in your catalog before updating.

Monitor Status

Use callbacks to track when RMAs move to non-updatable statuses.

​
Batch Updates

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

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

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