MasonHub ERP Integration home pagelight logo
  1. Returns
  2. Create Returns
POST
/rmas
curl --request POST \
     --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>",
  "return_reason_code": "<string>",
  "return_inventory_status": "<string>"
}'

Create return merchandise authorizations (RMA) for customer returns. The system supports automatic DHL return label generation and various return types.

MasonHub automatically generates DHL return labels when generate_return_label is true (default) and complete customer address is provided.

Return label URLs require API authentication and contain customer personal information. Treat them as sensitive data.

​
Request Body Schema

Send an array of RMA objects. Multiple returns can be created in a single request.

​
Required Fields

customer_identifier
required
string

Unique RMA identifier in your system. Used to reference this return in future operations.

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 (e.g., “Dry clean before restocking”).

​
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 (e.g., “NY”, “CA”). 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 (e.g., “US”, “CA”). Required if generate_return_label is true.

​
Return Reason Codes

return_reason_code
string

Standardized reason codes for analytics:

  • tooBig - Item was too large
  • tooSmall - Item was too small
  • damaged - Customer received damaged item
  • wrongItem - Customer received wrong item
  • other - Reason not captured in standard codes

​
Return Inventory Statuses

return_inventory_status
string

Target inventory status for returned items:

  • available - Ready for resale
  • quality-control - Requires inspection
  • damaged - Damaged items
  • refurbishing - Needs refurbishment
  • under-investigation - Under review
curl -X POST "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_city": "New York",
      "customer_address_state": "NY",
      "customer_address_postal_code": "10016",
      "customer_address_country_code": "US",
      "customer_instructions": "Dry clean before restocking",
      "line_items": [
        {
          "customer_order_id": "54321",
          "customer_sku_id": "shirts872340",
          "quantity": 1,
          "return_reason_code": "tooBig",
          "return_notes": "Didn'\''t fit properly",
          "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",
      "additional_data": {
        "return_label_url": "https://app.masonhub.co/demo_account/api/v1/return-labels/demo1234.pdf",
        "return_tracking_number": "9302020514103629166400"
      }
    }
  ]
}

​
Return Label Generation

When creating an RMA with return label generation:

1

Validate Address

System validates that all required address fields are provided

2

Generate Label

DHL return label is automatically generated

3

Return URLs

Response includes return_label_url and return_tracking_number

4

Email Label

Optionally email the label directly to the customer

​
Order Dependencies

RMAs can be created with or without order references. This flexibility supports:

  • Historical returns during system go-live
  • Returns without order tracking
  • Cross-order returns (single RMA referencing multiple orders)

When customer_order_id is provided, the system validates:

  • Order exists in the system
  • SKU was on the referenced order
  • Quantity doesn’t exceed original order quantity

​
Cross-Order Returns

A single RMA can reference multiple orders at the line item level:

{
  "customer_identifier": "rma123",
  "return_type": "rma_submitted_by_customer",
  "line_items": [
    {
      "customer_order_id": "order001",
      "customer_sku_id": "shirt123",
      "quantity": 1,
      "return_reason_code": "tooBig",
      "return_inventory_status": "available"
    },
    {
      "customer_order_id": "order002",
      "customer_sku_id": "pants456",
      "quantity": 2,
      "return_reason_code": "wrongItem",
      "return_inventory_status": "quality-control"
    }
  ]
}

​
Best Practices

Complete Addresses

Provide complete customer addresses for successful return label generation.

Clear Instructions

Include detailed handling instructions for quality control and restocking.

Proper Reason Codes

Use appropriate return reason codes for analytics and trend analysis.

Quality Control Routing

Route questionable returns through quality-control status for inspection.

​
Callback Events

After creating an RMA, you’ll receive rmaEvent callbacks as the return progresses:

  • tendered: Package picked up by carrier
  • inTransit: Package in transit to facility
  • delivered: Package arrived at facility
  • received: Items processed into inventory (includes line item details)