---
updatedAt: 2026-05-07T15:23:22.000Z
---

# Simulate a return

Simulates return creation for a given customer order and line item.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Simulations API",
    "description": "API for managing simulations of seller items and orders in the Marketplace dynamic sandbox.",
    "version": "1.0.0",
    "contact": {
      "name": "Marketplace API Support"
    }
  },
  "x-readme": {
    "samples-languages": [
      "shell"
    ]
  },
  "servers": [
    {
      "url": "https://sandbox.walmartapis.com/v1",
      "description": "Sandbox URL"
    }
  ],
  "tags": [
    {
      "name": "Simulations",
      "description": "Simulate items and orders in the Marketplace dynamic sandbox."
    }
  ],
  "paths": {
    "/simulations/returns": {
      "post": {
        "summary": "Simulate a return",
        "operationId": "simulateReturn",
        "description": "Simulates return creation for a given customer order and line item.",
        "tags": [
          "Simulations"
        ],
        "parameters": [
          {
            "name": "WM_SANDBOX",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "v2"
              ]
            },
            "description": "Include this header to access the Marketplace dynamic sandbox environment.",
            "example": "v2"
          },
          {
            "name": "WM_SEC.ACCESS_TOKEN",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The access token retrieved in the Token API call.",
            "example": "ACCESS_TOKEN_EXAMPLE.."
          },
          {
            "name": "WM_SVC.NAME",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Specifies the name of the Walmart service being called.",
            "example": "Walmart Service Name"
          },
          {
            "name": "WM_SVC.VERSION",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Service Version to access the API based on the version."
          },
          {
            "in": "header",
            "name": "Accept",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Specifies the data type expected in a response sent from the server.\n\nValid values are:\n  \n  | Value | Meaning |\n  | --- | --- |\n  | application/json | JSON format for data returned in response. |\n  \n",
            "example": "application/json"
          },
          {
            "in": "header",
            "name": "Content-Type",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Specifies the format of request and response body data.\n\n\nValid values are:\n  \n  | Value | Meaning |\n  | --- | --- |\n  | application/json | JSON format for data returned in response. |\n  \n",
            "example": "application/json"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "purchaseOrderId",
                  "lineNumber",
                  "qty",
                  "returnReason"
                ],
                "properties": {
                  "purchaseOrderId": {
                    "type": "string",
                    "example": "1775020042249",
                    "description": "Purchase order identifier for the order being used in the return simulation."
                  },
                  "lineNumber": {
                    "type": "integer",
                    "example": 1,
                    "description": "Line number of the item within the order to return."
                  },
                  "qty": {
                    "type": "integer",
                    "example": 1,
                    "description": "Quantity of units being returned for the specified order line."
                  },
                  "returnReason": {
                    "$ref": "#/components/schemas/ReturnReason"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Return simulation successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReturnOrder"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "array",
                      "description": "Array of objects containing error information.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "description": "Error code of the response.",
                            "example": "INVALID_REQUEST_HEADER.GMP_GATEWAY_API"
                          },
                          "field": {
                            "type": "string",
                            "description": "Specifies which field contains the error.",
                            "example": "WM_SVC.NAME"
                          },
                          "description": {
                            "type": "string",
                            "description": "Description of the error.",
                            "example": "WM_SVC.NAME set null or invalid."
                          },
                          "info": {
                            "type": "string",
                            "description": "Information about the error.",
                            "example": "One or more request headers are invalid."
                          },
                          "severity": {
                            "type": "string",
                            "description": "Severity of the error.",
                            "example": "ERROR"
                          },
                          "category": {
                            "type": "string",
                            "description": "Category of the error.",
                            "example": "DATA"
                          },
                          "causes": {
                            "type": "array",
                            "description": "List of error causes",
                            "items": {
                              "type": "string",
                              "description": "Cause of the error."
                            }
                          },
                          "errorIdentifiers": {
                            "type": "object",
                            "description": "Error identifiers associated with the error."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "array",
                      "description": "Array of objects containing error information.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "description": "Error code of the response.",
                            "example": "UNAUTHORIZED.GMP_GATEWAY_API"
                          },
                          "field": {
                            "type": "string",
                            "description": "Specifies which field contains the error.",
                            "example": "UNAUTHORIZED"
                          },
                          "description": {
                            "type": "string",
                            "description": "Description of the error.",
                            "example": "Unauthorized"
                          },
                          "info": {
                            "type": "string",
                            "description": "Information about the error.",
                            "example": "Unauthorized token or incorrect authorization header.\n\nVerify that you are using the correct format: `Authorization: Basic Base64Encode(clientId:clientSecret)`.\n\nFor more information, refer to https://developer.walmart.com/suppliers/docs/authentication-management.\n"
                          },
                          "severity": {
                            "type": "string",
                            "description": "Severity of the error.",
                            "example": "ERROR"
                          },
                          "category": {
                            "type": "string",
                            "description": "Category of the error.",
                            "example": "DATA"
                          },
                          "causes": {
                            "type": "array",
                            "description": "List of error causes.",
                            "items": {
                              "type": "string",
                              "description": "Cause of the error."
                            }
                          },
                          "errorIdentifiers": {
                            "type": "object",
                            "description": "Error identifiers associated with the error."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "description": "Unique identifier for the type of error.\n\nHelps in quickly recognizing and categorizing the specific issue.\n",
                      "example": "SYSTEM_ERROR.GMP_ITEM_QUERY_API"
                    },
                    "description": {
                      "type": "string",
                      "description": "Detailed message explaining what caused the error.\n\nProvides more context about the issue.\n",
                      "example": "System encountered some internal error."
                    },
                    "info": {
                      "type": "string",
                      "description": "Brief summary of the error, often used for a quick understanding of the issue.",
                      "example": "One or more mandatory request parameters are missing."
                    },
                    "severity": {
                      "type": "string",
                      "description": "Indicates the severity of the error.\n\nCommon values include ERROR, WARNING, or INFO.\n",
                      "example": "ERROR"
                    },
                    "category": {
                      "type": "string",
                      "description": "Classifies the error into a specific group or type, which helps in organizing and managing different types of issues.",
                      "example": "DATA"
                    },
                    "causes": {
                      "type": "array",
                      "description": "Array containing additional details or sub-errors that contributed to the main error.",
                      "example": [],
                      "items": {
                        "type": "string",
                        "description": "Causes of the error."
                      }
                    },
                    "errorIdentifiers": {
                      "type": "object",
                      "description": "Includes additional identifiers or metadata that provides more context about the error.",
                      "example": {}
                    },
                    "field": {
                      "type": "string",
                      "description": "Specifies the field or parameter that caused the error, pinpointing exactly where the issue occurred.",
                      "example": "Name is null"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ReturnOrder": {
        "type": "object",
        "description": "The created return order.",
        "properties": {
          "returnOrderId": {
            "type": "string",
            "description": "Unique identifier for the return order."
          },
          "customerOrderId": {
            "type": "string",
            "description": "Customer-facing order ID."
          },
          "customerEmailId": {
            "type": "string",
            "description": "Customer email address."
          },
          "customerName": {
            "$ref": "#/components/schemas/CustomerName"
          },
          "purchaseOrderId": {
            "type": "string",
            "description": "Associated purchase order ID."
          },
          "refundMode": {
            "type": "string",
            "description": "Mode of refund."
          },
          "returnOrderDate": {
            "type": "integer",
            "format": "int64",
            "description": "Return order creation date (epoch millis)."
          },
          "returnType": {
            "type": "string",
            "description": "Type of return.",
            "example": "REPLACEMENT"
          },
          "replacementCustomerOrderId": {
            "type": "string",
            "description": "Customer order ID for the replacement order."
          },
          "returnByDate": {
            "type": "string",
            "description": "Deadline to complete the return."
          },
          "totalRefundAmount": {
            "$ref": "#/components/schemas/CurrencyAmount"
          },
          "returnLineGroups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReturnLineGroup"
            }
          },
          "returnOrderLines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReturnOrderLine"
            }
          },
          "returnChannel": {
            "$ref": "#/components/schemas/ReturnChannel"
          }
        }
      },
      "ReturnOrderLine": {
        "type": "object",
        "properties": {
          "returnOrderLineNumber": {
            "type": "integer",
            "description": "Return order line number."
          },
          "salesOrderLineNumber": {
            "type": "integer",
            "description": "Original sales order line number"
          },
          "returnReason": {
            "$ref": "#/components/schemas/ReturnReason"
          },
          "returnDescription": {
            "type": "string",
            "description": "Additional return description."
          },
          "purchaseOrderId": {
            "type": "string",
            "description": "Associated purchase order ID."
          },
          "sellerOrderId": {
            "type": "string",
            "description": "Seller's custom order identifier."
          },
          "purchaseOrderLineNumber": {
            "type": "integer",
            "description": "Purchase order line number."
          },
          "isReturnForException": {
            "type": "boolean",
            "description": "Whether this is an exception return."
          },
          "exceptionItemType": {
            "type": "string",
            "description": "Type of exception item."
          },
          "rechargeReason": {
            "type": "string",
            "description": "Reason for recharge."
          },
          "returnCancellationReason": {
            "type": "string",
            "description": "Reason for return cancellation."
          },
          "item": {
            "$ref": "#/components/schemas/Item"
          },
          "charges": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Charge"
            }
          },
          "unitPrice": {
            "$ref": "#/components/schemas/CurrencyAmount"
          },
          "chargeTotals": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChargeTotal"
            }
          },
          "currentDeliveryStatus": {
            "type": "string",
            "description": "Current delivery status of the order line."
          },
          "currentRefundStatus": {
            "type": "string",
            "description": "Current refund status."
          },
          "currentTrackingStatuses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CurrentTrackingStatus"
            }
          },
          "refundChannels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RefundChannel"
            }
          },
          "cancellableQty": {
            "type": "integer",
            "description": "Quantity eligible for cancellation."
          },
          "quantity": {
            "$ref": "#/components/schemas/Quantity"
          },
          "returnExpectedFlag": {
            "type": "boolean",
            "description": "Whether physical return of item is expected."
          },
          "isFastReplacement": {
            "type": "boolean",
            "description": "Whether this is a fast replacement return."
          },
          "isKeepIt": {
            "type": "boolean",
            "description": "Whether customer can keep the item."
          },
          "lastItem": {
            "type": "boolean",
            "description": "Whether this is the last item in the return."
          },
          "refundedQty": {
            "type": "integer",
            "description": "Quantity already refunded."
          },
          "rechargeableQty": {
            "type": "integer",
            "description": "Quantity eligible for recharge."
          },
          "refundCoveredBy": {
            "type": "string",
            "description": "Entity covering the refund."
          },
          "returnTrackingDetail": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReturnTrackingDetail"
            }
          },
          "status": {
            "type": "string",
            "description": "Current status of the return line.",
            "example": "INITIATED"
          },
          "statusTime": {
            "type": "string",
            "description": "Timestamp of the current status."
          },
          "itemReturnSettings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ItemReturnSetting"
            }
          }
        }
      },
      "CustomerName": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "Customer first name."
          },
          "lastName": {
            "type": "string",
            "description": "Customer last name."
          }
        }
      },
      "Item": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "description": "Stock Keeping Unit (SKU) identifier assigned to the item."
          },
          "condition": {
            "type": "string",
            "description": "Item condition.",
            "example": "NEW"
          },
          "productName": {
            "type": "string",
            "description": "Name of the product."
          },
          "itemWeight": {
            "$ref": "#/components/schemas/ItemWeight"
          }
        }
      },
      "ItemWeight": {
        "type": "object",
        "properties": {
          "unitOfMeasure": {
            "type": "string",
            "description": "Unit of weight measurement.",
            "example": "LB, OZ, KG, or G"
          },
          "measurementValue": {
            "type": "integer",
            "description": "Weight value in the specified unit.",
            "example": 2
          }
        }
      },
      "Quantity": {
        "type": "object",
        "properties": {
          "unitOfMeasure": {
            "type": "string",
            "description": "Unit of measurement.",
            "example": "EACH"
          },
          "measurementValue": {
            "type": "integer",
            "description": "Quantity value in the specified unit.",
            "example": 1
          }
        }
      },
      "Charge": {
        "type": "object",
        "properties": {
          "chargeCategory": {
            "type": "string",
            "description": "Category of the charge."
          },
          "chargeName": {
            "type": "string",
            "description": "Name of the charge."
          },
          "chargePerUnit": {
            "$ref": "#/components/schemas/CurrencyAmount"
          },
          "isDiscount": {
            "type": "boolean",
            "description": "Whether this charge is a discount."
          },
          "isBillable": {
            "type": "boolean",
            "description": "Whether this charge is billable."
          },
          "tax": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tax"
            }
          },
          "excessCharge": {
            "$ref": "#/components/schemas/CurrencyAmount"
          },
          "references": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Reference"
            }
          }
        }
      },
      "CurrencyAmount": {
        "type": "object",
        "properties": {
          "currencyAmount": {
            "type": "number",
            "format": "double",
            "description": "Monetary amount."
          },
          "currencyUnit": {
            "type": "string",
            "description": "Currency code.",
            "example": "USD"
          }
        }
      },
      "Tax": {
        "type": "object",
        "properties": {
          "taxName": {
            "type": "string",
            "description": "Name of the tax."
          },
          "excessTax": {
            "$ref": "#/components/schemas/CurrencyAmount"
          },
          "taxPerUnit": {
            "$ref": "#/components/schemas/CurrencyAmount"
          }
        }
      },
      "ChargeTotal": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the charge total."
          },
          "value": {
            "$ref": "#/components/schemas/CurrencyAmount"
          }
        }
      },
      "CurrentTrackingStatus": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "Tracking status.",
            "example": "INITIATED"
          },
          "statusTime": {
            "type": "string",
            "description": "Timestamp of status."
          },
          "currentRefundStatus": {
            "type": "string",
            "description": "Current refund status."
          },
          "quantity": {
            "$ref": "#/components/schemas/Quantity"
          }
        }
      },
      "ReturnTrackingDetail": {
        "type": "object",
        "properties": {
          "sequenceNo": {
            "type": "integer",
            "description": "Sequence number of the tracking event."
          },
          "eventTag": {
            "type": "string",
            "description": "Event tag.",
            "example": "RETURN_INITIATED"
          },
          "eventDescription": {
            "type": "string",
            "description": "Human-readable event description."
          },
          "eventTime": {
            "type": "string",
            "description": "Timestamp of the event."
          },
          "references": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Reference"
            }
          }
        }
      },
      "Reference": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Reference name."
          },
          "value": {
            "type": "string",
            "description": "Reference value."
          }
        }
      },
      "ReturnLineGroup": {
        "type": "object",
        "properties": {
          "groupNo": {
            "type": "integer",
            "description": "Group number."
          },
          "returnLines": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "Return line within the group."
            }
          },
          "labels": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "Labels for the return group."
            }
          },
          "returnExpectedFlag": {
            "type": "boolean",
            "description": "Whether physical return is expected for this group."
          }
        }
      },
      "ReturnChannel": {
        "type": "object",
        "properties": {
          "channelName": {
            "type": "string",
            "description": "Name of the return channel."
          }
        }
      },
      "RefundChannel": {
        "type": "object",
        "properties": {
          "refundChannelName": {
            "type": "string",
            "description": "Name of the refund channel."
          },
          "quantity": {
            "$ref": "#/components/schemas/Quantity"
          }
        }
      },
      "ItemReturnSetting": {
        "type": "object",
        "description": "Item return settings (reserved for future use)."
      },
      "ReturnReason": {
        "type": "string",
        "description": "Reason for initiating the return.",
        "enum": [
          "DEFECTIVE",
          "WRONG_ITEM",
          "BUYER_CHANGED_MIND",
          "SELLER_WRONG_ITEM_SHIPPED",
          "CANCEL_ORDER",
          "MISSING_PARTS",
          "ARRIVED_DAMAGED",
          "NOT_AS_DESCRIBED",
          "ITEM_NOT_WORKING",
          "ORDERED_WRONG_ITEM"
        ]
      }
    }
  }
}
```