medusa-store/www/apps/docs/content/modules/users/admin/manage-invites.mdx

---
description: 'Learn how to manage invites using the admin API. This includes listing, creating, accepting, resending, and deleting invites.'
addHowToData: true
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# How to Manage Invites

In this document, you’ll learn how to manage invites using the admin API.

## Overview

You can use the invites admin API to manage and perform functionalities related to invites.

### Scenario

You want to add or use the following admin functionalities:

- List invites
- Create an invite
- Accept an invite
- Resend an invite
- Delete an invite

---

## Prerequisites

### Medusa Components

It is assumed that you already have a Medusa backend installed and set up. If not, you can follow the [quickstart guide](../../../development/backend/install.mdx) to get started.

### JS Client

This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods.

If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration).

### Medusa React

This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.

If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../../medusa-react/overview.mdx) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.mdx#usage).

### Authenticated Admin User

Except for the Accept Invite API Route, you must be an authenticated admin user before following along with the steps in the tutorial.

You can learn more about [authenticating as an admin user in the API reference](https://docs.medusajs.com/api/admin#authentication).

---

## List Invites

You can list invites by sending a request to the [List Invite API Route](https://docs.medusajs.com/api/admin#invites_getinvites):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

    ```ts
    medusa.admin.invites.list()
    .then(({ invites }) => {
      console.log(invites.length)
    })
    ```

  </TabItem>
  <TabItem value="medusa-react" label="Medusa React">

    ```tsx
    import { useAdminInvites } from "medusa-react"

    const Invites = () => {
      const { invites, isLoading } = useAdminInvites()

      return (
        <div>
          {isLoading && <span>Loading...</span>}
          {invites && !invites.length && (
            <span>No Invites</span>
          )}
          {invites && invites.length > 0 && (
            <ul>
              {invites.map((invite) => (
                <li key={invite.id}>{invite.user_email}</li>
              ))}
            </ul>
          )}
        </div>
      )
    }

    export default Invites
    ```

  </TabItem>
  <TabItem value="fetch" label="Fetch API">

    ```ts
    fetch(`<BACKEND_URL>/admin/invites`, {
      credentials: "include",
    })
    .then((response) => response.json())
    .then(({ invites }) => {
      console.log(invites.length)
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X GET '<BACKEND_URL>/admin/invites' \
    -H 'x-medusa-access-token: <API_TOKEN>'
    ```

  </TabItem>
</Tabs>

This API Route doesn't accept any parameters.

The request returns an array of invite objects.

---

## Create Invite

You can create an invite by sending a request to the [Create Invite API Route](https://docs.medusajs.com/api/admin#invites_postinvites):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

    ```ts
    medusa.admin.invites.create({
      user: "user@example.com",
      role: "admin",
    })
    .then(() => {
      // successful
    })
    ```

  </TabItem>
  <TabItem value="medusa-react" label="Medusa React">

    ```tsx
    import { useAdminCreateInvite } from "medusa-react"

    const CreateInvite = () => {
      const createInvite = useAdminCreateInvite()
      // ...

      const handleCreate = () => {
        createInvite.mutate({
          user: "user@example.com",
          role: "admin",
        })
      }

      // ...
    }

    export default CreateInvite
    ```

  </TabItem>
  <TabItem value="fetch" label="Fetch API">

    ```ts
    fetch(`<BACKEND_URL>/admin/invites`, {
      credentials: "include",
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        user: "user@example.com",
        role: "admin",
      }),
    })
    .then((response) => response.json())
    .then(() => {
      // successful
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X POST '<BACKEND_URL>/admin/invites' \
    -H 'x-medusa-access-token: <API_TOKEN>' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "user": "user@example.com",
        "role": "admin"
    }'
    ```

  </TabItem>
</Tabs>

This API Route requires the following body parameters:

- `user`: a string indicating the email of the user.
- `role`: a string indicating the role of the user. Its values can be `admin`, `member`, and `developer`.

The request does not return any data. If the invite was created successfully, the status code of the response will be `200`.

---

## Accept an Invite

A logged-out user can accept an invite, which would create a user for that user.

You can accept an invite by sending a request to the [Accept Invite API Route](https://docs.medusajs.com/api/admin#invites_postinvitesinviteaccept):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

    ```ts
    medusa.admin.invites.accept({
      token,
      user: {
        first_name: "Brigitte",
        last_name: "Collier",
        password: "supersecret",
      },
    })
    .then(() => {
      // successful
    })
    ```

  </TabItem>
  <TabItem value="medusa-react" label="Medusa React">

    ```tsx
    import { useAdminAcceptInvite } from "medusa-react"

    const AcceptInvite = () => {
      const acceptInvite = useAdminAcceptInvite()
      // ...

      const handleAccept = (
        token: string,
        firstName: string,
        lastName: string,
        password: string
      ) => {
        acceptInvite.mutate({
          token,
          user: {
            first_name: firstName,
            last_name: lastName,
            password,
          },
        })
      }

      // ...
    }

    export default AcceptInvite
    ```

  </TabItem>
  <TabItem value="fetch" label="Fetch API">

    ```ts
    fetch(`<BACKEND_URL>/admin/invites/accept`, {
      credentials: "include",
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        token,
        user: {
          first_name: "Brigitte",
          last_name: "Collier",
          password: "supersecret",
        },
      }),
    })
    .then((response) => response.json())
    .then(() => {
      // successful
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X POST '<BACKEND_URL>/admin/invites/accept' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "token": "<TOKEN>",
        "user": {
          "first_name": "Brigitte",
          "last_name": "Collier",
          "password": "supersecret"
        }
    }'
    ```

  </TabItem>
</Tabs>

This API Route requires the following request body parameters:

- `token`: a string indicating the invitation’s token.
- `user`: an object that has the following properties:
    - `first_name`: a string indicating the first name of the user.
    - `last_name`: a string indicating the last name of the user.
    - `password`: a string indicating the user’s password.

The request does not return any data. If the invite was accepted successfully, the status code of the response will be `200`.

---

## Resend an Invite

You can resend an invite if it’s not accepted yet. To resend an invite, send a request to the [Resend Invite API Route](https://docs.medusajs.com/api/admin#invites_postinvitesinviteresend):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

    ```ts
    medusa.admin.invites.resend(inviteId)
    .then(() => {
      // successful
    })
    ```

  </TabItem>
  <TabItem value="medusa-react" label="Medusa React">

    ```tsx
    import { useAdminResendInvite } from "medusa-react"

    type Props = {
      inviteId: string
    }

    const ResendInvite = ({ inviteId }: Props) => {
      const resendInvite = useAdminResendInvite(inviteId)
      // ...

      const handleResend = () => {
        resendInvite.mutate()
      }

      // ...
    }

    export default ResendInvite
    ```

  </TabItem>
  <TabItem value="fetch" label="Fetch API">

    ```ts
    fetch(`<BACKEND_URL>/admin/invites/${inviteId}/resend`, {
      credentials: "include",
      method: "POST",
    })
    .then((response) => response.json())
    .then(() => {
      // successful
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X POST '<BACKEND_URL>/admin/invites/<INVITE_ID>/resend' \
    -H 'x-medusa-access-token: <API_TOKEN>'
    ```

  </TabItem>
</Tabs>

This API Route requires the invite ID as a path parameter.

The request doesn't return any data. If the invite was resent successfully, the status code of the response will be `200`.

---

## Delete an Invite

You can delete an invite by sending a request to the [Delete Invite API Route](https://docs.medusajs.com/api/admin#invites_deleteinvitesinvite):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

    ```ts
    medusa.admin.invites.delete(inviteId)
    .then(({ id, object, deleted }) => {
      console.log(id)
    })
    ```

  </TabItem>
  <TabItem value="medusa-react" label="Medusa React">

    ```tsx
    import { useAdminDeleteInvite } from "medusa-react"

    type Props = {
      inviteId: string
    }

    const DeleteInvite = ({ inviteId }: Props) => {
      const deleteInvite = useAdminDeleteInvite(inviteId)
      // ...

      const handleDelete = () => {
        deleteInvite.mutate(void 0, {
          onSuccess: ({ id, object, deleted }) => {
            console.log(id)
          }
        })
      }

      // ...
    }

    export default Invite
    ```

  </TabItem>
  <TabItem value="fetch" label="Fetch API">

    ```ts
    fetch(`<BACKEND_URL>/admin/invites/${inviteId}`, {
      credentials: "include",
      method: "DELETE",
    })
    .then((response) => response.json())
    .then(({ id, object, deleted }) => {
      console.log(id)
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X DELETE '<BACKEND_URL>/admin/invites/<INVITE_ID>' \
    -H 'x-medusa-access-token: <API_TOKEN>'
    ```

  </TabItem>
</Tabs>

This API Route requires the invite ID as a path parameter.

It deletes the invite and returns the following fields:

- `id`: The ID of the deleted invite.
- `object`: The type of object that was deleted. In this case, the value will be `invite`.
- `deleted`: A boolean value indicating whether the invite was deleted.

---

## See Also

- [How to implement user profiles](./manage-profile.mdx)
- [How to manage users](./manage-users.mdx)