Returns v1

Saks marketplace returns v1 functionality is scheduled to be deprecated on September 30, 2027. New development should follow our returns v2 guidereturns v2 guide instead.

Customer Returns

Direct to Vendor Returns Presentation Deck

https://docs.google.com/presentation/d/1yULPM_26z2DtfmTsP1ygSBMzc4fb6AVYXUOuO3j8fuU/present

API Reference

ℹ️ Reference the API developer portal for implementation details:

https://developer.mirakl.com/content/product/mmp/rest/seller/openapi3

Customer Returns via Direct Mail

A customer can request a return from their saks.com account or by contacting our customer service team. They will be provided with a postage paid return label and instructed to ship the item back directly to you. You will QC and either accept or reject the return. If accepted, Saks will issue the refund to the customer. If rejected, you will return the item back to the customer.

The flow of managing returns is as follows:

You retrieve orders with open returns by calling API OR11

You acknowledge the return once you've captured it in your system by calling API OR31

When you receive the physical return, you need to accept or reject the return

A. If you accept, call API OR28 B. If you reject, call API OR31

Step 1: Retrieve Orders with Returns (API OR11)

See https://developer.mirakl.com/content/product/mmp/rest/seller/openapi3/orders/or11

When a customer initiates a return request, we create an incident on that order. To retrieve orders with open incidents, call API OR11 and set the param has_incident = true

When you receive the response, you should iterate through each order in the orders array and filter on the orders with the following attribute values:

orders.order_lines.order_line_additional_fields.hasnewreturn != false

Explanation: Every time you acknowledge a new return (in the next step), you will set this attribute to false. This filter ensures you're receiving a return that you have not yet seen. When a new return is opened on an order, Saks will set this attribute to 'true'.

orders.order_lines.order_line_state_reason_code = "INCIDENT_OPEN_RETURN_TO_VENDOR"

Explanation: This reason code means the item is being returned directly to you for you to either accept or reject.

You'll find these return-specific attributes in the response at orders.order_lines.order_line_additional_fields: - returnedqty [string] - returnreason [string] - returnorderno [string] (this is the Saks RMA) - returntrackingno [string] - returntrackingurl [string] - hasnewreturn [boolean]

In the event that a return has multiple quantities spanning multiple RMAs, these values will be in a comma separated list. Example:

{
  "order_line_additional_fields": [
    {
      "code": "returnedqty",
      "type": "STRING",
      "value": "2,1"
    },
    {
      "code": "returnorderno",
      "type": "STRING",
      "value": "6000002869-1,6000002869-2"
    },
    {
      "code": "returntrackingno",
      "type": "STRING",
      "value": "270072104823,270072104824"
    },
    {
      "code": "returntrackingurl",
      "type": "STRING",
      "value": "http://narvar.com?t=yxz,http://narvar.com?t=hkd"
    },
    {
      "code": "hasnewreturn",
      "type": "BOOLEAN",
      "value": "true"
    }
  ]
}

Step 2: Acknowledge Return (API OR31)

See https://developer.mirakl.com/content/product/mmp/rest/seller/openapi3/orders/or31

Once you capture the return data in your system, you should acknowledge it in Mirakl by setting the 'hasnewreturn' attribute to false. Therefore, subsequent calls to OR11 (above) will allow you to filter out these orders that have already been captured by you. Saks will update this attribute to 'true' if a new return is opened for an order.

To acknowledge the return, use OR31 to set the custom line item attribute ‘hasnewreturn’ = false at order_lines.order_line_additional_fields. Example:

{
 "order_lines": [
   {
     "order_line_additional_fields": [
       {
         "code": "hasnewreturn",
         "value": "false"
       }
     ],
     "order_line_id": "000000000-0000000-A-1"
   }
 ]
}

Step 3A: Accept Return (API OR28)

See https://developer.mirakl.com/content/product/mmp/rest/seller/openapi3/orders/or28

When you receive the return at your DC, you need to let us know that you accept the return in it's condition so we can issue the refund to the customer. At this point the incident will be closed. Set the following attributes, which can be retrieved using OR11:

Field Name	Description	Type	Required
amount	The amount to be refunded excluding taxes. This is usually the unit price for the line item multiplied by the quantity. Note that partial refunds for a single item are not supported by Saks and any such requests will generate an error.	Decimal	Y
order_line_id	The identifier of the order line that must be refunded.	String	Y
quantity	The quantity of products to refund.	Integer	Y
reason_code	For direct RTV use REFUND_ACCEPTED_BY_VENDOR	String	Y
shipping_amount	Always set to 0. This field is required however, Saks does not currently refund shipping costs to customers.	Decimal	Y
shipping_taxes	Always set amount to 0. Use code TAX.	Object	Y
taxes	The prorated tax amount the customer paid for the items refunded. Use code TAX. To calculate the correct tax amount to refund, you need to consider any amounts already refunded, otherwise you may run into a rounding issue when Mirakl validates the amount you provide. The formula to calculate the item tax amount to refund: (Original Order Tax Amount - Total Tax Amount Already Refunded) / Total Number of Returnable Units * Number of Units Returned Original Order Tax Amount can be found in the API OR11 response @ orders[].order_lines[].taxes[].amount, where orders[].order_lines[].taxes[].code = "TAX" Total Tax Amount Already Refunded can be found in the API OR11 response by calculating the sum of all amounts @ orders[].order_lines[].refunds[].taxes[].amount, where orders[].order_lines[].refunds[].taxes[].code = "TAX" Total Number of Returnable Units can be found in the API OR11 response by calculating the sum of all units ordered @ orders[].order_lines[].quantity and subtracting the sum of units already returned @ orders[].order_lines[].refunds[].quantity, where orders[].order_lines[].refunds[].refund_state = "REFUNDED" Number of Units Returned is the actual number of units you received back and should match the specified quantity in this request noted above.	Object	N

Example:

{
  "refunds": [
    {
      "order_line_id": "000000000-0000000-A-1",
      "amount": 100.00,
      "quantity": 1,
      "taxes": [
        {
          "amount": 5.00,
          "code": "TAX"
        }
      ],
      "currency_iso_code": "USD",
      "excluded_from_shipment": false,
      "reason_code": "REFUND_ACCEPTED_BY_VENDOR",
      "shipping_amount": 0,
      "shipping_taxes": [
        {
          "amount": 0,
          "code": "TAX"
        }
      ]
    }
  ]
}

Add Your Own RMA

If you want to add your own RMA # for reconciliation, you can use API OR31 to set the custom order line field 'vendorrma' to your RMA # and 'vendorrmacreationdate' for the creation date (ISO 8601 format), which will be returned in subsequent OR11 calls.

Example:

{
  "order_lines": [
    {
      "order_line_additional_fields": [
        {
          "code": "vendorrma",
          "type": "STRING",
          "value": "12345"
        },
        {
          "code": "vendorrmacreationdate",
          "type": "STRING",
          "value": "2025-01-01"
        }
      ],
      "order_line_id": "000000000-0000000-A-1"
    }
  ]
}

Step 3B: Reject Return (API OR31)

See https://developer.mirakl.com/content/product/mmp/rest/seller/openapi3/orders/or31

If, instead of accepting the return, you need to reject the return due to the wrong item being returned, a quality issue, or any other reason, you need to let us know about the rejection. At this point the incident will be closed.

Field Name	Description	Type	Required
order_line_id	The identifier of the order line that must be refunded.	String	Y
vendorrefundrejectionqty	The quantity of products to reject. When multiple partial quantity returns exist, you must append additional quantities separated by a comma.	String	Y
vendorrefundrejectionreason	The reason for the rejection. See a list of valid reason codes below. When multiple partial quantity returns exist, you must append additional reasons separated by a comma.	String	Y
vendorrefundrejectionnotes	Any note about the rejection or item condition for your reference. When multiple partial quantity returns exist, you must append additional notes separated by a comma.	String	N
vendorrefundrejectiontrackingurl	The tracking URL of rejected return that is sent back to the customer. Multiple tracking URLs are comma separated. When multiple partial quantity returns exist, you must append additional URLs separated by a comma.	String	N

Example:

{
    "order_lines": [
    {
        "order_line_id": "000000000-0000000-A-1",
        "order_line_additional_fields": [
            {
            "code": "vendorrefundrejectionqty",
            "value": "2"
            },
            {
            "code": "vendorrefundrejectionreason",
            "value": ["DAMAGED_AFTER_PURCHASE"]
            },
            {
            "code": "vendorrefundrejectionnotes",
            "value": ["Item was torn"]
            },
            {
            "code": "vendorrefundrejectiontrackingurl",
            "value": ["https://www.fedex.com/tracking?ID=123"]
            }
        ]
    }
  ]
}

When multiple rejections are made, you must include the previous values and append new rejection values separated by a comma:

{
    "order_lines": [
    {
        "order_line_id": "000000000-0000000-A-1",
        "order_line_additional_fields": [
            {
            "code": "vendorrefundrejectionqty",
            "value": "2,1"
            },
            {
            "code": "vendorrefundrejectionreason",
            "value": ["DAMAGED_AFTER_PURCHASE","MISSING_ORIGINAL_TAGS"]
            },
            {
            "code": "vendorrefundrejectionnotes",
            "value": ["Item was torn","Tags were cut off"]
            },
            {
            "code": "vendorrefundrejectiontrackingurl",
            "value": ["https://www.fedex.com/tracking?ID=123","https://www.fedex.com/tracking?ID=456"]
            }
        ]
    }
  ]
}

Customer Returns via Saks Store/DC

When a customer returns an item to a Saks store or DC, retrieving these returns is slightly different than direct mail returns. In addition, since Saks accepts returns made in store or to our DC, there is no action on your part to accept or reject these returns.

Via Saks Store

A customer can return to any Saks store. The Saks associate QCs & accepts the return, issues a refund and returns the item directly to you.

Via Saks DC

In the event a customer opens a return for 2 or more items that were sourced from different locations (i.e. a customer orders 3 items, one being shipped from your DC, one from a different vendor, and one from Saks DC), instead of issuing 3 return labels to the customer, Saks will issue a single return label and the return will be received to the Saks DC. When the return is received, Saks issues a refund, splits up the returned items based on the destination, and return your item to you.

Step 1: Retrieve Orders with Returns (API OR11)

See https://developer.mirakl.com/content/product/mmp/rest/seller/openapi3/orders/or11

API Request Frequency It is recommeded to make this call throughout the day, or at a minimum once a day.

Retrieving Orders with Returns Mirakl does not have an option to only request orders with returns, therefore you'll need to retrieve orders by date range to reduce the number of orders returned, then iterate through the orders[] array in the response, and filter on the following attributes client-side.

To retrieve orders with Saks Store/DC returns, use API OR11 and set the following parameters to narrow down your resultset:

start_update_date (the date the order was last updated - in this case, when the refund was processed). If retrieving orders throughout the day, you should set this to yesterday's date.

end_update_date (optional)

Example: https://saksus2-dev.mirakl.net/api/orders?start_update_date=2025-04-10&end_update_date=2025-04-11

Iterate through each order in the response and filter on these attribute values to obtain the orders needed:

orders.order_lines.order_line_additional_fields.hasnewreturn != false

Explanation: Every time you acknowledge a new return (in the next step), you will set this attribute to false. This filter ensures you're receiving a return that you have not yet seen. When a customer opens a new return, Saks will set this attribute to 'true'.

orders.order_lines.refunds.reason_code = "REFUND_ACCEPTED_BY_SAKS"

Explanation: This reason code means Saks has accepted the return and issued a refund.

orders.order_lines.refunds.refund_state = "REFUNDED"

Explanation: This refund state means the refund has been processed.

With the filtered orders, you'll find these return-specific attributes you can utililze at orders.order_lines.order_line_additional_fields:

returnedqty [string]

returnreason [string]

returnorderno [string] (this is the Saks RMA)

Return Tracking Info Returns via Saks store/DC do not currently include the return tracking number or return tracking URL in the API OR11 response payload. Instead, the return tracking number (when available) can be included in our daily returns report that is shared with you. This is planned as a future enhancement.

In the event that a return has multiple quantities spanning multiple RMAs, these values will be in a comma separated list. Example:

{
  "order_line_additional_fields": [
    {
      "code": "returnedqty",
      "type": "STRING",
      "value": "2,1"
    },
    {
      "code": "returnorderno",
      "type": "STRING",
      "value": "6000002869-1,6000002869-2"
    },
    {
      "code": "hasnewreturn",
      "type": "BOOLEAN",
      "value": "true"
    }
  ]
}

Step 2: Acknowledge Return (API OR31)

Once you've acknowledged the return in your system, set the orders.order_lines.order_line_additional_fields.hasnewreturn attribute to 'false'. This will allow you to filter out these orders/returns you've already processed the next time you retrieve orders (from Step 1).

Example:

{
 "order_lines": [
   {
     "order_line_additional_fields": [
       {
         "code": "hasnewreturn",
         "value": "false"
       }
     ],
     "order_line_id": "000000000-0000000-A-1"
   }
 ]
}

Return to Sender (RTS)

Currently, when a Saks order is sent back to you because it failed to deliver to the customer, you will need to contact our Partner Success team so that customers are refunded for this item and commissions are correctly returned to you.

An enhancement is planned to allow you to approve RTS refunds via API, eliminating the manual process today. There is no ETA for this enhancement.

Miscellaneous

Bulk Order Exports

In lieu of using API OR11 to retrieve returns, you can use OR13/OR14/OR15 to export your returns, which is recommended for larger payloads.

Return Reasons

Below are the return reasons the customer can choose:

WRONG_SIZE_COLOR
DISSATISFIED_QUALITY
DIFFERENT_PICTURE
WRONG_ITEM_DELIVERED
ITEM_DAMAGED
DAMAGED_MISSINGPARTS
DAMAGED_PACKAGING
NOT_AS_NEW
ITEM_SIZE_SMALL
ITEM_SIZE_LARGE
ITEM_DID_NOT_SUIT
MULTIPLE_KEPT_SMALLER
MULTIPLE_KEPT_LARGER
MULTIPLE_COLORS
MULTIPLE_STYLES
MULTIPLE_NONE_WORKED
TOO_EXPENSIVE
ARRIVE_LATE
DIFFERENT_RETAILER
NOT_LONGER_NEEDED

The return reason is provided on the order via API OR11 at orders.order_lines.order_line_additional_fields.returnreason.

Example:

{
  "orders": [
    {
      "order_lines": [
        {
          "order_line_additional_fields": [
            {
              "code": "returnreason",
              "type": "STRING",
              "value": "ITEM_DID_NOT_SUIT"
            }
          ]
        }
      ]
    }
  ]
}

Rejection Reasons

Code	Explanation
CUSTOMER_CLAIMED_INVALID_VENDOR_DEFECT	Customer is saying the item being returned was damaged by the brand / is defective but the brand knows this is not the case because the item was quality checked before shipment and the brand confirmed there were no issues with the product.
CUSTOMER_REQUESTED_TO_KEEP_RETURNED_ITEM	Customer mailed the return back but then had a change of heart and wants to keep the item. This is a very rare case and one we usually cannot operatilize for marketplace returns. When this happens for marketplace, we tell brands to process the return/refund and if the customer wants the item, they need to place another order.
DAMAGED_AFTER_PURCHASE	product passed brands QC during fulfillment and when the return came back to the brand DC, there were damages to the product (ripped clothing, scratched shoe/bag, stains, etc.) that were not on the product prior to fulfillment by the brand.
FOOD_BEVERAGE_FINAL_SALE	Returned item is food which is final sale and is not returnable. If the brand does not sell food items, this rejection reason code would not be used.
MARKED_FINAL_SALE	Item sold was a final sale item so it is not returnable. If a customer purchases multiple items and 1 is final sale, we block the customers ability to return the final sale in Narvar, but there is no way to stop the customer from initiating a return for a non final sale item but they ship back the final sale item. In this scenario, the brand would reject the item using this reason code.
MISSING_ORIGINAL_TAGS	Our return policy states returned merchandise must be factory fresh, never worn and contains all original tags. If the customer is returning an item where the original tags were removed, you would reject using this reason code.
MISSING_PROOF_OF_PURCHASE	If the returned item was never purchased by the customer, you would use this code. This would require communication between the brand and Saks MP Ops as the item in question could belong to another order. If after Saks MP Ops investigates and finds the item was never purchased, Saks MP Ops would direct the brand to use this rejection reason.
NOT_AUTHENTIC_AND_NOT_SOLD_AT_SAKS	Returned item is a counterfeit brand item.
PERSONALIZED_FINAL_SALE	Item was personalized ex. had the customers initials embossed into the product making it not resellable or returnable.
REMOVED_SECURITY_SENSOR	Similar rejection reason as MISSING_ORIGINAL_TAGS and can be used interchangeably.
RETURN_BOX_IS_EMPTY	Fraudulent return where the customer shipped an empty box or included non merchandise items (bags of flour) so the package registered a weight to make it look like the actual merchandise was in the carton. This reason code allows the Saks fraud team to reject any RNR claim the customer makes.
RETURN_DOES_NOT_MATCH_PURCHASE	If the brand sells an item year over year, the customer purchased one item last year and the same item thsi year and then tries to return the year old item for a full refund.
RETURN_WINDOW_EXPIRED	Customer initiated the return within the return window but then held the item for an extended period of time before shipping back to the brand.
RETURNING_CUSTOMERS_PERSONAL_ITEMS	Returned item is not a counterfeit brand item but is instead another brand’s item and the customer is attempting a fraudulent return. This would require communication between the brand and Saks MP Ops as the item in question could have been ordered by the customer and the customer shipped the return back to the wrong location. If after Saks MP Ops investigates and finds the item was never purchased, Saks MP Ops would direct the brand to use this rejection reason. If Saks MP Ops confirms the customer did purchase this item, Saks MP ops would provide the brand with a shipping label to get the item back to the Saks DC and no rejection would be provided by the brand.
SET_MISSING_PIECES	Returned product was a set i.e. suit pants and a jacket, handbag with a shoulder strap but the customer only returned part of the set.
VENDOR_REPAIR_NOT_OFFERED	This will be used for marketplace rejections as we do not currently offer the customer the ability to have an item repaired by the brand.
OTHER	If the rejection does not fall into any of the above, use this reason code. If this reason is used, the brand should add rejection notes so Saks knows why this is being rejected.

Return Locations

To find the initial leg of the return, you can check the return location code:

Code	Direct RTV	Label
INCIDENT_OPEN_RETURN_TO_VENDOR	Yes	Customer returned to vendor address
INCIDENT_OPEN_RETURN_TO_DC	No	Customer returned to Saks DC
INCIDENT_OPEN_RETURN_TO_STORE	No	Customer returned to Saks store

The return code is in the API OR11 response at orders.order_lines.order_line_state_reason_code:

{
  "orders": [
    {
      "order_lines": [
        {
          "order_line_state_reason_code": "INCIDENT_OPEN_RETURN_TO_VENDOR",
          "order_line_state_reason_label": "Customer returned to vendor address"
        }
      ]
    }
  ]
}