Medusa
Store APIAdmin API
Store APIAdmin API
Discord
Twitter
Linkedin
Github
  1. Returns
  • Getting Started
    • Introduction
    • Authentication
    • HTTP Compression
    • Publishable API Key
    • Expanding Fields
    • Selecting Fields
    • Query Parameter Types
    • Pagination
  • Auth
    • Check if Email Exists
      GET
    • Customer Login (JWT)
      POST
    • Customer Login (JWT)
      POST
    • Customer Log out
      DELETE
    • Get Current Customer
      GET
    • Customer Login
      POST
  • Carts
    • Create Payment Sessions
      POST
    • Update a Payment Session
      POST
    • Delete a Payment Session
      DELETE
    • Create a Cart
      POST
    • Get a Cart
      GET
    • Update a Cart
      POST
    • Remove Discount
      DELETE
    • Add a Line Item
      POST
    • Update a Line Item
      POST
    • Delete a Line Item
      DELETE
    • Select a Payment Session
      POST
    • Refresh a Payment Session
      POST
    • Add Shipping Method
      POST
    • Calculate Cart Taxes
      POST
    • Complete a Cart
      POST
  • Customers
    • Get Saved Payment Methods
    • Request Password Reset
    • Update a Shipping Address
    • Delete an Address
    • Create a Customer
    • Get a Customer
    • Update Customer
    • Add a Shipping Address
    • Reset Password
    • List Orders
  • Gift Cards
    • Get Gift Card by Code
  • Orders
    • Claim Order
    • Verify Order Claim
    • Look Up an Order
    • Get by Cart ID
    • Get an Order
  • Order Edits
    • Retrieve an Order Edit
    • Decline an Order Edit
    • Complete an Order Edit
  • Payment Collections
    • Refresh a Payment Session
    • Authorize Payment Session
    • Get a PaymentCollection
    • Create a Payment Session
    • Manage Payment Sessions
    • Authorize Payment Sessions
  • Products
    • Search Products
    • Get a Product
    • List Products
  • Product Variants
    • Get Product Variants
    • Get a Product Variant
  • Product Categories
    • Get a Product Category
    • List Product Categories
  • Product Collections
    • List Collections
    • Get a Collection
  • Product Tags
    • List Product Tags
  • Product Types
    • List Product Types
  • Regions
    • Get a Region
    • List Regions
  • Returns
    • Create Return
      POST
  • Return Reasons
    • List Return Reasons
    • Get a Return Reason
  • Shipping Options
    • List for Cart
    • Get Shipping Options
  • Swaps
    • Create a Swap
    • Get by Cart ID
  1. Returns

Create Return

POST
/store/returns
Returns
Create a Return for an Order. If a return shipping method is specified, the return is automatically fulfilled.

Request

Body Params application/json
The details of the return to create.
order_id
string 
required
The ID of the Order to create the return for.
return_shipping
object 
optional
The return shipping method used to return the items. If provided, a fulfillment is automatically created for the return.
option_id
string 
required
The ID of the Shipping Option to create the Shipping Method from.
items
array [object {4}] 
required
The items to include in the return.
item_id
string 
required
The ID of the line item to return.
quantity
integer 
required
The quantity to return.
reason_id
string 
optional
The ID of the return reason. Return reasons can be retrieved from the List Return Reasons API Route.
note
string 
optional
A note to add to the item returned.
Example
{
    "order_id": "string",
    "return_shipping": {
        "option_id": "string"
    },
    "items": [
        {
            "item_id": "string",
            "quantity": 0,
            "reason_id": "string",
            "note": "string"
        }
    ]
}

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api.medusa-commerce.com/store/returns' \
--header 'Content-Type: application/json' \
--data-raw '{
    "order_id": "string",
    "return_shipping": {
        "option_id": "string"
    },
    "items": [
        {
            "item_id": "string",
            "quantity": 0,
            "reason_id": "string",
            "note": "string"
        }
    ]
}'

Responses

🟢200OK
application/json
Body
The return's details.
return
object (Return) 
required
A Return holds information about Line Items that a Customer wishes to send back, along with how the items will be returned. Returns can also be used as part of a Swap or a Claim.
id
string 
required
The return's ID
Example:
ret_01F0YET7XPCMF8RZ0Y151NZV2V
swap_id
string  | null 
required
The ID of the swap that the return may belong to.
Example:
null
swap
object  | null 
optional
The details of the swap that the return may belong to.
claim_order_id
string  | null 
required
The ID of the claim that the return may belong to.
Example:
null
claim_order
object  | null 
optional
The details of the claim that the return may belong to.
order_id
string  | null 
required
The ID of the order that the return was created for.
Example:
order_01G8TJSYT9M6AVS5N4EMNFS1EK
order
object  | null 
optional
The details of the order that the return was created for.
location_id
string  | null 
required
The ID of the stock location the return will be added back.
Example:
sloc_01G8TJSYT9M6AVS5N4EMNFS1EK
refund_amount
integer 
required
The amount that should be refunded as a result of the return.
Example:
1000
no_notification
boolean  | null 
required
When set to true, no notification will be sent related to this return.
Example:
false
received_at
string <date-time> | null 
required
The date with timezone at which the return was received.
created_at
string <date-time>
required
The date with timezone at which the resource was created.
updated_at
string <date-time>
required
The date with timezone at which the resource was updated.
status
enum<string> 
required
Status of the Return.
Allowed values:
requestedreceivedrequires_actioncanceled
Default:
requested
shipping_data
object  | null 
required
Data about the return shipment as provided by the Fulfilment Provider that handles the return shipment.
Example:
{}
idempotency_key
string  | null 
required
Randomly generated key used to continue the completion of the return in case of failure.
metadata
object  | null 
required
An optional key-value map with additional details
Example:
{"car":"white"}
shipping_method
object (Shipping Method) 
optional
A Shipping Method represents a way in which an Order or Return can be shipped. Shipping Methods are created from a Shipping Option, but may contain additional details that can be necessary for the Fulfillment Provider to handle the shipment. If the shipping method is created for a return, it may be associated with a claim or a swap that the return is part of.
items
array[object (Return Item) {12}] 
optional
The details of the items that the customer is returning.
Example
{
    "return": {
        "id": "ret_01F0YET7XPCMF8RZ0Y151NZV2V",
        "swap_id": null,
        "swap": {},
        "claim_order_id": null,
        "claim_order": {},
        "order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
        "order": {},
        "location_id": "sloc_01G8TJSYT9M6AVS5N4EMNFS1EK",
        "refund_amount": 1000,
        "no_notification": false,
        "received_at": "2019-08-24T14:15:22Z",
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "status": "requested",
        "shipping_data": {},
        "idempotency_key": "string",
        "metadata": {
            "car": "white"
        },
        "shipping_method": {
            "id": "sm_01F0YET7DR2E7CYVSDHM593QG2",
            "shipping_option_id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
            "order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
            "order": {},
            "claim_order_id": null,
            "claim_order": {},
            "cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
            "cart": {},
            "swap_id": null,
            "swap": {},
            "return_id": null,
            "return_order": {},
            "price": 200,
            "includes_tax": false,
            "subtotal": 8000,
            "total": 8200,
            "tax_total": 0,
            "data": {},
            "tax_lines": [
                {
                    "id": "smtl_01G1G5V2DRX1SK6NQQ8VVX4HQ8",
                    "code": "tax01",
                    "name": "Tax Example",
                    "rate": 10,
                    "shipping_method_id": "sm_01F0YET7DR2E7CYVSDHM593QG2",
                    "shipping_method": {},
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "metadata": {
                        "car": "white"
                    }
                }
            ],
            "shipping_option": {
                "id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
                "name": "PostFake Standard",
                "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
                "region": {},
                "profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
                "provider_id": "manual",
                "amount": 200,
                "is_return": false,
                "admin_only": false,
                "includes_tax": false,
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "deleted_at": "2019-08-24T14:15:22Z",
                "price_type": "flat_rate",
                "data": {},
                "metadata": {
                    "car": "white"
                },
                "provider": {
                    "id": "manual",
                    "is_installed": true
                },
                "requirements": [
                    {
                        "id": "sor_01G1G5V29AB4CTNDRFSRWSRKWD",
                        "shipping_option_id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
                        "shipping_option": {},
                        "amount": 100,
                        "deleted_at": "2019-08-24T14:15:22Z",
                        "type": "min_subtotal"
                    }
                ],
                "profile": {
                    "id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
                    "name": "Default Shipping Profile",
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "deleted_at": "2019-08-24T14:15:22Z",
                    "type": "default",
                    "products": [
                        {}
                    ],
                    "shipping_options": [
                        {}
                    ],
                    "metadata": {
                        "car": "white"
                    }
                }
            }
        },
        "items": [
            {
                "return_id": "ret_01F0YET7XPCMF8RZ0Y151NZV2V",
                "item_id": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN",
                "return_order": {},
                "quantity": 1,
                "is_requested": true,
                "requested_quantity": 1,
                "received_quantity": 1,
                "reason_id": "rr_01G8X82GCCV2KSQHDBHSSAH5TQ",
                "note": "I didn't like it.",
                "metadata": {
                    "car": "white"
                },
                "reason": {
                    "id": "rr_01G8X82GCCV2KSQHDBHSSAH5TQ",
                    "value": "damaged",
                    "label": "Damaged goods",
                    "description": "Items that are damaged",
                    "parent_return_reason_id": null,
                    "parent_return_reason": {},
                    "return_reason_children": {},
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "deleted_at": "2019-08-24T14:15:22Z",
                    "metadata": {
                        "car": "white"
                    }
                },
                "item": {
                    "id": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN",
                    "cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
                    "cart": {},
                    "order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
                    "order": {},
                    "swap_id": null,
                    "swap": {},
                    "claim_order_id": null,
                    "claim_order": {},
                    "original_item_id": "string",
                    "order_edit_id": "string",
                    "order_edit": {},
                    "title": "Medusa Coffee Mug",
                    "description": "One Size",
                    "thumbnail": "https://medusa-public-images.s3.eu-west-1.amazonaws.com/coffee-mug.png",
                    "is_return": false,
                    "is_giftcard": false,
                    "should_merge": true,
                    "allow_discounts": true,
                    "has_shipping": false,
                    "unit_price": 8000,
                    "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
                    "quantity": 1,
                    "fulfilled_quantity": 0,
                    "returned_quantity": 0,
                    "shipped_quantity": 0,
                    "refundable": 0,
                    "subtotal": 8000,
                    "tax_total": 0,
                    "total": 8000,
                    "original_total": 8000,
                    "original_tax_total": 0,
                    "discount_total": 0,
                    "raw_discount_total": 0,
                    "gift_card_total": 0,
                    "includes_tax": false,
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "metadata": {
                        "car": "white"
                    },
                    "tax_lines": [
                        {
                            "id": "litl_01G1G5V2DRX1SK6NQQ8VVX4HQ8",
                            "code": "tax01",
                            "name": "Tax Example",
                            "rate": 10,
                            "item_id": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN",
                            "item": {},
                            "created_at": "2019-08-24T14:15:22Z",
                            "updated_at": "2019-08-24T14:15:22Z",
                            "metadata": {
                                "car": "white"
                            }
                        }
                    ],
                    "variant": {
                        "id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
                        "title": "Small",
                        "product_id": "prod_01G1G5V2MBA328390B5AXJ610F",
                        "product": {},
                        "sku": "shirt-123",
                        "barcode": null,
                        "ean": null,
                        "upc": null,
                        "variant_rank": 0,
                        "inventory_quantity": 100,
                        "allow_backorder": false,
                        "manage_inventory": true,
                        "hs_code": null,
                        "origin_country": null,
                        "mid_code": null,
                        "material": null,
                        "weight": null,
                        "length": null,
                        "height": null,
                        "width": null,
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z",
                        "deleted_at": "2019-08-24T14:15:22Z",
                        "purchasable": true,
                        "metadata": {
                            "car": "white"
                        },
                        "inventory_items": [
                            {
                                "id": "pvitem_01G8X9A7ESKAJXG2H0E6F1MW7A",
                                "inventory_item_id": "string",
                                "variant_id": "string",
                                "variant": {},
                                "required_quantity": 1,
                                "created_at": "2019-08-24T14:15:22Z",
                                "updated_at": "2019-08-24T14:15:22Z",
                                "deleted_at": "2019-08-24T14:15:22Z"
                            }
                        ],
                        "options": [
                            {
                                "id": "optval_01F0YESHR7S6ECD03RF6W12DSJ",
                                "value": "large",
                                "option_id": "opt_01F0YESHQBZVKCEXJ24BS6PCX3",
                                "option": {},
                                "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
                                "variant": {},
                                "created_at": "2019-08-24T14:15:22Z",
                                "updated_at": "2019-08-24T14:15:22Z",
                                "deleted_at": "2019-08-24T14:15:22Z",
                                "metadata": {
                                    "car": "white"
                                }
                            }
                        ],
                        "prices": [
                            {
                                "id": "ma_01F0YESHRFQNH5S8Q0PK84YYZN",
                                "amount": 100,
                                "min_quantity": 1,
                                "max_quantity": 1,
                                "price_list_id": "pl_01G8X3CKJXCG5VXVZ87H9KC09W",
                                "price_list": {},
                                "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
                                "variant": {},
                                "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
                                "region": {},
                                "created_at": "2019-08-24T14:15:22Z",
                                "updated_at": "2019-08-24T14:15:22Z",
                                "deleted_at": "2019-08-24T14:15:22Z",
                                "currency_code": "usd",
                                "currency": {
                                    "symbol": "$",
                                    "symbol_native": "$",
                                    "name": "US Dollar",
                                    "includes_tax": false,
                                    "code": "usd"
                                }
                            }
                        ]
                    },
                    "adjustments": [
                        {
                            "id": "lia_01G8TKE4XYCTHSCK2GDEP47RE1",
                            "item_id": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN",
                            "item": {},
                            "description": "Adjusted item's price.",
                            "discount_id": "disc_01F0YESMW10MGHWJKZSDDMN0VN",
                            "amount": 1000,
                            "metadata": {
                                "car": "white"
                            },
                            "discount": {
                                "id": "disc_01F0YESMW10MGHWJKZSDDMN0VN",
                                "code": "10DISC",
                                "is_dynamic": false,
                                "rule_id": "dru_01F0YESMVK96HVX7N419E3CJ7C",
                                "is_disabled": false,
                                "parent_discount_id": "disc_01G8ZH853YPY9B94857DY91YGW",
                                "parent_discount": {},
                                "starts_at": "2019-08-24T14:15:22Z",
                                "ends_at": "2019-08-24T14:15:22Z",
                                "valid_duration": "P3Y6M4DT12H30M5S",
                                "usage_limit": 100,
                                "usage_count": 0,
                                "created_at": "2019-08-24T14:15:22Z",
                                "updated_at": "2019-08-24T14:15:22Z",
                                "deleted_at": "2019-08-24T14:15:22Z",
                                "metadata": {
                                    "car": "white"
                                },
                                "rule": {
                                    "id": "dru_01F0YESMVK96HVX7N419E3CJ7C",
                                    "description": "10 Percent",
                                    "value": 10,
                                    "created_at": "2019-08-24T14:15:22Z",
                                    "updated_at": "2019-08-24T14:15:22Z",
                                    "deleted_at": "2019-08-24T14:15:22Z",
                                    "type": "fixed",
                                    "allocation": "total",
                                    "conditions": [
                                        {}
                                    ],
                                    "metadata": {
                                        "car": "white"
                                    }
                                },
                                "regions": [
                                    {
                                        "id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
                                        "name": "EU",
                                        "tax_rate": 0,
                                        "tax_code": null,
                                        "gift_cards_taxable": true,
                                        "automatic_taxes": true,
                                        "tax_provider_id": null,
                                        "includes_tax": false,
                                        "created_at": "2019-08-24T14:15:22Z",
                                        "updated_at": "2019-08-24T14:15:22Z",
                                        "deleted_at": "2019-08-24T14:15:22Z",
                                        "currency_code": "usd",
                                        "metadata": {
                                            "car": "white"
                                        },
                                        "countries": [
                                            {
                                                "id": 109,
                                                "name": "ITALY",
                                                "display_name": "Italy",
                                                "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
                                                "region": {},
                                                "iso_2": "it",
                                                "iso_3": "ita",
                                                "num_code": 380
                                            }
                                        ],
                                        "tax_provider": {
                                            "id": "manual",
                                            "is_installed": true
                                        },
                                        "payment_providers": [
                                            {
                                                "id": "manual",
                                                "is_installed": true
                                            }
                                        ],
                                        "fulfillment_providers": [
                                            {
                                                "id": "manual",
                                                "is_installed": true
                                            }
                                        ],
                                        "currency": {
                                            "symbol": "$",
                                            "symbol_native": "$",
                                            "name": "US Dollar",
                                            "includes_tax": false,
                                            "code": "usd"
                                        },
                                        "tax_rates": [
                                            {
                                                "id": "txr_01G8XDBAWKBHHJRKH0AV02KXBR",
                                                "rate": 10,
                                                "code": "tax01",
                                                "name": "Tax Example",
                                                "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
                                                "region": {},
                                                "product_count": 10,
                                                "product_type_count": 2,
                                                "shipping_option_count": 1,
                                                "created_at": "2019-08-24T14:15:22Z",
                                                "updated_at": "2019-08-24T14:15:22Z",
                                                "metadata": {
                                                    "car": "white"
                                                },
                                                "product_types": [
                                                    {
                                                        "id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
                                                        "value": "Clothing",
                                                        "created_at": "2019-08-24T14:15:22Z",
                                                        "updated_at": "2019-08-24T14:15:22Z",
                                                        "deleted_at": "2019-08-24T14:15:22Z",
                                                        "metadata": {
                                                            "car": "white"
                                                        }
                                                    }
                                                ],
                                                "shipping_options": [
                                                    {
                                                        "id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
                                                        "name": "PostFake Standard",
                                                        "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
                                                        "region": {},
                                                        "profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
                                                        "provider_id": "manual",
                                                        "amount": 200,
                                                        "is_return": false,
                                                        "admin_only": false,
                                                        "includes_tax": false,
                                                        "created_at": "2019-08-24T14:15:22Z",
                                                        "updated_at": "2019-08-24T14:15:22Z",
                                                        "deleted_at": "2019-08-24T14:15:22Z",
                                                        "price_type": "flat_rate",
                                                        "data": {},
                                                        "metadata": {
                                                            "car": "white"
                                                        },
                                                        "provider": {},
                                                        "requirements": [
                                                            null
                                                        ],
                                                        "profile": {
                                                            "products": [],
                                                            "shipping_options": [],
                                                            "metadata": {}
                                                        }
                                                    }
                                                ],
                                                "products": [
                                                    {
                                                        "id": "prod_01G1G5V2MBA328390B5AXJ610F",
                                                        "title": "Medusa Coffee Mug",
                                                        "subtitle": "string",
                                                        "description": "Every programmer's best friend.",
                                                        "handle": "coffee-mug",
                                                        "is_giftcard": false,
                                                        "thumbnail": "http://example.com",
                                                        "profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
                                                        "weight": null,
                                                        "length": null,
                                                        "height": null,
                                                        "width": null,
                                                        "hs_code": null,
                                                        "origin_country": null,
                                                        "mid_code": null,
                                                        "material": null,
                                                        "collection_id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
                                                        "type_id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
                                                        "discountable": true,
                                                        "external_id": null,
                                                        "created_at": "2019-08-24T14:15:22Z",
                                                        "updated_at": "2019-08-24T14:15:22Z",
                                                        "deleted_at": "2019-08-24T14:15:22Z",
                                                        "status": "draft",
                                                        "metadata": {
                                                            "car": "white"
                                                        },
                                                        "categories": [
                                                            null
                                                        ],
                                                        "collection": {
                                                            "products": [],
                                                            "metadata": {}
                                                        },
                                                        "type": {
                                                            "metadata": {}
                                                        },
                                                        "tags": [
                                                            null
                                                        ],
                                                        "images": [
                                                            null
                                                        ],
                                                        "profile": {
                                                            "products": [],
                                                            "shipping_options": [],
                                                            "metadata": {}
                                                        },
                                                        "profiles": [
                                                            null
                                                        ],
                                                        "options": [
                                                            null
                                                        ],
                                                        "sales_channels": [
                                                            null
                                                        ],
                                                        "variants": [
                                                            null
                                                        ]
                                                    }
                                                ]
                                            }
                                        ]
                                    }
                                ]
                            }
                        }
                    ]
                }
            }
        ]
    }
}
🟠400Client Error or Multiple Errors
🟠404Not Found Error
🟠409Invalid State Error
🟠422Invalid Request Error
🔴500Server Error
Modified at 2023-10-08 12:33:05
Previous
List Regions
Next
List Return Reasons
Built with