Medusa

Create Return

POST

/admin/returns

Returns

Create a return. The return can later be requested or confirmed.

Request Example

JavaScript

Shell

Java

Swift

curl --location -g --request POST '{{BASE_URL}}/admin/returns' \
--header 'Content-Type: application/json' \
--data-raw '{
    "order_id": "string",
    "location_id": "string",
    "description": "string",
    "internal_note": "string",
    "no_notification": true,
    "metadata": {}
}'

Response Example

200 - Example 1

{
    "order": {
        "shipping_address": {
            "id": "string",
            "customer_id": "string",
            "first_name": "string",
            "last_name": "string",
            "phone": "string",
            "company": "string",
            "address_1": "string",
            "address_2": "string",
            "city": "string",
            "country_code": "us",
            "postal_code": "string",
            "metadata": {},
            "created_at": "2019-08-24T14:15:22Z",
            "updated_at": "2019-08-24T14:15:22Z",
            "province": "us-ca"
        },
        "billing_address": {
            "id": "string",
            "customer_id": "string",
            "first_name": "string",
            "last_name": "string",
            "phone": "string",
            "company": "string",
            "address_1": "string",
            "address_2": "string",
            "city": "string",
            "country_code": "us",
            "postal_code": "string",
            "metadata": {},
            "created_at": "2019-08-24T14:15:22Z",
            "updated_at": "2019-08-24T14:15:22Z",
            "province": "us-ca"
        },
        "id": "string",
        "version": 0,
        "order_change": {},
        "region_id": "string",
        "customer_id": "string",
        "sales_channel_id": "string",
        "email": "user@example.com",
        "currency_code": "usd",
        "items": [
            {
                "detail": {
                    "id": "string",
                    "item_id": "string",
                    "item": {},
                    "quantity": 0,
                    "fulfilled_quantity": 0,
                    "delivered_quantity": 0,
                    "shipped_quantity": 0,
                    "return_requested_quantity": 0,
                    "return_received_quantity": 0,
                    "return_dismissed_quantity": 0,
                    "written_off_quantity": 0,
                    "metadata": {},
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z"
                },
                "id": "string",
                "title": "string",
                "subtitle": "string",
                "thumbnail": "string",
                "variant_id": "string",
                "product_id": "string",
                "product_title": "string",
                "product_description": "string",
                "product_subtitle": "string",
                "product_type": "string",
                "product_collection": "string",
                "product_handle": "string",
                "variant_sku": "string",
                "variant_barcode": "string",
                "variant_title": "string",
                "requires_shipping": true,
                "is_discountable": true,
                "is_tax_inclusive": true,
                "compare_at_unit_price": 0,
                "unit_price": 0,
                "quantity": 0,
                "tax_lines": [
                    {
                        "item": {},
                        "item_id": "string",
                        "total": 0,
                        "subtotal": 0,
                        "id": "string",
                        "description": "string",
                        "tax_rate_id": "string",
                        "code": "string",
                        "rate": 0,
                        "provider_id": "string",
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z"
                    }
                ],
                "adjustments": [
                    {
                        "item": {},
                        "item_id": "string",
                        "id": "string",
                        "code": "string",
                        "amount": 0,
                        "order_id": "string",
                        "description": "string",
                        "promotion_id": "string",
                        "provider_id": "string",
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z"
                    }
                ],
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "metadata": {},
                "original_total": 0,
                "original_subtotal": 0,
                "original_tax_total": 0,
                "item_total": 0,
                "item_subtotal": 0,
                "item_tax_total": 0,
                "total": 0,
                "subtotal": 0,
                "tax_total": 0,
                "discount_total": 0,
                "discount_tax_total": 0,
                "refundable_total": 0,
                "refundable_total_per_unit": 0,
                "product_type_id": "string",
                "is_giftcard": true,
                "variant_option_values": {
                    "Color": "Red"
                }
            }
        ],
        "shipping_methods": [
            {
                "id": "string",
                "order_id": "string",
                "name": "string",
                "description": "string",
                "amount": 0,
                "is_tax_inclusive": true,
                "shipping_option_id": "string",
                "metadata": {},
                "tax_lines": [
                    {
                        "shipping_method": {},
                        "shipping_method_id": "string",
                        "total": 0,
                        "subtotal": 0,
                        "id": "string",
                        "description": "string",
                        "tax_rate_id": "string",
                        "code": "string",
                        "rate": 0,
                        "provider_id": "string",
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z"
                    }
                ],
                "adjustments": [
                    {
                        "shipping_method": {},
                        "shipping_method_id": "string",
                        "id": "string",
                        "code": "string",
                        "amount": 0,
                        "order_id": "string",
                        "description": "string",
                        "promotion_id": "string",
                        "provider_id": "string",
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z"
                    }
                ],
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "original_total": 0,
                "original_subtotal": 0,
                "original_tax_total": 0,
                "total": 0,
                "subtotal": 0,
                "tax_total": 0,
                "discount_total": 0,
                "discount_tax_total": 0,
                "data": {}
            }
        ],
        "transactions": [
            {
                "id": "string",
                "order_id": "string",
                "amount": 0,
                "currency_code": "usd",
                "reference_id": "string",
                "metadata": {},
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "order": {},
                "version": 0,
                "reference": "capture"
            }
        ],
        "metadata": {},
        "canceled_at": "2019-08-24T14:15:22Z",
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "original_item_total": 0,
        "original_item_subtotal": 0,
        "original_item_tax_total": 0,
        "item_total": 0,
        "item_subtotal": 0,
        "item_tax_total": 0,
        "original_total": 0,
        "original_subtotal": 0,
        "original_tax_total": 0,
        "total": 0,
        "subtotal": 0,
        "tax_total": 0,
        "discount_subtotal": 0,
        "discount_total": 0,
        "discount_tax_total": 0,
        "gift_card_total": 0,
        "gift_card_tax_total": 0,
        "shipping_total": 0,
        "shipping_subtotal": 0,
        "shipping_tax_total": 0,
        "original_shipping_total": 0,
        "original_shipping_subtotal": 0,
        "original_shipping_tax_total": 0,
        "display_id": 0,
        "credit_lines": [
            {
                "id": "string",
                "order_id": "string",
                "order": {},
                "reference": "string",
                "reference_id": "string",
                "metadata": {},
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "amount": 0
            }
        ],
        "is_draft_order": true,
        "deleted_at": "2019-08-24T14:15:22Z",
        "status": "canceled",
        "summary": {
            "pending_difference": 0,
            "current_order_total": 0,
            "original_order_total": 0,
            "transaction_total": 0,
            "paid_total": 0,
            "refunded_total": 0,
            "credit_line_total": 0,
            "accounting_total": 0,
            "raw_pending_difference": {},
            "raw_current_order_total": {},
            "raw_original_order_total": {},
            "raw_transaction_total": {},
            "raw_paid_total": {},
            "raw_refunded_total": {},
            "raw_credit_line_total": {},
            "raw_accounting_total": {}
        }
    },
    "return": {
        "id": "string",
        "refund_amount": 0,
        "order_id": "string",
        "items": [
            {
                "id": "string",
                "quantity": 0,
                "received_quantity": 0,
                "damaged_quantity": 0,
                "reason_id": "string",
                "note": "string",
                "item_id": "string",
                "return_id": "string",
                "metadata": {}
            }
        ],
        "created_at": "2019-08-24T14:15:22Z",
        "canceled_at": "2019-08-24T14:15:22Z",
        "exchange_id": "string",
        "location_id": "string",
        "claim_id": "string",
        "order_version": 0,
        "display_id": 0,
        "no_notification": true,
        "received_at": "string",
        "status": "canceled"
    }
}

Request

Authorization

Query Params

fields

string

fields

optional

Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Body Params application/json

The return's details.

order_id

string

order_id

required

The ID of the order the return belongs to.

location_id

string

location_id

optional

The ID of the location the items are returned to.

description

string

description

optional

The return's description.

internal_note

string

internal_note

optional

A note viewed only by admin users.

no_notification

boolean

no_notification

optional

Whether to send the customer a notification about the created return.

metadata

object

optional

The return's metadata, can hold custom key-value pairs.

Examples

Responses

🟢200OK

application/json

Body

The order return details.

order

object (Order)

required

The order change's order.

shipping_address

object (OrderAddress)

optional

The address's details.

billing_address

object (OrderAddress)

optional

The address's details.

string

required

The order's ID.

version

number

version

required

The order's version.

order_change

object

optional

region_id

string

region_id

optional

The ID of the region the order belongs to.

customer_id

string

customer_id

optional

The ID of the customer that placed the order.

sales_channel_id

string

sales_channel_id

optional

The ID of the sales channel the order was placed in.

string <email>

optional

The email of the customer that placed the order.

currency_code

string

currency_code

required

The order's currency code.

Example:

usd

items

array[object (OrderLineItem) {43}]

optional

The order's items.

shipping_methods

array[object (OrderShippingMethod) {21}]

optional

The order's shipping methods.

transactions

array[object (OrderTransaction) {11}]

optional

The order's transactions.

metadata

object

optional

The order's metadata, can hold custom key-value pairs.

canceled_at

string <date-time>

canceled_at

optional

The date the order was canceled.

created_at

string <date-time>

created_at

required

The date the order was created.

updated_at

string <date-time>

updated_at

required

The date the order was updated.

original_item_total

number

original_item_total

required

The order items' total including taxes, excluding promotions.

original_item_subtotal

number

original_item_subtotal

required

The order items' total excluding taxes, including promotions.

original_item_tax_total

number

original_item_tax_total

required

The taxes total for order items, excluding promotions.

item_total

number

item_total

required

The order items' total including taxes and promotions.

item_subtotal

number

item_subtotal

required

The order items' total excluding taxes, including promotions.

item_tax_total

number

item_tax_total

required

The tax total of the order items including promotions.

original_total

number

original_total

required

The order's total including taxes, excluding promotions.

original_subtotal

number

original_subtotal

required

The order's total excluding taxes, including promotions.

original_tax_total

number

original_tax_total

required

The tax total of the order excluding promotions.

total

number

total

required

The order's total including taxes and promotions.

subtotal

number

subtotal

required

The order's subtotal excluding taxes, including promotions.

tax_total

number

tax_total

required

The tax total of the order including promotions.

discount_subtotal

number

discount_subtotal

required

The total discount excluding taxes.

discount_total

number

discount_total

required

The total discount including taxes.

discount_tax_total

number

discount_tax_total

required

The tax total applied on the discount.

gift_card_total

number

gift_card_total

required

The order's gift card total.

gift_card_tax_total

number

gift_card_tax_total

required

The order's gift card tax total.

shipping_total

number

shipping_total

required

The order's shipping total including taxes and promotions.

shipping_subtotal

number

shipping_subtotal

required

The order's shipping total excluding taxes, including promotions.

shipping_tax_total

number

shipping_tax_total

required

The total taxes of the order's shipping including taxes.

original_shipping_total

number

original_shipping_total

required

The order's shipping total including taxes, excluding promotions.

original_shipping_subtotal

number

original_shipping_subtotal

required

The order's shipping total excluding taxes, including promotions.

original_shipping_tax_total

number

original_shipping_tax_total

required

The total taxes of the order's shipping excluding promotions.

display_id

number

display_id

required

The order's display ID.

credit_lines

array[object (OrderCreditLine) {9}]

optional

The order's credit lines, useful to add additional payment amounts for an order.

is_draft_order

boolean

is_draft_order

optional

Whether the order is a draft order.

deleted_at

string <date-time>

deleted_at

optional

The date the order was deleted.

status

enum<string>

required

The order's status.

Allowed values:

canceledrequires_actionpendingcompleteddraftarchived

summary

object

optional

The order's summary.

return

object (AdminReturn)

required

The return's details.

string

required

The return's ID.

refund_amount

number

refund_amount

optional

The amount refunded by this return.

order_id

string

order_id

required

The ID of the associated order.

items

array[object (AdminReturnItem) {9}]

required

The return's items.

created_at

string <date-time>

created_at

required

The date the return was created.

canceled_at

string <date-time>

canceled_at

required

The date the return was canceled.

exchange_id

string

exchange_id

optional

The return's exchange id.

location_id

string

location_id

optional

The return's location id.

claim_id

string

claim_id

optional

The return's claim id.

order_version

number

order_version

required

The return's order version.

display_id

number

display_id

required

The return's display id.

no_notification

boolean

no_notification

optional

Whether the customer should receive notifications about the return's updates.

received_at

string

received_at

required

The date the return was received.

status

enum<string>

optional

The return's status.

Allowed values:

canceledrequestedreceivedpartially_received

🟠400Bad Request

🟠401Unauthorized

🟠404Record Not Found

🟠409409

🟠422Parameter Error

🔴500Server Error

Modified at 2025-06-17 04:10:32

Cancel Return Request

List Returns