Medusa Returns API

openapi: 3.2.0
info:
  title: Medusa Returns API
  version: 2.19.0
  description: 'Operations tagged Returns across 2 of this provider''s published API definitions: medusa-admin-openapi.yaml, medusa-store-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://localhost:9000
- url: https://api.medusajs.com
tags:
- name: Returns
  description: 'Admin users create a return when a customer returns an item to them.


    Returns can also be created by customers through the storefront, and admins will be able to manage them and make refunds, if necessary. Refunds are made through the [Payment API Routes](#payment)


    These API routes allow admin users to manage returns.

    '
  externalDocs:
    description: Learn more about order returns.
    url: https://docs.medusajs.com/resources/commerce-modules/order/return
  x-associatedSchema:
    $ref: '#/components/schemas/AdminReturn'
paths:
  /admin/returns:
    get:
      operationId: GetReturns
      summary: List Returns
      description: Retrieve a list of returns. The returns can be filtered by fields such as `id`. The returns can also be sorted or paginated.
      x-authenticated: true
      parameters:
      - name: fields
        in: query
        description: 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.
        required: false
        schema:
          type: string
          title: fields
          description: 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.
          externalDocs:
            url: '#select-fields-and-relations'
      - name: offset
        in: query
        description: The number of items to skip when retrieving a list.
        required: false
        schema:
          type: number
          title: offset
          description: The number of items to skip when retrieving a list.
          externalDocs:
            url: '#pagination'
      - name: limit
        in: query
        description: Limit the number of items returned in the list.
        required: false
        schema:
          type: number
          title: limit
          description: Limit the number of items returned in the list.
          externalDocs:
            url: '#pagination'
      - name: order
        in: query
        description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
        required: false
        schema:
          type: string
          title: order
          description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
      - name: id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: id
            description: Filter by a return's ID.
          - type: array
            description: Filter by return IDs.
            items:
              type: string
              title: id
              description: A return ID.
      - name: status
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: status
            description: Filter by a return status.
          - type: array
            description: Filter by return statuses.
            items:
              type: string
              title: status
              description: A return status.
      - name: created_at
        in: query
        description: Filter by the return's creation date.
        required: false
        schema:
          type: object
          description: Filter by the return's creation date.
          properties:
            $and:
              type: array
              description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
              items:
                type: object
              title: $and
            $or:
              type: array
              description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
              items:
                type: object
              title: $or
            $eq:
              oneOf:
              - type: string
                title: $eq
                description: Filter by an exact match.
              - type: array
                description: Filter by multiple exact matches.
                items:
                  type: string
                  title: $eq
                  description: An exact match.
            $ne:
              type: string
              title: $ne
              description: Filter by values not equal to this parameter.
            $in:
              type: array
              description: Filter by values in this array.
              items:
                type: string
                title: $in
                description: The value to match.
            $nin:
              type: array
              description: Filter by values not in this array.
              items:
                type: string
                title: $nin
                description: The value not to match.
            $not:
              oneOf:
              - type: string
                title: $not
                description: Filter by values not matching this parameter.
              - type: object
                description: Filter by values not matching the conditions in this parameter.
                properties:
                  $and:
                    type: array
                    description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
                    items:
                      type: object
                    title: $and
                  $or:
                    type: array
                    description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
                    items:
                      type: object
                    title: $or
                  $eq:
                    oneOf:
                    - type: string
                      title: $eq
                      description: Filter by an exact match.
                    - type: array
                      description: Filter by multiple exact matches.
                      items:
                        type: string
                        title: $eq
                        description: The value to match.
                  $ne:
                    type: string
                    title: $ne
                    description: Filter by values not matching this parameter.
                  $in:
                    type: array
                    description: Filter by values in this array.
                    items:
                      type: string
                      title: $in
                      description: The value to match.
                  $nin:
                    type: array
                    description: Filter by values not in this array.
                    items:
                      type: string
                      title: $nin
                      description: The value to not match
                  $not:
                    oneOf:
                    - type: string
                      title: $not
                      description: Filter by values not matching this parameter
                    - type: object
                      description: Filter by values not matching the conditions in this parameter.
                    - type: array
                      description: Filter by values not matching the values of this parameter.
                      items:
                        type: string
                        title: $not
                        description: The values to not match.
                  $gt:
                    type: string
                    title: $gt
                    description: Filter by values greater than this parameter. Useful for numbers and dates only.
                  $gte:
                    type: string
                    title: $gte
                    description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
                  $lt:
                    type: string
                    title: $lt
                    description: Filter by values less than this parameter. Useful for numbers and dates only.
                  $lte:
                    type: string
                    title: $lte
                    description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
                  $like:
                    type: string
                    title: $like
                    description: Apply a `like` filter. Useful for strings only.
                  $re:
                    type: string
                    title: $re
                    description: Apply a regex filter. Useful for strings only.
                  $ilike:
                    type: string
                    title: $ilike
                    description: Apply a case-insensitive `like` filter. Useful for strings only.
                  $fulltext:
                    type: string
                    title: $fulltext
                    description: Filter to apply on full-text properties.
                  $overlap:
                    type: array
                    description: Filter arrays that have overlapping values with this parameter.
                    items:
                      type: string
                      title: $overlap
                      description: The value to match.
                  $contains:
                    type: array
                    description: Filter arrays that contain some of the values of this parameter.
                    items:
                      type: string
                      title: $contains
                      description: The values to match.
                  $contained:
                    type: array
                    description: Filter arrays that contain all values of this parameter.
                    items:
                      type: string
                      title: $contained
                      description: The values to match.
                  $exists:
                    type: boolean
                    title: $exists
                    description: Filter by whether a value for this parameter exists (not `null`).
              - type: array
                description: Filter by values not matching those in this parameter.
                items:
                  type: string
                  title: $not
                  description: The values to not match.
            $gt:
              type: string
              title: $gt
              description: Filter by values greater than this parameter. Useful for numbers and dates only.
            $gte:
              type: string
              title: $gte
              description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
            $lt:
              type: string
              title: $lt
              description: Filter by values less than this parameter. Useful for numbers and dates only.
            $lte:
              type: string
              title: $lte
              description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
            $like:
              type: string
              title: $like
              description: Apply a `like` filter. Useful for strings only.
            $re:
              type: string
              title: $re
              description: Apply a regex filter. Useful for strings only.
            $ilike:
              type: string
              title: $ilike
              description: Apply a case-insensitive `like` filter. Useful for strings only.
            $fulltext:
              type: string
              title: $fulltext
              description: Filter to apply on full-text properties.
            $overlap:
              type: array
              description: Filter arrays that have overlapping values with this parameter.
              items:
                type: string
                title: $overlap
                description: The values to match.
            $contains:
              type: array
              description: Filter arrays that contain some of the values of this parameter.
              items:
                type: string
                title: $contains
                description: The values to match.
            $contained:
              type: array
              description: Filter arrays that contain all values of this parameter.
              items:
                type: string
                title: $contained
                description: The values to match.
            $exists:
              type: boolean
              title: $exists
              description: Filter by whether a value for this parameter exists (not `null`).
          title: created_at
      - name: updated_at
        in: query
        description: Filter by the return's update date.
        required: false
        schema:
          type: object
          description: Filter by the return's update date.
          properties:
            $and:
              type: array
              description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
              items:
                type: object
              title: $and
            $or:
              type: array
              description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
              items:
                type: object
              title: $or
            $eq:
              oneOf:
              - type: string
                title: $eq
                description: Filter by an exact match.
              - type: array
                description: Filter by multiple exact matches.
                items:
                  type: string
                  title: $eq
                  description: An exact match.
            $ne:
              type: string
              title: $ne
              description: Filter by values not equal to this parameter.
            $in:
              type: array
              description: Filter by values in this array.
              items:
                type: string
                title: $in
                description: The value to match.
            $nin:
              type: array
              description: Filter by values not in this array.
              items:
                type: string
                title: $nin
                description: The value not to match.
            $not:
              oneOf:
              - type: string
                title: $not
                description: Filter by values not matching this parameter.
              - type: object
                description: Filter by values not matching the conditions in this parameter.
                properties:
                  $and:
                    type: array
                    description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
                    items:
                      type: object
                    title: $and
                  $or:
                    type: array
                    description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
                    items:
                      type: object
                    title: $or
                  $eq:
                    oneOf:
                    - type: string
                      title: $eq
                      description: Filter by an exact match.
                    - type: array
                      description: Filter by multiple exact matches.
                      items:
                        type: string
                        title: $eq
                        description: The value to match.
                  $ne:
                    type: string
                    title: $ne
                    description: Filter by values not matching this parameter.
                  $in:
                    type: array
                    description: Filter by values in this array.
                    items:
                      type: string
                      title: $in
                      description: The value to match.
                  $nin:
                    type: array
                    description: Filter by values not in this array.
                    items:
                      type: string
                      title: $nin
                      description: The value to not match
                  $not:
                    oneOf:
                    - type: string
                      title: $not
                      description: Filter by values not matching this parameter
                    - type: object
                      description: Filter by values not matching the conditions in this parameter.
                    - type: array
                      description: Filter by values not matching the values of this parameter.
                      items:
                        type: string
                        title: $not
                        description: The values to not match.
                  $gt:
                    type: string
                    title: $gt
                    description: Filter by values greater than this parameter. Useful for numbers and dates only.
                  $gte:
                    type: string
                    title: $gte
                    description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
                  $lt:
                    type: string
                    title: $lt
                    description: Filter by values less than this parameter. Useful for numbers and dates only.
                  $lte:
                    type: string
                    title: $lte
                    description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
                  $like:
                    type: string
                    title: $like
                    description: Apply a `like` filter. Useful for strings only.
                  $re:
                    type: string
                    title: $re
                    description: Apply a regex filter. Useful for strings only.
                  $ilike:
                    type: string
                    title: $ilike
                    description: Apply a case-insensitive `like` filter. Useful for strings only.
                  $fulltext:
                    type: string
                    title: $fulltext
                    description: Filter to apply on full-text properties.
                  $overlap:
                    type: array
                    description: Filter arrays that have overlapping values with this parameter.
                    items:
                      type: string
                      title: $overlap
                      description: The value to match.
                  $contains:
                    type: array
                    description: Filter arrays that contain some of the values of this parameter.
                    items:
                      type: string
                      title: $contains
                      description: The values to match.
                  $contained:
                    type: array
                    description: Filter arrays that contain all values of this parameter.
                    items:
                      type: string
                      title: $contained
                      description: The values to match.
                  $exists:
                    type: boolean
                    title: $exists
                    description: Filter by whether a value for this parameter exists (not `null`).
              - type: array
                description: Filter by values not matching those in this parameter.
                items:
                  type: string
                  title: $not
                  description: The values to not match.
            $gt:
              type: string
              title: $gt
              description: Filter by values greater than this parameter. Useful for numbers and dates only.
            $gte:
              type: string
              title: $gte
              description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
            $lt:
              type: string
              title: $lt
              description: Filter by values less than this parameter. Useful for numbers and dates only.
            $lte:
              type: string
              title: $lte
              description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
            $like:
              type: string
              title: $like
              description: Apply a `like` filter. Useful for strings only.
            $re:
              type: string
              title: $re
              description: Apply a regex filter. Useful for strings only.
            $ilike:
              type: string
              title: $ilike
              description: Apply a case-insensitive `like` filter. Useful for strings only.
            $fulltext:
              type: string
              title: $fulltext
              description: Filter to apply on full-text properties.
            $overlap:
              type: array
              description: Filter arrays that have overlapping values with this parameter.
              items:
                type: string
                title: $overlap
                description: The values to match.
            $contains:
              type: array
              description: Filter arrays that contain some of the values of this parameter.
              items:
                type: string
                title: $contains
                description: The values to match.
            $contained:
              type: array
              description: Filter arrays that contain all values of this parameter.
              items:
                type: string
                title: $contained
                description: The values to match.
            $exists:
              type: boolean
              title: $exists
              description: Filter by whether a value for this parameter exists (not `null`).
          title: updated_at
      - name: with_deleted
        in: query
        description: Whether to include deleted records in the result.
        required: false
        schema:
          type: boolean
          title: with_deleted
          description: Whether to include deleted records in the result.
      - name: order_id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: order_id
            description: Filter by the return's order ID.
          - type: array
            description: Filter by return order IDs.
            items:
              type: string
              title: order_id
              description: The return's order ID.
          - type: object
            properties:
              $and:
                type: array
                description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
                items:
                  type: object
              $or:
                type: array
                description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
                items:
                  type: object
              $eq:
                oneOf:
                - type: string
                  title: $eq
                  description: Filter by exact value.
                - type: array
                  title: $eq
                  description: Filter by exact value.
                  items:
                    type: string
              $ne:
                type: string
                title: $ne
                description: Filter by not equal to the given value.
              $in:
                type: array
                title: $in
                description: Filter by values included in the given array.
                items:
                  type: string
              $nin:
                type: array
                title: $nin
                description: Filter by values not included in the given array.
                items:
                  type: string
              $not:
                oneOf:
                - type: string
                  title: $not
                  description: Filter by not equal to the given value.
                - type: object
                  title: $not
                  description: Filter by values not matching the conditions in this parameter.
                - type: array
                  title: $not
                  description: Filter by values not matching the conditions in this parameter.
                  items:
                    type: string
              $gt:
                type: string
                title: $gt
                description: Filter by values greater than the given value.
              $gte:
                type: string
                title: $gte
                description: Filter by values greater than or equal to the given value.
              $lt:
                type: string
                title: $lt
                description: Filter by values less than the given value.
              $lte:
                type: string
                title: $lte
                description: Filter by values less than or equal to the given value.
              $like:
                type: string
                title: $like
                description: Apply a `like` filter. Useful for strings only.
              $re:
                type: string
                title: $re
                description: Apply a regex filter. Useful for strings only.
              $ilike:
                type: string
                title: $ilike
                description: Apply a case-insensitive `like` filter. Useful for strings only.
              $fulltext:
                type: string
                title: $fulltext
                description: Filter to apply on full-text properties.
              $overlap:
                type: array
                title: $overlap
                description: Filter to apply on array properties to find overlapping values.
                items:
                  type: string
              $contains:
                type: array
                title: $contains
                description: Filter to apply on array properties to find contained values.
                items:
                  type: string
              $contained:
                type: array
                title: $contained
                description: Filter to apply on array properties to find contained values.
                items:
                  type: string
              $exists:
                type: boolean
                title: $exists
                description: Filter by whether a value exists or not.
            title: order_id
            description: The return's order id.
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      x-codeSamples:
      - lang: JavaScript
        label: JS SDK
        source: "import Medusa from \"@medusajs/js-sdk\"\n\nexport const sdk = new Medusa({\n  baseUrl: import.meta.env.VITE_BACKEND_URL || \"/\",\n  debug: import.meta.env.DEV,\n  auth: {\n    type: \"session\",\n  },\n})\n\nsdk.admin.return.list()\n.then(({ returns, count, limit, offset }) => {\n  console.log(returns)\n})"
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/returns'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Returns
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  description: The paginated list of returns.
                  required:
                  - limit
                  - offset
                  - count
                  properties:
                    limit:
                      type: number
                      title: limit
                      description: The maximum number of items returned.
                    offset:
                      type: number
                      title: offset
                      description: The number of items skipped before retrieving the returned items.
                    count:
                      type: number
                      title: count
                      description: The total number of items.
                - type: object
                  description: The paginated list of returns.
                  required:
                  - returns
                  properties:
                    returns:
                      type: array
                      description: The return's returns.
                      items:
                        $ref: '#/components/schemas/AdminReturn'
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
    post:
      operationId: PostReturns
      summary: Create Return
      description: Create a return. The return can later be requested or confirmed.
      x-authenticated: true
      parameters:
      - name: fields
        in: query
        description: 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.
        required: false
        schema:
          type: string
          title: fields
          description: 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.
          externalDocs:
            url: '#select-fields-and-relations'
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminInitiateReturnRequest'
      x-codeSamples:
      - lang: JavaScript
        label: JS SDK
        source: "import Medusa from \"@medusajs/js-sdk\"\n\nexport const sdk = new Medusa({\n  baseUrl: import.meta.env.VITE_BACKEND_URL || \"/\",\n  debug: import.meta.env.DEV,\n  auth: {\n    type: \"session\",\n  },\n})\n\nsdk.admin.return.initiateRequest({\n  order_id: \"order_123\",\n})\n.then(({ return }) => {\n  console.log(return)\n})"
      - lang: Shell
        label: cURL
        source: "curl -X POST '{backend_url}/admin/returns' \\\n-H 'Authorization: Bearer {jwt_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n  \"order_id\": \"{value}\",\n  \"items\": [\n    {\n      \"id\": \"id_7DO5H2LbSN3p7IzB\",\n      \"quantity\": 1357590174892032,\n      \"reason_id\": \"{value}\",\n      \"note\": \"{value}\"\n    }\n  ],\n  \"return_shipping\": {\n    \"option_id\": \"{value}\",\n    \"price\": 5112171463704576\n  },\n  \"internal_note\": \"{value}\",\n  \"location_id\": \"{value}\"\n}'"
      tags:
      - Returns
      responses:
        '200':
          description: OK
          con

# --- truncated at 32 KB (448 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/medusa/refs/heads/main/openapi/medusa-returns-api-openapi.yml