Send a Return Message

Add a customer message to the conversation thread of a return (RMA) request. The return must belong to the authenticated customer. The created message comes back flagged isAdmin: false.

Endpoint

POST /api/shop/return-messages

Authentication

This endpoint requires an authenticated customer — send the storefront key and a customer Bearer token. See the Authentication page.

Request Headers

Header	Required	Description
Content-Type	Yes	application/json, or multipart/form-data when the message carries an attachment
X-STOREFRONT-KEY	Yes	Your storefront API key
Authorization	Yes	Bearer token (customer login required)

Request Body

{
  "return_id": 12,
  "message": "Any update on my return?"
}

Request Parameters

Parameter	Type	Required	Description
return_id	integer	Yes	Id of the return to add the message to. Must belong to the authenticated customer.
message	string	Yes	The message text.

Attachments

A message can carry one file — a photo of the damaged item, a scan, a receipt. Send the same fields as multipart/form-data instead of a JSON body and add the file in a file field:

curl -X POST https://your-store.com/api/shop/return-messages \
  -H "X-STOREFRONT-KEY: pk_storefront_..." \
  -H "Authorization: Bearer <customer-token>" \
  -F "return_id=12" \
  -F "message=Photo of the damaged zipper attached." \
  -F "[email protected]"

• One file per message. To send several, post several messages; each keeps its own attachment.
• The stored file is renamed. The server stores it under rma-conversation/{messageId}/ with a generated name, and the extension is derived from the file's detected type. attachment in the response keeps the name the customer uploaded, so show that in the conversation and link to attachmentUrl.
• Any file type the store accepts is allowed here. Unlike the evidence images on Create Return, a conversation attachment is not restricted to the configured image types.
• JSON stays valid. Omit the file and send application/json exactly as in the first example; attachment and attachmentUrl then come back null.

Response Fields (201 Created)

Field	Type	Description
id	integer	Numeric message id.
rmaId	integer	Id of the return the message belongs to.
message	string	The message text.
isAdmin	boolean	false — the message was sent by the customer.
attachment	string	File name as the customer uploaded it, or null when the message has no attachment.
attachmentUrl	string	Public URL of the stored file, or null.
createdAt	string	ISO 8601 message timestamp.

Status Codes

Status	Meaning
201 Created	Message added to the return conversation, with the attachment stored when one was sent.
400 Bad Request	message is missing.
401 Unauthorized	Missing or invalid storefront key.
403 Forbidden	Missing or invalid customer Bearer token.
404 Not Found	The return does not exist or is not the customer's.

Related Resources

• List Return Messages — the conversation thread on a return
• View Return — one return with its status flags
• Returns Overview — the returns menu overview, including the settings that gate it