Skip to main content
POST
/
admin
/
returns
JS SDK
import Medusa from "@medusajs/js-sdk"

export const sdk = new Medusa({
  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
  debug: import.meta.env.DEV,
  auth: {
    type: "session",
  },
})

sdk.admin.return.initiateRequest({
  order_id: "order_123",
})
.then(({ return }) => {
  console.log(return)
})
{
  "order": {
    "id": "<string>",
    "version": 123,
    "status": "canceled",
    "currency_code": "usd",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "original_item_total": 123,
    "original_item_subtotal": 123,
    "original_item_tax_total": 123,
    "item_total": 123,
    "item_subtotal": 123,
    "item_tax_total": 123,
    "original_total": 123,
    "original_subtotal": 123,
    "original_tax_total": 123,
    "total": 123,
    "subtotal": 123,
    "tax_total": 123,
    "discount_subtotal": 123,
    "discount_total": 123,
    "discount_tax_total": 123,
    "gift_card_total": 123,
    "gift_card_tax_total": 123,
    "shipping_total": 123,
    "shipping_subtotal": 123,
    "shipping_tax_total": 123,
    "original_shipping_total": 123,
    "original_shipping_subtotal": 123,
    "original_shipping_tax_total": 123,
    "display_id": 123,
    "credit_line_total": 123,
    "item_discount_total": 123,
    "shipping_discount_total": 123,
    "order_change": {},
    "region_id": "<string>",
    "customer_id": "<string>",
    "sales_channel_id": "<string>",
    "email": "jsmith@example.com",
    "shipping_address": {
      "id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "customer_id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "phone": "<string>",
      "company": "<string>",
      "address_1": "<string>",
      "address_2": "<string>",
      "city": "<string>",
      "country_code": "us",
      "province": "us-ca",
      "postal_code": "<string>",
      "metadata": {}
    },
    "billing_address": {
      "id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "customer_id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "phone": "<string>",
      "company": "<string>",
      "address_1": "<string>",
      "address_2": "<string>",
      "city": "<string>",
      "country_code": "us",
      "province": "us-ca",
      "postal_code": "<string>",
      "metadata": {}
    },
    "items": [
      {
        "id": "<string>",
        "title": "<string>",
        "requires_shipping": true,
        "is_discountable": true,
        "is_tax_inclusive": true,
        "unit_price": 123,
        "quantity": 123,
        "detail": {
          "id": "<string>",
          "item_id": "<string>",
          "item": {},
          "quantity": 123,
          "fulfilled_quantity": 123,
          "delivered_quantity": 123,
          "shipped_quantity": 123,
          "return_requested_quantity": 123,
          "return_received_quantity": 123,
          "return_dismissed_quantity": 123,
          "written_off_quantity": 123,
          "metadata": {},
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z"
        },
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "original_total": 123,
        "original_subtotal": 123,
        "original_tax_total": 123,
        "item_total": 123,
        "item_subtotal": 123,
        "item_tax_total": 123,
        "total": 123,
        "subtotal": 123,
        "tax_total": 123,
        "discount_total": 123,
        "discount_tax_total": 123,
        "refundable_total": 123,
        "refundable_total_per_unit": 123,
        "is_giftcard": true,
        "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>",
        "variant_option_values": {
          "Color": "Red"
        },
        "compare_at_unit_price": 123,
        "tax_lines": [
          {
            "item": {},
            "item_id": "<string>",
            "total": 123,
            "subtotal": 123,
            "id": "<string>",
            "code": "<string>",
            "rate": 123,
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "description": "<string>",
            "tax_rate_id": "<string>",
            "provider_id": "<string>"
          }
        ],
        "adjustments": [
          {
            "item": {},
            "item_id": "<string>",
            "id": "<string>",
            "amount": 123,
            "order_id": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "code": "<string>",
            "description": "<string>",
            "promotion_id": "<string>",
            "provider_id": "<string>"
          }
        ],
        "metadata": {},
        "product_type_id": "<string>"
      }
    ],
    "shipping_methods": [
      {
        "id": "<string>",
        "order_id": "<string>",
        "name": "<string>",
        "amount": 123,
        "is_tax_inclusive": true,
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "original_total": 123,
        "original_subtotal": 123,
        "original_tax_total": 123,
        "total": 123,
        "subtotal": 123,
        "tax_total": 123,
        "discount_total": 123,
        "discount_tax_total": 123,
        "description": "<string>",
        "shipping_option_id": "<string>",
        "data": {},
        "metadata": {},
        "tax_lines": [
          {
            "shipping_method": {},
            "shipping_method_id": "<string>",
            "total": 123,
            "subtotal": 123,
            "id": "<string>",
            "code": "<string>",
            "rate": 123,
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "description": "<string>",
            "tax_rate_id": "<string>",
            "provider_id": "<string>"
          }
        ],
        "adjustments": [
          {
            "shipping_method": {},
            "shipping_method_id": "<string>",
            "id": "<string>",
            "amount": 123,
            "order_id": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "code": "<string>",
            "description": "<string>",
            "promotion_id": "<string>",
            "provider_id": "<string>"
          }
        ]
      }
    ],
    "transactions": [
      {
        "id": "<string>",
        "order_id": "<string>",
        "amount": 123,
        "currency_code": "usd",
        "reference": "capture",
        "reference_id": "<string>",
        "metadata": {},
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "order": {},
        "version": 123
      }
    ],
    "summary": {
      "pending_difference": 123,
      "current_order_total": 123,
      "original_order_total": 123,
      "transaction_total": 123,
      "paid_total": 123,
      "refunded_total": 123,
      "credit_line_total": 123,
      "accounting_total": 123,
      "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": {}
    },
    "metadata": {},
    "canceled_at": "2023-11-07T05:31:56Z",
    "credit_lines": [
      {
        "id": "<string>",
        "order_id": "<string>",
        "order": {},
        "reference": "<string>",
        "reference_id": "<string>",
        "metadata": {},
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "amount": 123
      }
    ],
    "is_draft_order": true,
    "deleted_at": "2023-11-07T05:31:56Z",
    "custom_display_id": "<string>",
    "locale": "en-US"
  },
  "return": {
    "id": "<string>",
    "order_id": "<string>",
    "items": [
      {
        "id": "<string>",
        "quantity": 123,
        "received_quantity": 123,
        "damaged_quantity": 123,
        "item_id": "<string>",
        "return_id": "<string>",
        "reason_id": "<string>",
        "note": "<string>",
        "metadata": {}
      }
    ],
    "created_at": "2023-11-07T05:31:56Z",
    "canceled_at": "2023-11-07T05:31:56Z",
    "order_version": 123,
    "display_id": 123,
    "received_at": "<string>",
    "status": "canceled",
    "refund_amount": 123,
    "exchange_id": "<string>",
    "location_id": "<string>",
    "claim_id": "<string>",
    "no_notification": true
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
fields
string

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

application/json

The return's details.

​
order_id
string
required

The ID of the order the return belongs to.

​
location_id
string

The ID of the location the items are returned to.

​
description
string

The return's description.

​
internal_note
string

A note viewed only by admin users.

​
no_notification
boolean

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

​
metadata
object

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

Response

OK

The order return details.

​
order
object
required

The order change's order.

​
return
object
required

The return's details.