Customer Groups

Queries and Mutations listed here are used to send requests to the Admin Customer Group API Routes.

All hooks listed require user authentication.

Customer Groups can be used to organize customers that share similar data or attributes into dedicated groups. This can be useful for different purposes such as setting a different price for a specific customer group.

Related Guide: How to manage customer groups.

Mutations

useAdminCreateCustomerGroup

This hook creates a customer group.

Example

import React from "react"
import { useAdminCreateCustomerGroup } from "medusa-react"

const CreateCustomerGroup = () => {
  const createCustomerGroup = useAdminCreateCustomerGroup()
  // ...

  const handleCreate = (name: string) => {
    createCustomerGroup.mutate({
      name,
    })
  }

  // ...
}

export default CreateCustomerGroup

Mutation Function Parameters

AdminPostCustomerGroupsReqAdminPostCustomerGroupsReqRequired

The details of the customer group to create.

Mutation Function Returned Data

AdminCustomerGroupsResAdminCustomerGroupsResRequired

The customer group's details.

useAdminUpdateCustomerGroup

This hook updates a customer group's details.

Example

import React from "react"
import { useAdminUpdateCustomerGroup } from "medusa-react"

type Props = {
  customerGroupId: string
}

const CustomerGroup = ({ customerGroupId }: Props) => {
  const updateCustomerGroup = useAdminUpdateCustomerGroup(
    customerGroupId
  )
  // ..

  const handleUpdate = (name: string) => {
    updateCustomerGroup.mutate({
      name,
    })
  }

  // ...
}

export default CustomerGroup

Hook Parameters

idstringRequired

The customer group's ID.

Mutation Function Parameters

AdminPostCustomerGroupsGroupReqAdminPostCustomerGroupsGroupReqRequired

The details to update in the customer group.

Mutation Function Returned Data

AdminCustomerGroupsResAdminCustomerGroupsResRequired

The customer group's details.

useAdminDeleteCustomerGroup

This hook deletes a customer group. This doesn't delete the customers associated with the customer group.

Example

import React from "react"
import { useAdminDeleteCustomerGroup } from "medusa-react"

type Props = {
  customerGroupId: string
}

const CustomerGroup = ({ customerGroupId }: Props) => {
  const deleteCustomerGroup = useAdminDeleteCustomerGroup(
    customerGroupId
  )
  // ...

  const handleDeleteCustomerGroup = () => {
    deleteCustomerGroup.mutate()
  }

  // ...
}

export default CustomerGroup

Hook Parameters

idstringRequired

The customer group's ID.

Mutation Function Returned Data

DeleteResponseDeleteResponseRequired

The response returned for a DELETE request.

useAdminAddCustomersToCustomerGroup

The hook adds a list of customers to a customer group.

Example

import React from "react"
import { 
  useAdminAddCustomersToCustomerGroup,
} from "medusa-react"

type Props = {
  customerGroupId: string
}

const CustomerGroup = ({ customerGroupId }: Props) => {
  const addCustomers = useAdminAddCustomersToCustomerGroup(
    customerGroupId
  )
  // ...

  const handleAddCustomers= (customerId: string) => {
    addCustomers.mutate({
      customer_ids: [
        {
          id: customerId,
        },
      ],
    })
  }

  // ...
}

export default CustomerGroup

Hook Parameters

idstringRequired

The customer group's ID.

Mutation Function Parameters

AdminPostCustomerGroupsGroupCustomersBatchReqAdminPostCustomerGroupsGroupCustomersBatchReqRequired

The customers to add to the customer group.

Mutation Function Returned Data

AdminCustomerGroupsResAdminCustomerGroupsResRequired

The customer group's details.

useAdminRemoveCustomersFromCustomerGroup

This hook removes a list of customers from a customer group. This doesn't delete the customer, only the association between the customer and the customer group.

Example

import React from "react"
import { 
  useAdminRemoveCustomersFromCustomerGroup,
} from "medusa-react"

type Props = {
  customerGroupId: string
}

const CustomerGroup = ({ customerGroupId }: Props) => {
  const removeCustomers = 
    useAdminRemoveCustomersFromCustomerGroup(
      customerGroupId
    )
  // ...

  const handleRemoveCustomer = (customerId: string) => {
    removeCustomers.mutate({
      customer_ids: [
        {
          id: customerId,
        },
      ],
    })
  }

  // ...
}

export default CustomerGroup

Hook Parameters

idstringRequired

The customer group's ID.

Mutation Function Parameters

AdminDeleteCustomerGroupsGroupCustomerBatchReqAdminDeleteCustomerGroupsGroupCustomerBatchReqRequired

The customers to remove from the customer group.

Mutation Function Returned Data

AdminCustomerGroupsResAdminCustomerGroupsResRequired

The customer group's details.

---

Queries

useAdminCustomerGroup

This hook retrieves a customer group by its ID. You can expand the customer group's relations or select the fields that should be returned.

Example

import React from "react"
import { useAdminCustomerGroup } from "medusa-react"

type Props = {
  customerGroupId: string
}

const CustomerGroup = ({ customerGroupId }: Props) => {
  const { customer_group, isLoading } = useAdminCustomerGroup(
    customerGroupId
  )

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {customer_group && <span>{customer_group.name}</span>}
    </div>
  )
}

export default CustomerGroup

Hook Parameters

idstringRequired

The customer group's ID.

queryAdminGetCustomerGroupsGroupParams

Configurations to apply on the retrieved customer group.

Query Returned Data

customer_groupCustomerGroupRequired

Customer group details.

useAdminCustomerGroups

This hook retrieves a list of customer groups. The customer groups can be filtered by fields such as name or id. The customer groups can also be sorted or paginated.

Example

To list customer groups:

import React from "react"
import { useAdminCustomerGroups } from "medusa-react"

const CustomerGroups = () => {
  const { 
    customer_groups,
    isLoading,
  } = useAdminCustomerGroups()

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {customer_groups && !customer_groups.length && (
        <span>No Customer Groups</span>
      )}
      {customer_groups && customer_groups.length > 0 && (
        <ul>
          {customer_groups.map(
            (customerGroup) => (
              <li key={customerGroup.id}>
                {customerGroup.name}
              </li>
            )
          )}
        </ul>
      )}
    </div>
  )
}

export default CustomerGroups

To specify relations that should be retrieved within the customer groups:

import React from "react"
import { useAdminCustomerGroups } from "medusa-react"

const CustomerGroups = () => {
  const { 
    customer_groups,
    isLoading,
  } = useAdminCustomerGroups({
    expand: "customers"
  })

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {customer_groups && !customer_groups.length && (
        <span>No Customer Groups</span>
      )}
      {customer_groups && customer_groups.length > 0 && (
        <ul>
          {customer_groups.map(
            (customerGroup) => (
              <li key={customerGroup.id}>
                {customerGroup.name}
              </li>
            )
          )}
        </ul>
      )}
    </div>
  )
}

export default CustomerGroups

By default, only the first 10 records are retrieved. You can control pagination by specifying the limit and offset properties:

import React from "react"
import { useAdminCustomerGroups } from "medusa-react"

const CustomerGroups = () => {
  const { 
    customer_groups,
    limit,
    offset,
    isLoading,
  } = useAdminCustomerGroups({
    expand: "customers",
    limit: 15,
    offset: 0
  })

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {customer_groups && !customer_groups.length && (
        <span>No Customer Groups</span>
      )}
      {customer_groups && customer_groups.length > 0 && (
        <ul>
          {customer_groups.map(
            (customerGroup) => (
              <li key={customerGroup.id}>
                {customerGroup.name}
              </li>
            )
          )}
        </ul>
      )}
    </div>
  )
}

export default CustomerGroups

Hook Parameters

queryAdminGetCustomerGroupsParams

Filters and pagination configurations to apply on the retrieved customer groups.

Query Returned Data

limitnumberRequired

The maximum number of items that can be returned in the list.

offsetnumberRequired

The number of items skipped before the returned items in the list.

countnumberRequired

The total number of items available.

customer_groupsCustomerGroup[]Required

An array of customer group details.

useAdminCustomerGroupCustomers

This hook retrieves a list of customers in a customer group. The customers can be filtered by the query field. The customers can also be paginated.

Example

import React from "react"
import { useAdminCustomerGroupCustomers } from "medusa-react"

type Props = {
  customerGroupId: string
}

const CustomerGroup = ({ customerGroupId }: Props) => {
  const { 
    customers, 
    isLoading,
  } = useAdminCustomerGroupCustomers(
    customerGroupId
  )

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {customers && !customers.length && (
        <span>No customers</span>
      )}
      {customers && customers.length > 0 && (
        <ul>
          {customers.map((customer) => (
            <li key={customer.id}>{customer.first_name}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default CustomerGroup

Hook Parameters

idstringRequired

The customer group's ID.

queryAdminGetCustomersParams

Filters and pagination configurations to apply on the retrieved customers.

Query Returned Data

limitnumberRequired

The maximum number of items that can be returned in the list.

offsetnumberRequired

The number of items skipped before the returned items in the list.

countnumberRequired

The total number of items available.

customersCustomer[]Required

An array of customer details.