MasonHub ERP Integration home pagelight logo
  1. Returns
  2. Get Returns
GET
/rmas
curl --request GET \
     --url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/rmas \
     --header 'Authorization: Bearer <token>'

The Returns API manages RMA (Return Merchandise Authorization) processes, allowing customers to return items for processing, refund, or replacement. This endpoint retrieves return information with powerful filtering capabilities.

RMAs can be created without existing orders, facilitating go-live scenarios with historical returns.

​
Query Parameters

id
UUID[]

MasonHub RMA UUID strings. Supports batching 1-30 IDs per request.

status
string

Filter by RMA status. Options:

  • open - RMA created, awaiting return shipment
  • tendered - Return package tendered to carrier
  • inTransit - Return package in transit
  • delivered - Return package delivered to facility
  • received - Return items received and processed
  • undeliverable - Return package undeliverable
sdt
string

Start date/time filter in RFC3339 format (e.g., 2018-12-01T00:00:00Z).

edt
string

End date/time filter in RFC3339 format (e.g., 2018-12-31T23:59:59Z).

offset
default:0
integer

Pagination offset for retrieving subsequent pages of results.

limit
default:30
integer

Number of results to return. Range: 1-100.

list_type
default:detail
string

Response detail level. Options:

  • detail - Full RMA information including all fields
  • summary - Condensed view with essential fields only
curl -X GET "https://app.masonhub.co/{account}/api/v1/rmas?status=open&sdt=2018-12-01T00:00:00Z&limit=25" \
  -H "Authorization: Bearer your_jwt_token"

{
  "limit": 25,
  "offset": 0,
  "list_type": "detail",
  "data": [
    {
      "id": "vf79fyn5-ec61-7892-ae7b-57a173b68133",
      "customer_identifier": "rma123",
      "manifest_id": "manifest001",
      "return_type": "rma_submitted_by_customer",
      "status": "open",
      "package_id": "1z324897234nferg45",
      "return_tracking_number": "9302020514103629166400",
      "return_label_url": "https://app.masonhub.co/demo_account/api/v1/return-labels/demo1234.pdf",
      "customer_address_name": "John Smith",
      "customer_address_street_line_one": "100 First Ave",
      "customer_address_street_line_two": "Apt 16",
      "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,
          "quantity_received": 0,
          "return_reason_code": "tooBig",
          "return_notes": "Didn't fit properly",
          "return_inventory_status": "quality-control",
          "not_on_original_rma": false
        }
      ],
      "created_at": "2018-12-01T08:30:00Z",
      "updated_at": "2018-12-01T08:30:00Z"
    }
  ]
}

​
RMA Status Lifecycle

Understanding the status progression helps you track returns effectively:

1

Open

RMA created, awaiting return shipment from customer

2

Tendered

Return package tendered to carrier for pickup

3

In Transit

Return package is in transit to the facility

4

Delivered

Return package delivered to MasonHub facility

5

Received

Return items received and processed into inventory

6

Undeliverable

Return package could not be delivered (terminal status)

​
Return Types

​
Batch Queries

You can query multiple RMAs in a single request using arrays:

# Query by multiple RMA IDs
GET /rmas?id=vf79fyn5-ec61-7892-ae7b-57a173b68133&id=550e8400-e29b-41d4-a716-446655440000

# Query by date range and status
GET /rmas?status=received&sdt=2018-12-01T00:00:00Z&edt=2018-12-31T23:59:59Z

Maximum 30 identifiers per batch request for the id parameter. Exceeding this limit will result in a 400 error.

​
Performance Tips

Use Date Ranges

Filter by sdt and edt to narrow down results instead of retrieving all RMAs.

Filter by Status

Use the status parameter to retrieve only RMAs in specific states.

Summary Lists

Use list_type=summary when you only need basic RMA information.

Appropriate Limits

Use reasonable limit values to avoid timeouts on large datasets.

​
Return Label Access

Return label URLs require API authentication and contain customer personal information. Labels are time-limited for security.

To access a return label PDF:

curl -X GET "https://app.masonhub.co/{account}/api/v1/return-labels/demo1234.pdf" \
  -H "Authorization: Bearer your_jwt_token"