Medusa
Store APIAdmin API
Store APIAdmin API
Discord
Twitter
Linkedin
Github
  1. Returns
  • Plugins
    • List Plugins
      GET
  • Auth
    • Refresh Authentication Token
      POST
    • Validate Authentication Callback
      POST
    • Generate Reset Password Token for Admin User
      POST
    • Retrieve Registration JWT Token
      POST
    • Authenticate User
      POST
    • Set Authentication Session
      POST
    • Delete Authentication Session
      DELETE
    • Reset an Admin User's Password
      POST
  • Draft Orders
    • Create a Draft Order Edit
    • Cancel Edit on Draft Order
    • Confirm an Edit on a Draft Order
    • Request Edit on Draft Order
    • Convert a Draft Order to an Order
    • Add Item to Draft Order Edit
    • Update Existing Item in Draft Order Edit
    • Remove Item from Draft Order Edit
    • Update New Item in Draft Order Edit
    • Add Promotions to Draft Order Edit
    • Remove Promotions from Draft Order Edit
    • Add Shipping Method to Draft Order Edit
    • Remove Shipping Method from Draft Order Edit
    • Update Existing Shipping Method in Draft Order Edit
    • Remove New Shipping Method from Draft Order
    • Update New Shipping Method in Draft Order Edit
    • Delete a Draft Order
    • Get a Draft Order
    • Update a Draft Order
    • Create Draft Order
    • List Draft Orders
  • Fulfillment Providers
    • List Fulfillment Options
    • List Fulfillment Providers
  • Fulfillment Sets
    • Delete Fulfillment Set
    • Add a Service Zone to a Fulfillment Set
    • Remove a Service Zone from Fulfillment Set
    • Get a Service Zone in a Fulfillment Set
    • Update the Service Zone of a Fulfillment Set
  • Inventory Items
    • Manage Inventory Levels
    • Manage Inventory Levels of Inventory Item
    • Create Inventory Level for Inventory Item
    • List Inventory Levels
    • Update an Inventory Level of an Inventory Item
    • Remove Inventory Level of Inventory Item
    • Create Inventory Item
    • List Inventory Items
    • Get a Inventory Item
    • Delete Inventory Item
    • Update an Inventory Item
  • Order Edits
    • Create Order Edit
    • Confirm Order Edit
    • Request Order Edit
    • Add Items to Order Edit
    • Update Order Item Quantity of Order Edit
    • Remove Item from Order Edit
    • Update an Item in an Order Edit
    • Add Shipping Method to Order Edit
    • Remove Shipping Method from Order Edit
    • Update Shipping Method of an Order Edit
    • Cancel Order Edit
  • Orders
    • List Changes on an Order
    • Mark a Fulfillment as Delivered.
    • Get Preview
    • Archive an Order
    • Cancel Order
    • Cancel Transfer Request
    • Create Credit Line for Order
    • Request Order Transfer
    • Complete Order
    • Update Order
    • Get an Order
    • List Line Items
    • Cancel Fulfillment
    • Create an Order Fulfillment
    • Create Shipment for an Order's Fulfillment
    • List Orders
  • Payment Collections
    • Delete a Payment Collection
    • Create Payment Collection
    • Mark a Payment Collection as Paid
  • Products
    • Create Product Import
    • Confirm Product Import
    • Export Products
    • Manage Products
    • Manage Variants in a Product
    • Associate Variant with Inventory Item
    • Remove Inventory Item Association with Product Variant
    • Update Product Variant's Inventory Details
    • Delete a Product
    • Get a Product
    • Update a Product
    • Create a Product Option
    • List a Product's Options
    • Get a Product's Option
    • Delete an Option from Product
    • Update a Product's Option
    • Get Variant of a Product
    • Delete Product Variant
    • Update a Product Variant
    • Manage Variants Inventory in a Product
    • Create a Product Variant
    • List Variants of a Product
    • Create Product
    • List Products
  • Claims
    • Get a Claim
    • Cancel a Claim
    • Add Inbound Items to a Claim
    • Remove an Inbound Item from Claim
    • Update Inbound Items of a Claim
    • Add an Inbound Shipping Method to a Claim
    • Cancel Claim Request
    • Confirm a Claim Request
    • Add Claim Items to a Claim
    • Remove a Claim Item from a Claim
    • Update a Claim Item
    • Remove Inbound Shipping Method from Claim
    • Update Inbound Shipping Method of a Claim
    • Add Outbound Items to a Claim
    • Remove an Outbound Item from Claim
    • Update Outbound Item of a Claim
    • Add Outbound Shipping Methods to a Claim
    • Remove Outbound Shipping Method from Claim
    • Update Outbound Shipping Method of a Claim
    • Create a Claim
    • List Claims
  • Currencies
    • Get a Currency
    • List Currencies
  • Exchanges
    • Get an Exchange
    • Cancel an Exchange
    • Add Inbound Items to an Exchange
    • Remove Inbound Item from Exchange
    • Update an Inbount Item of an Exchange
    • Add an Inbound Shipping Method to an Exchange
    • Cancel Exchange Request
    • Confirm an Exchange
    • Remove Inbound Shipping Method from Exchange
    • Update Inbound Shipping Method of an Exchange
    • Add Outbound Items to Exchange
    • Remove Outbound Item from Exchange
    • Update Outbound Item of an Exchange
    • Add Outbound Shipping Method to Exchange
    • Remove Outbound Shipping Method from Exchange
    • Update Outbound Shipping Method of Exchange
    • Create Exchange
    • List Exchanges
  • Fulfillments
    • Cancel a Fulfillment
    • Create Fulfillment
    • Create a Shipment for a Fulfillment
  • Invites
    • Refresh Invite Token
    • Get an Invite
    • Delete Invite
    • Accept Invite
    • Create Invite
    • List Invites
  • Notifications
    • Get a Notification
    • List Notifications
  • Payments
    • Get a Payment
    • Capture Payment
    • Refund Payment
    • List Payment Providers
    • List Payments
  • Returns
    • Cancel a return.
      POST
    • Get a Return
      GET
    • Update a Return
      POST
    • Add Damaged Items to Return
      POST
    • Remove Damaged Item from Return
      DELETE
    • Update Damaged Item of Return
      POST
    • Add Received Items to Return
      POST
    • Remove a Received Item from Return
      DELETE
    • Update a Received Item in a Return
      POST
    • Confirm Return Receival
      POST
    • Add Requested Items to Return
      POST
    • Remove Item from Return
      DELETE
    • Update Requested Item in Return
      POST
    • Add a Shipping Method to a Return
      POST
    • Remove Shipping Method from Return
      DELETE
    • Update a Shipping Method of a Return
      POST
    • Start Return Receival
      POST
    • Cancel Return Receival
      DELETE
    • Confirm Return Request
      POST
    • Cancel Return Request
      DELETE
    • Create Return
      POST
    • List Returns
      GET
  • Users
    • Get Logged-In User
    • Delete a User
    • Get a User
    • Update a User
    • List Users
  • Workflows Executions
    • Get a Workflows Execution
    • Subscribe to a Workflow's Execution
    • Get Workflow Execution's Details
    • Subscribe to Step of a Workflow's Execution
    • Fail a Step in a Workflow's Execution
    • Succeed a Step in a Workflow's Execution
    • List Workflows Executions
    • Execute a Workflow
  • Api Keys
    • Revoke API Key
    • Get API Key
    • Update an API Key
    • Delete an Api Key
    • Manage Sales Channels of a Publishable API Key
    • Create Api Key
    • List API Keys
  • Price Lists
    • Remove Products from Price List
    • Delete a Price List
    • Get a Price List
    • Update a Price List
    • Manage Prices in Price List
    • Create Price List
    • List Price Lists
  • Stores
    • Get a Store
    • Update a Store
    • List Stores
  • Tax Rates
    • Create Tax Rule for a Rate
    • Delete a Tax Rate
    • Get a Tax Rate
    • Update a Tax Rate
    • Remove Rule of Tax Rate
    • Create Tax Rate
    • List Tax Rates
  • Price Preferences
    • Delete a Price Preference
    • Get a Price Preference
    • Update a Price Preference
    • Create Price Preference
    • List Price Preferences
  • Return Reasons
    • Delete a Return Reason
    • Get a Return Reason
    • Update a Return Reason
    • Create Return Reason
    • List Return Reasons
  • Sales Channels
    • Delete a Sales Channel
    • Get a Sales Channel
    • Update a Sales Channel
    • Manage Products in Sales Channel
    • Create Sales Channel
    • List Sales Channels
  • Stock Locations
    • Delete a Stock Location
    • Get a Stock Location
    • Update a Stock Location
    • Add Fulfillment Set to Stock Location
    • Manage Fulfillment Providers of a Stock Location
    • Manage Sales Channels of a Stock Location
    • Create Stock Location
    • List Stock Locations
  • Tax Regions
    • Delete a Tax Region
    • Update a Tax Region
    • Get a Tax Region
    • Create Tax Region
    • List Tax Regions
  • Promotions
    • List Rule Attribute Options of a Rule Type
    • List Rules of a Promotion
    • List Rule Values Given a Rule Attribute
    • Manage the Buy Rules of a Promotion
    • Manage a Promotion's Rules
    • Manage Target Rules of a Promotion
    • Get a Promotion
    • Delete a Promotion
    • Update a Promotion
    • List Promotions
    • Create Promotion
  • Customer Groups
    • Get a Customer Group
    • Update a Customer Group
    • Delete a Customer Group
    • Manage Customers of a Customer Group
    • Create Customer Group
    • List Customer Groups
  • Product Tags
    • Delete a Product Tag
    • Get a Product Tag
    • Update a Product Tag
    • Create Product Tag
    • List Product Tags
  • Product Types
    • Delete a Product Type
    • Get a Product Type
    • Update a Product Type
    • Create Product Type
    • List Product Types
  • Refund Reasons
    • Get a Refund Reason
    • Update a Refund Reason
    • Delete a Refund Reason
    • Create Refund Reason
    • List Refund Reasons
  • Uploads
    • Get a File
    • Delete a File
    • Upload Files
  • Campaigns
    • Manage the Promotions of a Campaign
    • Get a Campaign
    • Delete a Campaign
    • Update a Campaign
    • List Campaigns
    • Create Campaign
  • Collections
    • Manage Products of a Collection
    • Delete a Collection
    • Get a Collection
    • Update a Collection
    • Create Collection
    • List Collections
  • Customers
    • Manage Customer Groups of Customer
    • Get a Customer
    • Delete a Customer
    • Update a Customer
    • List Addresses
    • Add a Customer Address
    • List Addresses
    • Remove an Address from Customer
    • Update a Customer's Address
    • Create Customer
    • List Customers
  • Product Categories
    • Manage Products in Product Category
    • Delete a Product Category
    • Get a Product Category
    • Update a Product Category
    • Create Product Category
    • List Product Categories
  • Reservations
    • Get a Reservation
    • Update a Reservation
    • Delete a Reservation
    • Create Reservation
    • List Reservations
  • Shipping Profiles
    • Delete a Shipping Profile
    • Get a Shipping Profile
    • Update a Shipping Profile
    • Create Shipping Profile
    • List Shipping Profiles
  • Regions
    • Get a Region
    • Delete a Region
    • Update a Region
    • Create Region
    • List Regions
  • Tax Providers
    • List Tax Providers
  • Shipping Options
    • Manage the Rules of a Shipping Option
    • Create Shipping Option
    • List Shipping Options
    • Delete a Shipping Option
    • Get a Shipping Option
    • Update a Shipping Option
  • Product Variants
    • List Product Variants
  1. Returns

Create Return

POST
/admin/returns
Create a return. The return can later be requested or confirmed.
Request 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 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
or
or
or
Query Params

Body Params application/json

Examples

Responses

🟢200OK
application/json
OK
Body

🟠400Bad Request
🟠401Unauthorized
🟠404Record Not Found
🟠409409
🟠422Parameter Error
🔴500Server Error
Modified at 2025-06-17 04:10:32
Previous
Cancel Return Request
Next
List Returns
Built with