---
title: "Raise a new return (RMA) request"
method: POST
path: "/returns"
tags: ["Customer Return"]
---

# Raise a new return (RMA) request

`POST /returns`

## Request

- Base URL: `http://localhost:8000/api/shop`
- URL: `http://localhost:8000/api/shop/returns`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/bagisto/apis/bagisto-shop-api/docs/returns/post.ts> (a function with typed inputs; its response is checked against the schema)

Raises a return for one returnable order item. Send multipart/form-data to attach evidence images in `images[]`; a JSON body works without images. A JSON body, and GraphQL `createCustomerReturn`, take images as base64 data URIs in `images`, like the profile image.

## Headers

- `X-STOREFRONT-KEY` string, required
- `X-Locale` string
- `X-Channel` string
- `X-Currency` string

## Request body

- object
  - `order_id` integer, required
  - `order_item_id` integer, required
  - `rma_qty` integer, required
  - `resolution_type` 'return' | 'cancel_items', required
  - `rma_reason_id` integer, required
  - `information` string
  - `package_condition` 'open' | 'packed'
  - `custom_attributes` object
  - `agreement` boolean, required
  - `images` string[]: Evidence images as base64 data URIs, max 5 MB each.

## Response `201`

The created return request.

## Other responses

- `400`: Invalid input
- `422`: Validation Error

## Changes

- **2026-10-28** `63e385bd5442`: 1 info
  - added the new optional request property `images`
- **2026-09-14** `37a56692b7a4`: 1 warning, 2 info
  - removed the request property `images`
  - added the new optional request property `images[]`
  - the `custom_attributes` request property type was generalized from `object` to `string`
- **2026-09-09** `f5f1433697f6`: 1 breaking, 4 info
  - request property `package_condition` was restricted to a list of enum values
  - added the new optional request property `custom_attributes`
  - added the media type `multipart/form-data` to the request body
  - added the new `open` enum value to the request property `package_condition`
  - …1 more

[Operation history](https://skmtc.dev/bagisto/apis/bagisto-shop-api/changes/returns/post.md)

---

[API](https://skmtc.dev/bagisto/apis/bagisto-shop-api.md) - [All operations](https://skmtc.dev/bagisto/apis/bagisto-shop-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bagisto/apis/bagisto-shop-api/revisions/f619df36bf29?raw)