---
updatedAt: 2026-05-11T18:50:59.000Z
---

# Issue refund

Issue refunds for return orders.

A single request may include multiple return order lines.

Use the Refund Order Lines API for non exception category items, including adjustments where the seller sets a partial refund amount.

Exception category items HAZMAT OTHER and FREIGHT are not eligible for the Marketplace Returns Program.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Returns Management",
    "version": "1.0",
    "description": "Buyers initiate returns on Walmart.com for Marketplace items.\n\nException categories HAZMAT OTHER and FREIGHT are excluded from buyer initiated returns.\n\nFor HAZMAT and OTHER the seller generates the return shipping label and uploads it.\n\nFor instructions and the Returns API JSON schema see the [Returns guide](https://developer.walmart.com/us-marketplace/docs/returns-and-refunds-api-overview)."
  },
  "x-readme": {
    "samples-languages": [
      "shell"
    ],
    "proxy-enabled": false
  },
  "servers": [
    {
      "url": "https://marketplace.walmartapis.com",
      "description": "Production URL"
    },
    {
      "url": "https://sandbox.walmartapis.com",
      "description": "Sandbox URL"
    }
  ],
  "security": [
    {
      "basicScheme": []
    }
  ],
  "paths": {
    "/v3/returns/{returnOrderId}/refund": {
      "post": {
        "tags": [
          "Returns/Refunds"
        ],
        "summary": "Issue refund",
        "description": "Issue refunds for return orders.\n\nA single request may include multiple return order lines.\n\nUse the Refund Order Lines API for non exception category items, including adjustments where the seller sets a partial refund amount.\n\nException category items HAZMAT OTHER and FREIGHT are not eligible for the Marketplace Returns Program.",
        "externalDocs": {
          "description": "View Guide",
          "url": "/doc/us/mp/us-mp-returns/#4438"
        },
        "operationId": "issueRefund",
        "parameters": [
          {
            "name": "returnOrderId",
            "in": "path",
            "description": "Return order identifier also known as RMA number. Use to filter results.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "WM_SEC.ACCESS_TOKEN",
            "description": "The access token retrieved in the Token API call",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM....."
          },
          {
            "in": "header",
            "name": "WM_CONSUMER.CHANNEL.TYPE",
            "description": "A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "WM_QOS.CORRELATION_ID",
            "description": "A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "b3261d2d-028a-4ef7-8602-633c23200af6"
          },
          {
            "in": "header",
            "name": "WM_SVC.NAME",
            "description": "Walmart Service Name",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Walmart Service Name"
          },
          {
            "in": "header",
            "name": "WM_SANDBOX",
            "description": "Include this header to access the Marketplace dynamic sandbox environment.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "v2"
              ]
            },
            "example": "v2"
          }
        ],
        "requestBody": {
          "description": "File fields",
          "content": {
            "application/json": {
              "schema": {
                "required": [
                  "customerOrderId",
                  "refundLines"
                ],
                "type": "object",
                "properties": {
                  "customerOrderId": {
                    "type": "string",
                    "description": "Customer sales order identifier. Use to filter results."
                  },
                  "refundLines": {
                    "type": "array",
                    "description": "List of return order lines to refund.",
                    "items": {
                      "required": [
                        "returnOrderLineNumber"
                      ],
                      "type": "object",
                      "properties": {
                        "returnOrderLineNumber": {
                          "type": "integer",
                          "description": "Line number within the return order. Required when the return order contains multiple lines. If the return order contains a single line and this field is not sent, that line is selected automatically. Omitting a required line number results in a data error.",
                          "format": "int64"
                        },
                        "quantity": {
                          "required": [
                            "measurementValue",
                            "unitOfMeasure"
                          ],
                          "type": "object",
                          "properties": {
                            "unitOfMeasure": {
                              "type": "string",
                              "description": "Unit of measure for the quantity. Examples include EACH or EA."
                            },
                            "measurementValue": {
                              "type": "number",
                              "description": "Numeric value for the quantity in the specified unit of measure.",
                              "format": "double"
                            }
                          },
                          "description": "Quantity to refund on this return line."
                        }
                      },
                      "description": "List of return order lines to refund."
                    }
                  }
                }
              },
              "example": {
                "customerOrderId": "1535274411287",
                "refundLines": [
                  {
                    "returnOrderLineNumber": 1,
                    "quantity": {
                      "unitOfMeasure": "EA",
                      "measurementValue": 2
                    }
                  }
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "returnOrderId": {
                      "type": "string",
                      "description": "Return order identifier also known as RMA number. Use to filter results."
                    },
                    "customerOrderId": {
                      "type": "string",
                      "description": "Customer sales order identifier. Use to filter results."
                    },
                    "refundLines": {
                      "type": "array",
                      "description": "Array of refund lines",
                      "items": {
                        "required": [
                          "returnOrderLineNumber"
                        ],
                        "type": "object",
                        "properties": {
                          "returnOrderLineNumber": {
                            "type": "integer",
                            "description": "Line number within the return order. Required when the return order contains multiple lines. If the return order contains a single line and this field is not sent, that line is selected automatically. Omitting a required line number results in a data error.",
                            "format": "int64"
                          },
                          "quantity": {
                            "required": [
                              "measurementValue",
                              "unitOfMeasure"
                            ],
                            "type": "object",
                            "properties": {
                              "unitOfMeasure": {
                                "type": "string",
                                "description": "Unit of measure for the quantity. Examples include EACH or EA."
                              },
                              "measurementValue": {
                                "type": "number",
                                "description": "Numeric value for the quantity in the specified unit of measure.",
                                "format": "double"
                              }
                            },
                            "description": "Quantity to refund on this return line."
                          }
                        },
                        "description": "List of return order lines to refund."
                      }
                    }
                  }
                },
                "example": {
                  "returnOrderId": "106152711271982880",
                  "customerOrderId": "1535274411287",
                  "refundLines": [
                    {
                      "returnOrderLineNumber": 1,
                      "quantity": {
                        "unitOfMeasure": "EA",
                        "measurementValue": 2
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
```