# Medusa Returns API

**Canonical:** https://apis.io/apis/medusa/medusa-returns-api/  
**Provider:** Medusa — https://apis.io/providers/medusa/  
**Base URL:** https://{medusa-backend-domain}  
**Documentation:** https://docs.medusajs.com/api/store

Medusa Returns API is one of 82 APIs that [Medusa](https://apis.io/providers/medusa/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include Returns. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, an API reference, and authentication docs.

Admin users create a return when a customer returns an item to them. Returns can also be created by customers through the storefront, and admins will be able to manage them and make refunds, if necessary. Refunds are made through the [Payment API Routes](#payment) These API routes allow admin users to manage returns.

## Operations (23)

| Method | Path | Summary |
|---|---|---|
| GET | `/admin/returns` | List Returns |
| POST | `/admin/returns` | Create Return |
| GET | `/admin/returns/{id}` | Get a Return |
| POST | `/admin/returns/{id}` | Update a Return |
| POST | `/admin/returns/{id}/cancel` | Cancel a return. |
| POST | `/admin/returns/{id}/dismiss-items` | Add Damaged Items to Return |
| POST | `/admin/returns/{id}/dismiss-items/{action_id}` | Update Damaged Item of Return |
| DELETE | `/admin/returns/{id}/dismiss-items/{action_id}` | Remove Damaged Item from Return |
| POST | `/admin/returns/{id}/receive` | Start Return Receival |
| DELETE | `/admin/returns/{id}/receive` | Cancel Return Receival |
| POST | `/admin/returns/{id}/receive-items` | Add Received Items to Return |
| POST | `/admin/returns/{id}/receive-items/{action_id}` | Update a Received Item in a Return |
| DELETE | `/admin/returns/{id}/receive-items/{action_id}` | Remove a Received Item from Return |
| POST | `/admin/returns/{id}/receive/confirm` | Confirm Return Receival |
| POST | `/admin/returns/{id}/request` | Confirm Return Request |
| DELETE | `/admin/returns/{id}/request` | Cancel Return Request |
| POST | `/admin/returns/{id}/request-items` | Add Requested Items to Return |
| POST | `/admin/returns/{id}/request-items/{action_id}` | Update Requested Item in Return |
| DELETE | `/admin/returns/{id}/request-items/{action_id}` | Remove Item from Return |
| POST | `/admin/returns/{id}/shipping-method` | Add a Shipping Method to a Return |
| POST | `/admin/returns/{id}/shipping-method/{action_id}` | Update a Shipping Method of a Return |
| DELETE | `/admin/returns/{id}/shipping-method/{action_id}` | Remove Shipping Method from Return |
| POST | `/store/returns` | Create Return |

## Machine-readable artifacts (9)

- **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/medusa/refs/heads/main/openapi/medusa-returns-api-openapi.yml
- **Documentation** — https://docs.medusajs.com/api/store
- **APIReference** — https://docs.medusajs.com/api/store
- **OpenAPI Source** — https://raw.githubusercontent.com/medusajs/medusa/develop/www/apps/api-reference/specs/store/openapi.full.yaml
- **Authentication** — https://docs.medusajs.com/api/store#authentication
- **Documentation** — https://docs.medusajs.com/api/admin
- **APIReference** — https://docs.medusajs.com/api/admin
- **OpenAPI Source** — https://raw.githubusercontent.com/medusajs/medusa/develop/www/apps/api-reference/specs/admin/openapi.full.yaml
- **Authentication** — https://docs.medusajs.com/api/admin#authentication

## Other Medusa APIs (12)

- [Medusa GraphQL API](https://apis.io/apis/medusa/medusa-graphql-api/)
- [Medusa MCP Remote Server](https://apis.io/apis/medusa/medusa-mcp-server/)
- [Medusa Api Keys API](https://apis.io/apis/medusa/medusa-api-keys-api/)
- [Medusa Auth API](https://apis.io/apis/medusa/medusa-auth-api/)
- [Medusa [auth Provider] API](https://apis.io/apis/medusa/medusa-auth-provider-api/)
- [Medusa Campaigns API](https://apis.io/apis/medusa/medusa-campaigns-api/)
- [Medusa Carts API](https://apis.io/apis/medusa/medusa-carts-api/)
- [Medusa Claims API](https://apis.io/apis/medusa/medusa-claims-api/)
- [Medusa Collections API](https://apis.io/apis/medusa/medusa-collections-api/)
- [Medusa Currencies API](https://apis.io/apis/medusa/medusa-currencies-api/)
- [Medusa Customer Groups API](https://apis.io/apis/medusa/medusa-customer-groups-api/)
- [Medusa Customers API](https://apis.io/apis/medusa/medusa-customers-api/)

## Tags

Returns

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/medusa/medusa-returns-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/medusa/.