Medusa Views API

openapi: 3.2.0
info:
  version: 2.19.0
  title: Medusa Admin Views API
  license:
    name: MIT
    url: https://github.com/medusajs/medusa/blob/develop/LICENSE
  description: 'A view configuration is a saved data-table view for an entity, such as products or orders. It lets admin users customize how a table shows its data, then save that customization as a reusable view.

    These API routes allow admin users to manage the system default and personal views.

    '
servers:
- url: http://localhost:9000
- url: https://api.medusajs.com
tags:
- name: Views
  description: 'A view configuration is a saved data-table view for an entity, such as products or orders. It lets admin users customize how a table shows its data, then save that customization as a reusable view.

    These API routes allow admin users to manage the system default and personal views.

    '
  externalDocs:
    description: Learn more about views configurations.
    url: https://docs.medusajs.com/resources/commerce-modules/settings/view-configurations
  x-associatedSchema:
    $ref: '#/components/schemas/AdminViewConfiguration'
paths:
  /admin/views/entities:
    get:
      operationId: GetViewsEntities
      summary: List Views
      description: Retrieve a list of views. The views can be filtered by fields such as `id`. The views can also be sorted or paginated.
      x-authenticated: true
      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.views.listEntities()\n.then(({ entities }) => {\n  console.log(entities)\n})"
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/views/entities'' \

          -H ''Authorization: Bearer {access_token}'''
      tags:
      - Views
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminEntityListResponse'
        '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'
      x-since: 2.10.3
      x-featureFlag: view_configurations
  /admin/views/{entity}/columns:
    get:
      operationId: GetViewsEntityColumns
      summary: List Columns in View
      x-sidebar-summary: List Columns
      description: Retrieve a list of columns in a view for an entity. The columns are retrieved for the authenticated admin user.
      x-authenticated: true
      parameters:
      - name: entity
        in: path
        description: The entity to retrieve its columns (for example, `orders`)
        required: true
        schema:
          type: string
      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\nconst { columns } = await sdk.admin.views.columns(\"orders\")"
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/views/{entity}/columns'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Views
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminViewsEntityColumnsResponse'
        '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'
      x-since: 2.10.3
      x-featureFlag: view_configurations
  /admin/views/{entity}/configurations:
    get:
      operationId: GetViewsEntityConfigurations
      summary: List View Configurations
      description: Retrieve a list of view configurations of an entity. The configurations can be filtered by fields like `id`. The configurations can also be paginated. An admin user can only retrieve their own configurations.
      x-authenticated: true
      parameters:
      - name: entity
        in: path
        description: The entity to retrieve its view configurations (for example, `orders`)
        required: true
        schema:
          type: string
      - 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 `-`.
          externalDocs:
            url: '#pagination'
      - 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: id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: id
            description: Filter by a view configuration ID.
          - type: array
            description: Filter by view configuration IDs.
            items:
              type: string
              title: id
              description: The view configuration ID.
      - name: entity
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: entity
            description: Filter by an entity.
          - type: array
            description: Filter by entities.
            items:
              type: string
              title: entity
              description: An entity.
      - name: name
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: name
            description: Filter by a view's name.
          - type: array
            description: Filter by view names.
            items:
              type: string
              title: name
              description: The view's name.
      - name: user_id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: user_id
            description: Filter by the ID of the user who owns the view.
          - type: array
            description: Filter by the IDs of users who own the view.
            items:
              type: string
              title: user_id
              description: The user ID.
      - name: is_system_default
        in: query
        description: Filter by whether the view is a system default.
        required: false
        schema:
          type: boolean
          title: is_system_default
          description: Whether the view is a system default.
      - name: created_at
        in: query
        description: Filter by a view configuration's creation date.
        required: false
        schema:
          type: object
          description: Filter by a view configuration'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 an exact match.
                items:
                  type: string
                  title: $eq
                  description: Filter by 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: Filter by values in this array.
            $nin:
              type: array
              description: Filter by values not in this array.
              items:
                type: string
                title: $nin
                description: Filter by values not in this array.
            $not:
              oneOf:
              - type: string
                title: $not
                description: Filter by values not matching the conditions in this parameter.
              - type: object
                description: Filter by values not matching the conditions in this parameter.
              - type: array
                description: Filter by values not matching the conditions in this parameter.
                items:
                  type: string
                  title: $not
                  description: Filter by values not matching the conditions in this parameter.
            $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: Filter arrays that have overlapping values with this parameter.
            $contains:
              type: array
              description: Filter arrays that contain some of the values of this parameter.
              items:
                type: string
                title: $contains
                description: Filter arrays that contain some of the values of this parameter.
            $contained:
              type: array
              description: Filter arrays that contain all values of this parameter.
              items:
                type: string
                title: $contained
                description: Filter arrays that contain all values of this parameter.
            $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 a view configuration's update date.
        required: false
        schema:
          type: object
          description: Filter by a view configuration'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 an exact match.
                items:
                  type: string
                  title: $eq
                  description: Filter by 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: Filter by values in this array.
            $nin:
              type: array
              description: Filter by values not in this array.
              items:
                type: string
                title: $nin
                description: Filter by values not in this array.
            $not:
              oneOf:
              - type: string
                title: $not
                description: Filter by values not matching the conditions in this parameter.
              - type: object
                description: Filter by values not matching the conditions in this parameter.
              - type: array
                description: Filter by values not matching the conditions in this parameter.
                items:
                  type: string
                  title: $not
                  description: Filter by values not matching the conditions in this parameter.
            $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: Filter arrays that have overlapping values with this parameter.
            $contains:
              type: array
              description: Filter arrays that contain some of the values of this parameter.
              items:
                type: string
                title: $contains
                description: Filter arrays that contain some of the values of this parameter.
            $contained:
              type: array
              description: Filter arrays that contain all values of this parameter.
              items:
                type: string
                title: $contained
                description: Filter arrays that contain all values of this parameter.
            $exists:
              type: boolean
              title: $exists
              description: Filter by whether a value for this parameter exists (not `null`).
          title: updated_at
      - 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: $and
        in: query
        description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
        required: false
        schema:
          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
      - name: $or
        in: query
        description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
        required: false
        schema:
          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
      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.views.listConfigurations(\"orders\")\n.then(({ view_configurations, count, limit, offset }) => {\n  console.log(view_configurations)\n})"
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/views/{entity}/configurations'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Views
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  description: The list of view configurations.
                  required:
                  - limit
                  - offset
                  - count
                  properties:
                    limit:
                      type: number
                      title: limit
                      description: The maximum number of returned items.
                    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.
                    estimate_count:
                      type: number
                      title: estimate_count
                      description: The estimated count retrieved from the PostgreSQL query planner, which may be inaccurate.
                      x-featureFlag: index_engine
                - type: object
                  description: The list of view configurations.
                  required:
                  - view_configurations
                  properties:
                    view_configurations:
                      type: array
                      description: The list of view configurations.
                      items:
                        $ref: '#/components/schemas/AdminViewConfiguration'
        '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'
      x-since: 2.10.3
      x-featureFlag: view_configurations
    post:
      operationId: PostViewsEntityConfigurations
      summary: Create View Configuration
      description: Create a new view configuration for an entity. If `is_system_default` is set to true, the created configuration will be set as the system default for the specified entity. Otherwise, it will be a custom configuration for the admin user.
      x-authenticated: true
      parameters:
      - name: entity
        in: path
        description: The entity to create its view configuration (for example, `orders`).
        required: true
        schema:
          type: string
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminCreateViewConfiguration'
      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\nconst { view_configuration } = await sdk.admin.views.createConfiguration(\n  \"orders\",\n  {\n    name: \"My Orders View\",\n    configuration: {\n      visible_columns: [\"display_id\", \"status\"],\n      column_order: [\"display_id\", \"status\"],\n    },\n  }\n)"
      - lang: Shell
        label: cURL
        source: "curl -X POST '{backend_url}/admin/views/{entity}/configurations' \\\n-H 'Authorization: Bearer {jwt_token}' \\\n-H 'Content-Type: application/json' \\\n-d '{\n  \"is_system_default\": true,\n  \"name\": \"Custom View\"\n}'"
      tags:
      - Views
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminViewConfigurationResponse'
        '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'
      x-workflow: createViewConfigurationWorkflow
      x-events: []
      x-since: 2.10.3
      x-featureFlag: view_configurations
  /admin/views/{entity}/configurations/active:
    get:
      operationId: GetViewsEntityConfigurationsActive
      summary: Get Active View Configuration
      description: Get the active view configurations for an entity. If no active view is set, `null` is returned. An admin user can only retrieve their own active configuration.
      x-authenticated: true
      parameters:
      - name: entity
        in: path
        description: The entity to retrieve its active view configurations (for example, `orders`).
        required: true
        schema:
          type: string
      - 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: []
      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.views.retrieveActiveConfiguration(\"orders\")\n.then(({ view_configuration, active_view_configuration_id }) => {\n  console.log(view_configuration)\n})"
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/views/{entity}/configurations/active'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Views
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/AdminViewConfigurationResponse'
                - type: object
                  description: Additional properties related to the active view configuration.
                  properties:
                    is_default_active:
                      type: boolean
                      title: is_default_active
                      description: Whether the active view configuration is the system default.
                    default_type:
                      type: string
                      description: The type of the default view configuration if the active view is the system default. It will be `system` if the active view is the system default, `code` if no active view is set, or `undefined` if the active view isn't the system default.
                      enum:
                      - code
                      - system
        '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'
      x-since: 2.10.3
      x-featureFlag: view_configurations
    post:
      operationId: PostViewsEntityConfigurationsActive
      summary: Make View Configuration Active
      description: Make a view configuration active. This will set the given view configuration as the active one for the specified entity for the admin user. An admin user can only set their own configurations as active. If the view configuration ID is `null`, the active view configuration will be cleared, and the `code` or system default view configuration type will be used as the active view.
      x-authenticated: true
      parameters:
      - name: entity
        in: path
        description: The entity to update its view configuration (for example, `orders`).
        required: true
        schema:
          type: string
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminSetActiveViewConfiguration'
      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\nawait sdk.admin.views.setActiveConfiguration(\"orders\", {\n  view_configuration_id: \"viewconfig_123\",\n})"
      - lang: Shell
        label: cURL
        source: "curl -X POST '{backend_url}/admin/views/{entity}/configurations/active' \\\n-H 'Authorization: Bearer {jwt_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n  \"view_configuration_id\": \"{value}\"\n}'"
      tags:
      - Views
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: The details of the operation.
                required:
                - success
                properties:
                  success:
                    type: boolean
                    title: success
                    description: Whether the operation was successful.
        '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'
      x-since: 2.10.3
      x-featureFlag: view_configurations
  /admin/views/{entity}/configurations/{id}:
    get:
      operationId: GetViewsEntityConfigurationsId
      summary: Get View Configuration
      description: Retrieve a view configuration for an entity. An admin user can only retrieve their own configurations.
      x-authenticated: true
      parameters:
      - name: entity
        in: path
        description: The entity to retrieve its view configurations (for example, `orders`)
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: The ID of the view configuration to retrieve.
        required: true
        schema:
          type: string
      - 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:

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