Refund Walmart Return
POST/api/walmart/:integrationInstance/returns/:return/refund
Issue a refund against a Walmart Marketplace return order. Without a request body, every returned line is refunded at its full quantity. To refund only specific line(s) or quantities, send an optional lines array — each item has returnOrderLineNumber (integer, required) and quantity (integer ≥ 1, required). Reflects the refund status locally.
This endpoint currently requires session authentication; Personal Access Token scope support is in progress.
WFS-fulfilled returns are settled by Walmart and cannot be refunded here; attempting to refund one (or any Walmart-side failure) returns a 422 with the failure reason. The return must belong to the integration instance in the path (404 otherwise).
Requires a Bearer token.
When Walmart rejects the refund, the message carries Walmart's own reason (for example "Refund already issued for return order line 2") rather than its raw error envelope, so it can be shown to an end user as-is.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.