Medusa Invites API

openapi: 3.2.0
info:
  version: 2.19.0
  title: Medusa Admin Invites API
  license:
    name: MIT
    url: https://github.com/medusajs/medusa/blob/develop/LICENSE
  description: 'An admin can invite new users to manage their team. This allows new users to authenticate as admins and perform admin functionalities.


    These API routes allow admin users to manage invites.

    '
servers:
- url: http://localhost:9000
- url: https://api.medusajs.com
tags:
- name: Invites
  description: 'An admin can invite new users to manage their team. This allows new users to authenticate as admins and perform admin functionalities.


    These API routes allow admin users to manage invites.

    '
  externalDocs:
    description: Learn more about the User Module
    url: https://docs.medusajs.com/resources/commerce-modules/user
  x-associatedSchema:
    $ref: '#/components/schemas/AdminInvite'
paths:
  /admin/invites:
    get:
      operationId: GetInvites
      summary: List Invites
      description: Retrieve a list of invites. The invites can be filtered by fields such as `id`. The invites 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: q
        in: query
        description: Search term to apply on an invite's searchable properties.
        required: false
        schema:
          type: string
          title: q
          description: Search term to apply on an invite's searchable properties.
      - name: id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: id
            description: Filter by an invite's ID.
          - type: array
            description: Filter by invite IDs.
            items:
              type: string
              title: id
              description: An invite's ID.
      - name: email
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: email
            description: Filter by an invite's email.
            format: email
          - type: array
            description: Filter by invite emails.
            items:
              type: string
              title: email
              description: An email.
              format: email
      - name: created_at
        in: query
        description: Filter by the invite's creation date.
        required: false
        schema:
          type: object
          description: Filter by the invite'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 the invite's update date.
        required: false
        schema:
          type: object
          description: Filter by the invite'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: deleted_at
        in: query
        description: Filter by the invite's deletion date.
        required: false
        schema:
          type: object
          description: Filter by the invite's deletion 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: deleted_at
      - name: $and
        in: query
        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
        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
      - 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.
      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.invite.list()\n.then(({ invites, count, limit, offset }) => {\n  console.log(invites)\n})"
      - lang: Shell
        label: cURL
        source: curl '{backend_url}/admin/invites'
      tags:
      - Invites
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  description: The paginated list of invites.
                  required:
                  - limit
                  - offset
                  - count
                  properties:
                    limit:
                      type: number
                      title: limit
                      description: The maximum number of items retrieved.
                    offset:
                      type: number
                      title: offset
                      description: The number of items skipped before the returned items.
                    count:
                      type: number
                      title: count
                      description: The total number of items.
                - type: object
                  description: The paginated list of invites.
                  required:
                  - invites
                  properties:
                    invites:
                      type: array
                      description: The list of invites.
                      items:
                        $ref: '#/components/schemas/AdminInvite'
        '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'
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
    post:
      operationId: PostInvites
      summary: Create Invite
      description: Create a invite.
      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'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: The invite's details.
              required:
              - email
              properties:
                email:
                  type: string
                  title: email
                  description: The email of the user to invite.
                  format: email
                metadata:
                  type: object
                  description: The invite's metadata. Can be custom data in key-value pairs.
                roles:
                  type: array
                  description: The invited user's roles.
                  x-featureFlag: rbac
                  items:
                    type: string
                    title: roles
                    description: The invited user's role.
      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.invite.create({\n  email: \"user@gmail.com\",\n})\n.then(({ invite }) => {\n  console.log(invite)\n})"
      - lang: Shell
        label: cURL
        source: "curl -X POST '{backend_url}/admin/invites' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n  \"email\": \"Whitney_Schultz@gmail.com\"\n}'"
      tags:
      - Invites
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminInviteResponse'
        '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: createInvitesWorkflow
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      x-events:
      - name: invite.created
        payload: "```ts\n{\n  id, // The ID of the invite\n}\n```"
        description: 'Emitted when invites are created. You can listen to this event

          to send an email to the invited users, for example.'
        deprecated: false
  /admin/invites/accept:
    post:
      operationId: PostInvitesAccept
      summary: Accept Invite
      description: 'Accept an invite and create a new user.

        Since the user isn''t created yet, the JWT token used in the authorization header is retrieved from the `/auth/user/emailpass/register` API route (or a provider other than `emailpass`). The user can then authenticate using the `/auth/user/emailpass` API route.

        '
      x-authenticated: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminGetInviteAcceptParams'
      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.auth.register(\"user\", \"emailpass\", {\n  email: \"user@gmail.com\",\n  password: \"supersecret\"\n})\n\n// all subsequent requests will use the token in the header\nconst { user } = await sdk.admin.invite.accept(\n  {\n    email: \"user@gmail.com\",\n    first_name: \"John\",\n    last_name: \"Smith\",\n    invite_token: \"12345...\"\n  },\n)"
      - lang: Shell
        label: cURL
        source: "curl -X POST '{backend_url}/admin/invites/accept?token={invite_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n  \"email\": \"Lila_Zemlak@hotmail.com\",\n  \"first_name\": \"{value}\",\n  \"last_name\": \"{value}\"\n}'"
      tags:
      - Invites
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  description: The created user's details.
                  required:
                  - user
                  properties:
                    user:
                      $ref: '#/components/schemas/AdminUser'
                - type: object
                  description: An error's details.
                  required:
                  - message
                  properties:
                    message:
                      type: string
                      title: message
                      description: The error message.
        '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: acceptInviteWorkflow
      security:
      - cookie_auth: []
      - jwt_token: []
      x-events:
      - name: user.created
        payload: "```ts\n{\n  id, // The ID of the user\n}\n```"
        description: Emitted when users are created.
        deprecated: false
      - name: invite.accepted
        payload: "```ts\n{\n  id, // The ID of the invite\n}\n```"
        description: Emitted when an invite is accepted.
        deprecated: false
      parameters:
      - name: token
        in: query
        description: The invite's token.
        required: true
        schema:
          type: string
          title: token
          description: The invite's token.
      - 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'
  /admin/invites/{id}:
    get:
      operationId: GetInvitesId
      summary: Get an Invite
      description: Retrieve an invite by its ID. You can expand the invite's relations or select the fields that should be returned.
      x-authenticated: true
      parameters:
      - name: id
        in: path
        description: The invite's ID.
        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'
      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.invite.retrieve(\"invite_123\")\n.then(({ invite }) => {\n  console.log(invite)\n})"
      - lang: Shell
        label: cURL
        source: curl '{backend_url}/admin/invites/{id}'
      tags:
      - Invites
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminInviteResponse'
        '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'
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
    delete:
      operationId: DeleteInvitesId
      summary: Delete Invite
      description: Delete an invite.
      x-authenticated: true
      parameters:
      - name: id
        in: path
        description: The invite's ID.
        required: true
        schema:
          type: string
      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.invite.delete(\"invite_123\")\n.then(({ deleted }) => {\n  console.log(deleted)\n})"
      - lang: Shell
        label: cURL
        source: curl -X DELETE '{backend_url}/admin/invites/{id}'
      tags:
      - Invites
      responses:
        '200':
          description: OK
          content:
     

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