RMAs Create and List In Sandbox

Wednesday, Dec 26, 2018

RMA Creation and List is now live in sandbox

You can now make POST and GET requests to https://sandbox.masonhub.co/account_name/api/v1/rmas. The full API documentation for RMAs is located here: https://docs.masonhub.co/api/v1#tag/Returns

RMAs, as you may well know, represent returns that are expected to be sent from customers to the distribution center for receiving, processing, and turnaround. The model for RMAs is fairly straightforward and self-explanatory, but there are a couple things to keep in mind:

  • You cannot create an RMA Line Item for an order that does not exist. The API will reject the RMA when it tries to validate it, and advise as such on the response to your request.
  • You cannot create an RMA Line Item for a Sku that was not on the order specified in the line item. Again, the API validation will let you know this is invalid.
  • You cannot create RMA Line Items for higher quantities of Skus than were on the order specified. For instance, if Order “123” had 2 units of Sku “A”, your RMA cannot be created for 3 units of Sku “A” against Order “123”
  • You can have multiple orders referenced on the same RMA. Order references exist on the line item level. So, if you want to allow your customers to create single RMAs across several orders, be our guest. We’ll still make sure the skus and quantities align as per the above conditions.

An Example

To Create a new RMA, issue a POST to https://sandbox.masonhub.co/account_name/api/v1/rmas endpoint using your client name. The body of the POST should look something like this:

[
  {
    "customer_identifier": "rma123",
    "package_id": "1z324897234nferg45",
    "return_type": "rma_submitted_by_customer",
    "customer_instructions": "Dry clean",
    "line_items": [
      {
        "customer_order_id": "54321",
        "customer_sku_id": "shirts872340",
        "quantity": 1,
        "return_reason_code": "fit",
        "return_notes": "Didn't fit",
        "return_inventory_status": "qc"
      }
    ]
  },
  {
    "customer_identifier": "rma999",
    "package_id": "1z3248972302urik586",
    "return_type": "rma_submitted_by_customer",
    "line_items": [
      {
        "customer_order_id": "54321",
        "customer_sku_id": "shirts872340",
        "quantity": 1,
        "return_reason_code": "damage",
        "return_notes": "Item torn",
        "return_inventory_status": "damaged"
      }
    ]
  }
]

After a successful response from the MasonHub API, you would now be able to retrieve the order information by submitted a GET request to https://sandbox.masonhub.co/account_name/api/v1/rmas Remember, if you want to look for a specific RMA, you can enter the customer_identifier that you submitted on the RMA POST, in the ‘cid’ url query parameter, like so: https://sandbox.masonhub.co/account_name/api/v1/rmas?cid=rma123 You’ll get a response that looks something like this:

{
    "search_criteria": {
        "cids": [
            "rma123"
        ],
        "status": "all",
        "sdt": null,
        "edt": null
    },
    "limit": 30,
    "offset": 0,
    "list_type": "detail",
    "include_counts": false,
    "data": [
        {
            "id": "efe22627-e17e-4a61-85bd-e36172a2d24d",
            "customer_identifier": "rma123",
            "package_id": "1z324897234nferg45",
            "return_type": "rma_submitted_by_customer",
            "status": "open",
            "processed_at": null,
            "notes": null,
            "customer_instructions": "Dry clean",
            "line_items": [
                {
                    "customer_order_id": "54321",
                    "customer_sku_id": "shirts872340",
                    "quantity": 1,
                    "return_reason_code": "fit",
                    "return_notes": "Didn't fit",
                    "return_inventory_status": "qc"
                }
            ],
            "version": 1,
            "created_at": "2018-12-24T16:17:10.800553Z",
            "updated_at": "2018-12-24T16:17:10.800554Z",
            "deleted_at": null
        }
    ]
}

That’s how you can get started creating and retrieving your RMA information from the API. Very soon PUT and DELETE will be released for RMAs so you can make updates after creation. And more importantly, an endpoint in our Data Factory so that you can trigger some RMA events, such as receipts on existing RMAs, or creation of blind RMAs.


As always, don’t be afraid to reach out to Chris or Andy with any questions.