Menu

Views API Routes

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.

GET /admin/views/entities#

List Views

Retrieve a list of views. The views can be filtered by fields such as id. The views can also be sorted or paginated.

Feature flag: This API route is only available when the view_configurations feature flag is enabled. Set the MEDUSA_FF_VIEW_CONFIGURATIONS environment variable to true to enable it.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Request examples

Responses

200 OK

entitiesobject[]
The list of entities.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/views/{entity}/columns#

List Columns in View

Retrieve a list of columns in a view for an entity. The columns are retrieved for the authenticated admin user.

Feature flag: This API route is only available when the view_configurations feature flag is enabled. Set the MEDUSA_FF_VIEW_CONFIGURATIONS environment variable to true to enable it.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

entitystring
The entity to retrieve its columns (for example, orders)

Request examples

Responses

200 OK

columnsobject[]
The view's columns.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/views/{entity}/configurations#

List View Configurations

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.

Feature flag: This API route is only available when the view_configurations feature flag is enabled. Set the MEDUSA_FF_VIEW_CONFIGURATIONS environment variable to true to enable it.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

entitystring
The entity to retrieve its view configurations (for example, orders)

Query parameters

offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
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 -.
with_deletedbooleanOptional
Whether to include deleted records in the result.
idstring | string[]Optional
Filter by a view configuration ID.
entitystring | string[]Optional
Filter by an entity.
namestring | string[]Optional
Filter by a view's name.
user_idstring | string[]Optional
Filter by the ID of the user who owns the view.
is_system_defaultbooleanOptional
Filter by whether the view is a system default.
created_atobjectOptional
Filter by a view configuration's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a view configuration's update date. Accepts the filter operators.
fieldsstringOptional
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.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.

Request examples

Responses

200 OK

limitnumber
The maximum number of returned items.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items.
estimate_countnumberOptional
The estimated count retrieved from the PostgreSQL query planner, which may be inaccurate.
view_configurationsobject[]
The list of view configurations.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/views/{entity}/configurations#

Create View Configuration

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.

Feature flag: This API route is only available when the view_configurations feature flag is enabled. Set the MEDUSA_FF_VIEW_CONFIGURATIONS environment variable to true to enable it.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

entitystring
The entity to create its view configuration (for example, orders).

Request body (application/json)

is_system_defaultbooleanOptional
Whether the view is the system default. If so, it will be used as the default view for all users that don't have a custom active view set.
set_activebooleanOptional
Whether the view is set as active.
configurationobjectOptional
The view's configuration.
namestringOptional
The view's name.

Request examples

Responses

200 OK

view_configurationobject
The details of a view configuration.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/views/{entity}/configurations/active#

Get Active View Configuration

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.

Feature flag: This API route is only available when the view_configurations feature flag is enabled. Set the MEDUSA_FF_VIEW_CONFIGURATIONS environment variable to true to enable it.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

entitystring
The entity to retrieve its active view configurations (for example, orders).

Query parameters

fieldsstringOptional
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.

Request examples

Responses

200 OK

view_configurationobject
The details of a view configuration.
is_default_activebooleanOptional
Whether the active view configuration is the system default.
default_type"code" | "system"Optional
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.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/views/{entity}/configurations/active#

Make View Configuration Active

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.

Feature flag: This API route is only available when the view_configurations feature flag is enabled. Set the MEDUSA_FF_VIEW_CONFIGURATIONS environment variable to true to enable it.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

entitystring
The entity to update its view configuration (for example, orders).

Request body (application/json)

view_configuration_idstring
The ID of the view configuration to set as active. If null, the active view configuration will be cleared, and the code or system default view configuration will be used as the active view.

Request examples

Responses

200 OK

successboolean
Whether the operation was successful.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/views/{entity}/configurations/{id}#

Get View Configuration

Retrieve a view configuration for an entity. An admin user can only retrieve their own configurations.

Feature flag: This API route is only available when the view_configurations feature flag is enabled. Set the MEDUSA_FF_VIEW_CONFIGURATIONS environment variable to true to enable it.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

entitystring
The entity to retrieve its view configurations (for example, orders)
idstring
The ID of the view configuration to retrieve.

Query parameters

fieldsstringOptional
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.

Request examples

Responses

200 OK

view_configurationobject
The details of a view configuration.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/views/{entity}/configurations/{id}#

Update View Configuration

Update the view configuration of an entity. An admin user can only update their own configurations.

Feature flag: This API route is only available when the view_configurations feature flag is enabled. Set the MEDUSA_FF_VIEW_CONFIGURATIONS environment variable to true to enable it.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

entitystring
The entity to update its view configuration (for example, orders).
idstring
The view configuration's ID.

Request body (application/json)

set_activebooleanOptional
Whether the view is set as active.
namestringOptional
The view's name.
is_system_defaultbooleanOptional
Whether the view is the system default.
configurationobjectOptional
The view's configuration.

Request examples

Responses

200 OK

view_configurationobject
The details of a view configuration.

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /admin/views/{entity}/configurations/{id}#

Remove View Configurations

Remove view configurations of an entity. An admin user can only delete their own configurations.

Feature flag: This API route is only available when the view_configurations feature flag is enabled. Set the MEDUSA_FF_VIEW_CONFIGURATIONS environment variable to true to enable it.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

entitystring
The entity to delete its view configuration (for example, orders)
idstring
The ID of the view configuration to delete

Request examples

Responses

200 OK

idstring
The ID of the deleted View Configuration.
objectstring
The name of the deleted object.
Example: view_configuration
deletedboolean
Whether the view was deleted.

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page