Medusa

List Returns

GET

/admin/returns

Returns

Retrieve a list of Returns. The returns can be paginated.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request GET 'https://api.medusa-commerce.com/admin/returns'

Response Example

200 - Example 1

{
  "count": 0,
  "offset": 0,
  "limit": 0,
  "returns": [
    {
      "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"
              },
              "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"
                  }
                }
              ],
              "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"
                }
              ],
              "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"
                      },
                      "currency": {
                        "symbol": "$",
                        "symbol_native": "$",
                        "name": "US Dollar",
                        "includes_tax": false,
                        "code": "usd"
                      },
                      "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
                        }
                      ],
                      "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": [
                            {
                              "metadata": {}
                            }
                          ],
                          "shipping_options": [
                            {
                              "region": {},
                              "data": {},
                              "metadata": {},
                              "requirements": []
                            }
                          ],
                          "products": [
                            {
                              "metadata": {},
                              "images": [],
                              "categories": [],
                              "tags": [],
                              "profiles": [],
                              "sales_channels": [],
                              "options": [],
                              "variants": []
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Request

Query Params

limit

number

optional

Limit the number of Returns returned.

offset

number

optional

The number of Returns to skip when retrieving the Returns.

Responses

🟢200OK

application/json

Body

count

integer

required

The total number of items available

offset

integer

required

The number of returns skipped when retrieving the returns.

limit

integer

required

The number of items per page

returns

array[object (Return) {19}]

required

An array of returns details.

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.

🟠400Client Error or Multiple Errors

🟠401User is not authorized. Must log in first

🟠404Not Found Error

🟠409Invalid State Error

🟠422Invalid Request Error

🔴500Server Error

Modified at 2023-10-10 11:56:36

Receive a Return

Cancel a Return