Rma Changes (Return Labels)

Wednesday, Mar 6, 2019

API Changes to RMAs (Return Labels)

There have been significant, breaking changes to the RMA endpoints in the API. Please find them detailed below.

Dropped order existance requirement

We have dropped the requirement that an RMA must be placed against an existing order. This enables you to create returns for items which could have been shipped on orders prior to your integration with MasonHub, facilitating the go-live process.

  • For this reason, customer_order_id is no longer a required field in the POST request.

DHL Return Labels

DHL return labels can now be generated upon RMA creation/update. This happens synchronously with the HTTP call, so that we can return back to you a link to the return label PDF as well as the tracking number. The returned URL is a MasonHub link which requires normal API authentication in order to access. This security measure was taken in order to prevent return labels (and subsequently personal customer data) from being exposed publically.

In order to create the return label, a new field can be passed in the request body:

"generate_return_label": true

this will ensure that a return label is created with the request. The default value is true, so if this field is left out a return label will be created.

When issuing a request which will create a return label, the customer shipping address is required in the request body. Package ID can also be left out, as this will take the value of the generated return tracking number. See an example below, or refer to the API docs for more info.

"customer_address_name": "John Smith",
"customer_address_street_line_one": "100 First Ave",
"customer_address_street_line_two": "Apt 16",
"customer_address_postal_code": "10016",
"customer_address_city": "New York",
"customer_address_state": "NY",
"customer_address_country_code": "US"

Upon success, the HTTP response body will contain an ‘additional_data’ section containing the link to the generated return label PDF as well as the return tracking number.

    "records_submitted": 1,
    "records_processed": 1,
    "records_failed": 0,
    "records_succeeded": 1,
    "results": [
            "customer_identifier": "CARBON422",
            "status": "success",
            "uri": "https://app.masonhub.co/demo_account/api/v1/rmas?cid=DEMO123",
            "additional_data": {
                "return_label_url": "https://app.masonhub.co/demo_account/api/v1/return-labels/demo1234.pdf",
                "return_tracking_number": "9302020514103629166400"

See the full RMA Creation spec here.

Unexpected line items on receipt

not_on_original_rma has been added to the RMA line item model. In the case that there is an unexpected item (not part of original RMA) received with the others it will be added as a line item to the RMA, and not_on_original_rma will be set to true to denote that this item was not on the original RMA. This process is conditional on the case that the received sku already exists in our systems.

See the full RMA spec here.

Summary of changes

  • generate_return_label now an accepted field on the RMA creation (POST) endpoint to specify to generate a return label.
  • Customer Address is now required to create an RMA with a generated return label.
  • Package ID is no longer a required field on RMA creation with a generated return label.
  • not_on_original_rma is now returned with each RMA line item
  • additional_data JSON array now returned with RMA response when a return label is generated
    • Includes return_label_url with a link to the downloadable PDF (requires authentication)
    • Includes tracking_number with the generated DHL tracking number.

Don’t hesitate to reach out to Chris, Andy, or Christopher with any questions.