Medusa
Store APIAdmin API
Store APIAdmin API
Discord
Twitter
Linkedin
Github
  1. Returns
  • Introduction
  • Authentication
  • HTTP Compression
  • Publishable API Key
  • Expanding Fields
  • Selecting Fields
  • Query Parameter Types
  • Pagination
  • Currencies
    • List Currencies
      GET
    • Get a Currency
      GET
  • Payment Providers
    • List Payment Providers
      GET
  • Return Reasons
    • List Return Reasons
      GET
    • Get a Return Reason
      GET
  • Auth
    • Retrieve Registration JWT Token
      POST
    • Authenticate Customer
      POST
    • Generate Reset Password Token for Customer
      POST
    • Refresh Authentication Token
      POST
    • Validate Authentication Callback
      POST
    • Delete Authentication Session
      DELETE
    • Set Authentication Session
      POST
    • Reset a Customer's Password
      POST
  • Collections
    • List Collections
      GET
    • Get a Collection
      GET
  • Regions
    • List Regions
    • Get a Region
  • Products
    • List Products
    • Get a Product
  • Customers
    • Get Logged-in Customer
    • Update Customer
    • Create Address for Logged-In Customer
    • List Customer's Addresses
    • Get Customer's Address
    • Update Customer's Address
    • Remove Customer's Address
    • Register Customer
  • Product Tags
    • List Product Tags
    • Get a Product Tag
  • Returns
    • Create Return
      POST
  • Product Types
    • Get a Product Type
    • List Product Types
  • Product Categories
    • List Product Categories
    • Get a Product Category
  • Carts
    • Create Cart
    • Set Cart's Customer
    • Add Shipping Method to Cart
    • Add Line Item to Cart
    • Calculate Cart Taxes
    • Get a Cart
    • Update a Cart
    • Update a Line Item in a Cart
    • Remove Line Item from Cart
    • Complete Cart
    • Add Promotions to Cart
    • Remove Promotions from Cart
  • Orders
    • List Logged-in Customer's Orders
    • Request Order Transfer
    • Get an Order
    • Cancel Order Transfer
    • Decline Order Transfer
    • Accept Order Transfer
  • Payment Collections
    • Initialize Payment Session of a Payment Collection
    • Create Payment Collection
  • Shipping Options
    • Calculate Shipping Option Price
    • List Shipping Options for Cart
  1. Returns

Create Return

POST
/store/returns
Returns
Create a return for an order's items. The admin receives the return and process it from their side.
Request Request Example
Shell
JavaScript
Java
Swift
curl --location -g --request POST '{{BASE_URL}}/store/returns' \
--header 'x-publishable-api-key;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "order_id": "string",
    "note": "string",
    "receive_now": true,
    "location_id": "string",
    "items": [
        {
            "id": "string",
            "quantity": 0,
            "reason_id": "string",
            "note": "string"
        }
    ],
    "return_shipping": {
        "option_id": "string",
        "price": 0
    }
}'
Response Response Example
200 - Example 1
{
    "return": {
        "id": "string",
        "display_id": 0,
        "created_at": "2019-08-24T14:15:22Z",
        "order_id": "string",
        "location_id": "string",
        "canceled_at": "string",
        "exchange_id": "string",
        "claim_id": "string",
        "refund_amount": 0,
        "received_at": "string",
        "status": "received",
        "items": [
            {
                "id": "string",
                "quantity": 0,
                "received_quantity": 0,
                "damaged_quantity": 0,
                "reason_id": "string",
                "note": "string",
                "item_id": "string",
                "return_id": "string",
                "metadata": {}
            }
        ]
    }
}

Request

Header Params
x-publishable-api-key
string 
required
Publishable API Key created in the Medusa Admin.
Body Params application/json
The details of the return to create.
order_id
string 
order_id
required
The ID of the order this return is created for.
note
string 
note
optional
A note with more details about the return.
receive_now
boolean 
receive_now
optional
Whether to mark the return as received.
location_id
string 
location_id
optional
The ID of the location that items are returned to.
items
array[object (StoreCreateReturnItem) {4}] 
required
The return's items.
id
string 
id
required
The item's ID.
quantity
number 
quantity
required
The item's quantity.
reason_id
string 
reason_id
optional
The ID of the associated return reason.
note
string 
note
optional
A note with more details about the returned item.
return_shipping
object (StoreCreateReturnShipping) 
required
The return's shipping details.
option_id
string 
option_id
required
The ID of the shipping option to use.
price
number 
price
optional
The shipping's price.
Examples

Responses

🟢200OK
application/json
OK
Body
The return's details.
return
object (StoreReturn) 
required
The return's details.
id
string 
id
required
The return's ID.
display_id
number 
display_id
required
The return's display ID.
created_at
string <date-time>
created_at
required
The date the return was created.
order_id
string 
order_id
required
The ID of the order this return belongs to.
location_id
string 
location_id
optional
The ID of the location the return items are being returned to.
canceled_at
string 
canceled_at
required
The date the return was canceled.
exchange_id
string 
exchange_id
optional
The ID of the associated exchange.
claim_id
string 
claim_id
optional
The ID of the associated claim.
refund_amount
number 
refund_amount
optional
The amount to be refunded.
received_at
string 
received_at
required
The date the return items were received.
status
enum<string> 
optional
The return's status.
Allowed values:
receivedcanceledrequestedopenpartially_received
items
array[object (StoreReturnItem) {9}] 
required
The return's items.
🟠400Bad Request
🟠401Unauthorized
🟠404Record Not Found
🟠409409
🟠422Parameter Error
🔴500Server Error
Modified at 2025-06-17 04:21:30
Previous
Get a Product Tag
Next
Get a Product Type
Built with