api-ref: custom API reference (#4770)
* initialized next.js project * finished markdown sections * added operation schema component * change page metadata * eslint fixes * fixes related to deployment * added response schema * resolve max stack issue * support for different property types * added support for property types * added loading for components * added more loading * type fixes * added oneOf type * removed console * fix replace with push * refactored everything * use static content for description * fixes and improvements * added code examples section * fix path name * optimizations * fixed tag navigation * add support for admin and store references * general enhancements * optimizations and fixes * fixes and enhancements * added search bar * loading enhancements * added loading * added code blocks * added margin top * add empty response text * fixed oneOf parameters * added path and query parameters * general fixes * added base path env variable * small fix for arrays * enhancements * design enhancements * general enhancements * fix isRequired * added enum values * enhancements * general fixes * general fixes * changed oas generation script * additions to the introduction section * added copy button for code + other enhancements * fix response code block * fix metadata * formatted store introduction * move sidebar logic to Tags component * added test env variables * fix code block bug * added loading animation * added expand param + loading * enhance operation loading * made responsive + improvements * added loading provider * fixed loading * adjustments for small devices * added sidebar label for endpoints * added feedback component * fixed analytics * general fixes * listen to scroll for other headings * added sample env file * update api ref files + support new fields * fix for external docs link * added new sections * fix last item in sidebar not showing * move docs content to www/docs * change redirect url * revert change * resolve build errors * configure rewrites * changed to environment variable url * revert changing environment variable name * add environment variable for API path * fix links * fix tailwind settings * remove vercel file * reconfigured api route * move api page under api * fix page metadata * fix external link in navigation bar * update api spec * updated api specs * fixed google lint error * add max-height on request samples * add padding before loading * fix for one of name * fix undefined types * general fixes * remove response schema example * redesigned navigation bar * redesigned sidebar * fixed up paddings * added feedback component + report issue * fixed up typography, padding, and general styling * redesigned code blocks * optimization * added error timeout * fixes * added indexing with algolia + fixes * fix errors with algolia script * redesign operation sections * fix heading scroll * design fixes * fix padding * fix padding + scroll issues * fix scroll issues * improve scroll performance * fixes for safari * optimization and fixes * fixes to docs + details animation * padding fixes for code block * added tab animation * fixed incorrect link * added selection styling * fix lint errors * redesigned details component * added detailed feedback form * api reference fixes * fix tabs * upgrade + fixes * updated documentation links * optimizations to sidebar items * fix spacing in sidebar item * optimizations and fixes * fix endpoint path styling * remove margin * final fixes * change margin on small devices * generated OAS * fixes for mobile * added feedback modal * optimize dark mode button * fixed color mode useeffect * minimize dom size * use new style system * radius and spacing design system * design fixes * fix eslint errors * added meta files * change cron schedule * fix docusaurus configurations * added operating system to feedback data * change content directory name * fixes to contribution guidelines * revert renaming content * added api-reference to documentation workflow * fixes for search * added dark mode + fixes * oas fixes * handle bugs * added code examples for clients * changed tooltip text * change authentication to card * change page title based on selected section * redesigned mobile navbar * fix icon colors * fix key colors * fix medusa-js installation command * change external regex in algolia * change changeset * fix padding on mobile * fix hydration error * update depedencies
This commit is contained in:
Shahed Nasser
@@ -0,0 +1,738 @@
|
||||
---
|
||||
description: 'Learn how to implement customer group functionalities for admins using the REST APIs. This includes listing customer groups, creating a customer group, managing customers in the group, and more.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# How to Manage Customer Groups
|
||||
|
||||
In this document, you’ll learn how to use the customer groups admin APIs to manage customer groups and their associated customers and price lists.
|
||||
|
||||
## Overview
|
||||
|
||||
Using the Admin API you can manage customer groups by creating, retrieving, updating, and deleting them. You can also manage the customers in a customer group.
|
||||
|
||||
Using the PriceList API you can specify among the conditions the customer groups that the prices will apply to.
|
||||
|
||||
This guide covers how to use these APIs to perform these tasks.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa Components
|
||||
|
||||
It is assumed that you already have a Medusa backend installed and set up. If not, you can follow our [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.md) installed and have [created an instance of the client](../../../js-client/overview.md#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
|
||||
|
||||
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).
|
||||
|
||||
---
|
||||
|
||||
## Create Customer Groups
|
||||
|
||||
You can create a customer group by sending a request to the Create Customer Group endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.customerGroups.create({
|
||||
name: "VIP",
|
||||
})
|
||||
.then(({ customer_group }) => {
|
||||
console.log(customer_group.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminCreateCustomerGroup } from "medusa-react"
|
||||
|
||||
const CreateCustomerGroup = () => {
|
||||
const createCustomerGroup = useAdminCreateCustomerGroup()
|
||||
// ...
|
||||
|
||||
const handleCreate = () => {
|
||||
createCustomerGroup.mutate({
|
||||
name,
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
|
||||
return (
|
||||
<form>
|
||||
{/* Render form */}
|
||||
</form>
|
||||
)
|
||||
}
|
||||
|
||||
export default CreateCustomerGroup
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/customer-groups`, {
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
name: "VIP",
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ customer_group }) => {
|
||||
console.log(customer_group.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/customer-groups' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"name": "VIP"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires the `name` parameter and optionally accepts the `metadata` object parameter to be passed in the body. It returns the created customer group.
|
||||
|
||||
---
|
||||
|
||||
## List Customer Groups
|
||||
|
||||
You can get a list of all customer groups by sending a request to the List Customer Groups endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.customerGroups.list()
|
||||
.then(({ customer_groups, limit, offset, count }) => {
|
||||
console.log(customer_groups.length)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { CustomerGroup } from "@medusajs/medusa"
|
||||
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: CustomerGroup) => (
|
||||
<li key={customerGroup.id}>
|
||||
{customerGroup.name}
|
||||
</li>
|
||||
)
|
||||
)}
|
||||
</ul>
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default CustomerGroups
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/customer-groups`, {
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ customer_groups, limit, offset, count }) => {
|
||||
console.log(customer_groups.length)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X GET '<BACKEND_URL>/admin/customer-groups' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request returns an array of customer groups, as well as pagination fields.
|
||||
|
||||
You can also pass filters and other selection query parameters to the request. Check out the [API reference](https://docs.medusajs.com/api/admin#customer-groups_getcustomergroups) for more details on available query parameters.
|
||||
|
||||
---
|
||||
|
||||
## Retrieve a Customer Group
|
||||
|
||||
You can retrieve a single customer group by sending a request to the Get a Customer Group endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.customerGroups.retrieve(customerGroupId)
|
||||
.then(({ customer_group }) => {
|
||||
console.log(customer_group.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminCustomerGroup } from "medusa-react"
|
||||
|
||||
const CustomerGroup = () => {
|
||||
const { customer_group, isLoading } = useAdminCustomerGroup(
|
||||
customerGroupId
|
||||
)
|
||||
|
||||
return (
|
||||
<div>
|
||||
{isLoading && <span>Loading...</span>}
|
||||
{customer_group && <span>{customer_group.name}</span>}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default CustomerGroup
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(
|
||||
`<BACKEND_URL>/admin/customer-groups/${customerGroupId}`,
|
||||
{
|
||||
credentials: "include",
|
||||
}
|
||||
)
|
||||
.then((response) => response.json())
|
||||
.then(({ customer_group }) => {
|
||||
console.log(customer_group.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X GET '<BACKEND_URL>/admin/customer-groups/<CUSTOMER_GROUP_ID>' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request accepts the ID of the customer group to retrieve as a path parameter. It returns the customer group of that ID.
|
||||
|
||||
---
|
||||
|
||||
## Update a Customer Group
|
||||
|
||||
You can update a customer group’s data by sending a request to the Update Customer Group endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.customerGroups.update(customerGroupId, {
|
||||
metadata: {
|
||||
is_seller: true,
|
||||
},
|
||||
})
|
||||
.then(({ customer_group }) => {
|
||||
console.log(customer_group.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminUpdateCustomerGroup } from "medusa-react"
|
||||
|
||||
const UpdateCustomerGroup = () => {
|
||||
const updateCustomerGroup = useAdminUpdateCustomerGroup(
|
||||
customerGroupId
|
||||
)
|
||||
// ..
|
||||
|
||||
const handleUpdate = () => {
|
||||
updateCustomerGroup.mutate({
|
||||
name,
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
|
||||
return (
|
||||
<form>
|
||||
{/* Render form */}
|
||||
</form>
|
||||
)
|
||||
}
|
||||
|
||||
export default UpdateCustomerGroup
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(
|
||||
`<BACKEND_URL>/admin/customer-groups/${customerGroupId}`,
|
||||
{
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
metadata: {
|
||||
is_seller: true,
|
||||
},
|
||||
}),
|
||||
}
|
||||
)
|
||||
.then((response) => response.json())
|
||||
.then(({ customer_group }) => {
|
||||
console.log(customer_group.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/customer-groups/<CUSTOMER_GROUP_ID>' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"metadata": {
|
||||
"is_seller": true
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request accepts the ID of the customer group as a path parameter, and optionally accepts the `name` or `metadata` fields as body parameters. It returns the updated customer group.
|
||||
|
||||
---
|
||||
|
||||
## Delete Customer Group
|
||||
|
||||
You can delete a customer group by sending a request to the Delete a Customer Group endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.customerGroups.delete(customerGroupId)
|
||||
.then(({ id, object, deleted }) => {
|
||||
console.log(id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminDeleteCustomerGroup } from "medusa-react"
|
||||
|
||||
const CustomerGroup = () => {
|
||||
const deleteCustomerGroup = useAdminDeleteCustomerGroup(
|
||||
customerGroupId
|
||||
)
|
||||
// ...
|
||||
|
||||
const handleDeleteCustomerGroup = () => {
|
||||
deleteCustomerGroup.mutate()
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default CustomerGroup
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(
|
||||
`<BACKEND_URL>/admin/customer-groups/${customerGroupId}`,
|
||||
{
|
||||
method: "DELETE",
|
||||
credentials: "include",
|
||||
}
|
||||
)
|
||||
.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/customer-groups/<CUSTOMER_GROUP_ID>' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request accepts the ID of the customer group to delete as a path parameter. It returns the ID of the deleted entity.
|
||||
|
||||
---
|
||||
|
||||
## Manage Customers
|
||||
|
||||
### Add Customer to Group
|
||||
|
||||
You can add a customer to a group by sending a request to the Customer Group’s Add Customer endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.customerGroups.addCustomers(customerGroupId, {
|
||||
customer_ids: [
|
||||
{
|
||||
id: customerId,
|
||||
},
|
||||
],
|
||||
})
|
||||
.then(({ customer_group }) => {
|
||||
console.log(customer_group.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import {
|
||||
useAdminAddCustomersToCustomerGroup,
|
||||
} from "medusa-react"
|
||||
|
||||
const CustomerGroup = () => {
|
||||
const addCustomers = useAdminAddCustomersToCustomerGroup(
|
||||
customerGroupId
|
||||
)
|
||||
// ...
|
||||
|
||||
const handleAddCustomers= (customerId: string) => {
|
||||
addCustomers.mutate({
|
||||
customer_ids: [
|
||||
{
|
||||
id: customerId,
|
||||
},
|
||||
],
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default CustomerGroup
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```ts
|
||||
fetch(
|
||||
`<BACKEND_URL>/admin/customer-groups/${customerGroupId}/customers/batch`,
|
||||
{
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
customer_ids: [
|
||||
{
|
||||
id: customerId,
|
||||
},
|
||||
],
|
||||
}),
|
||||
}
|
||||
)
|
||||
.then((response) => response.json())
|
||||
.then(({ customer_group }) => {
|
||||
console.log(customer_group.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/customer-groups/<CUSTOMER_GROUP_ID>/customers/batch' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"customer_ids": [
|
||||
{
|
||||
"id": "<CUSTOMER_ID>"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request accepts the ID of the customer group as a path parameter. In its body, it accepts a `customer_ids` array of objects. Each object in the array must have the `id` property with its value being the ID of the customer you want to add.
|
||||
|
||||
### List Customers
|
||||
|
||||
You can retrieve a list of all customers in a customer group using the List Customers endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.customerGroups.listCustomers(customerGroupId)
|
||||
.then(({ customers, count, offset, limit }) => {
|
||||
console.log(customers.length)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { Customer } from "@medusajs/medusa"
|
||||
import { useAdminCustomerGroupCustomers } from "medusa-react"
|
||||
|
||||
const CustomerGroup = () => {
|
||||
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: Customer) => (
|
||||
<li key={customer.id}>{customer.first_name}</li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default CustomerGroup
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/customer-groups/${customerGroupId}/customers`, {
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ customers, count, offset, limit }) => {
|
||||
console.log(customers.length)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X GET '<BACKEND_URL>/admin/customer-groups/<CUSTOMER_GROUP_ID>/customers' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request accepts the ID of the customer group as a path parameter. It returns an array of customers along with pagination fields.
|
||||
|
||||
### Remove Customers from a Group
|
||||
|
||||
:::info
|
||||
|
||||
Removing customers from a group does not remove them entirely. They’ll still be available in your store.
|
||||
|
||||
:::
|
||||
|
||||
You can remove customers from a customer group by sending a request to the Remove Customers endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.customerGroups.removeCustomers(
|
||||
customer_group_id,
|
||||
{
|
||||
customer_ids: [
|
||||
{
|
||||
id: customer_id,
|
||||
},
|
||||
],
|
||||
}
|
||||
)
|
||||
.then(({ customer_group }) => {
|
||||
console.log(customer_group.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { Customer } from "@medusajs/medusa"
|
||||
import {
|
||||
useAdminRemoveCustomersFromCustomerGroup,
|
||||
} from "medusa-react"
|
||||
|
||||
const CustomerGroup = () => {
|
||||
const removeCustomers =
|
||||
useAdminRemoveCustomersFromCustomerGroup(
|
||||
customerGroupId
|
||||
)
|
||||
// ...
|
||||
|
||||
const handleRemoveCustomer = (customer_id: string) => {
|
||||
removeCustomers.mutate({
|
||||
customer_ids: [
|
||||
{
|
||||
id: customer_id,
|
||||
},
|
||||
],
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default CustomerGroup
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```ts
|
||||
fetch(
|
||||
`<BACKEND_URL>/admin/customer-groups/${customerGroupId}/customers/batch`,
|
||||
{
|
||||
method: "DELETE",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
customer_ids: [
|
||||
{
|
||||
id: customerId,
|
||||
},
|
||||
],
|
||||
}),
|
||||
}
|
||||
)
|
||||
.then((response) => response.json())
|
||||
.then(({ customer_group }) => {
|
||||
console.log(customer_group.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X DELETE '<BACKEND_URL>/admin/customer-groups/<CUSTOMER_GROUP_ID>/customers/batch' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"customer_ids": [
|
||||
{
|
||||
"id": "<CUSTOMER_ID>"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request accepts as a path parameter the ID of the customer group to remove customers from. In its body, it accepts a `customer_ids` array of objects. Each object in the array must have the `id` property with the value being the ID of the customer to remove from the group.
|
||||
|
||||
This request returns the customer group.
|
||||
|
||||
---
|
||||
|
||||
## Use Customer Groups as Conditions in a Price List
|
||||
|
||||
When you create or update a price list, you can specify one or more customer groups as conditions for the price list. You can learn how to do that in the [PriceList API documentation](../../price-lists/admin/manage-price-lists.mdx).
|
||||
@@ -0,0 +1,338 @@
|
||||
---
|
||||
description: 'Learn how to implement customer-related functionalities for admins using the REST APIs. This includes how to list customers, add a new customer and edit the details of a customer.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# How to Manage Customers
|
||||
|
||||
In this document, you’ll learn how to implement customer management functionalities for admin users.
|
||||
|
||||
## Overview
|
||||
|
||||
Using the customer admin REST APIs, you can manage customers, including creating, updating, and listing them.
|
||||
|
||||
### Scenario
|
||||
|
||||
You want to add or use the following admin functionalities:
|
||||
|
||||
- List customers
|
||||
- Add a new customer
|
||||
- Edit a customer’s details
|
||||
|
||||
---
|
||||
|
||||
## 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, JavaScript’s Fetch API, or cURL.
|
||||
|
||||
If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#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
|
||||
|
||||
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 Customers
|
||||
|
||||
You can show a list of customers by sending a request to the [List Customers](https://docs.medusajs.com/api/admin#customers_getcustomers) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.customers.list()
|
||||
.then(({ customers, limit, offset, count }) => {
|
||||
console.log(customers.length)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { Customer } from "@medusajs/medusa"
|
||||
import { useAdminCustomers } from "medusa-react"
|
||||
|
||||
const Customers = () => {
|
||||
const { customers, isLoading } = useAdminCustomers()
|
||||
|
||||
return (
|
||||
<div>
|
||||
{isLoading && <span>Loading...</span>}
|
||||
{customers && !customers.length && (
|
||||
<span>No customers</span>
|
||||
)}
|
||||
{customers && customers.length > 0 && (
|
||||
<ul>
|
||||
{customers.map((customer: Customer) => (
|
||||
<li key={customer.id}>{customer.first_name}</li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default Customers
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/customers`, {
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ customers, limit, offset, count }) => {
|
||||
console.log(customers.length)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X GET '<BACKEND_URL>/admin/customers' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request doesn’t require any path or query parameters. You can pass it optional parameters used for filtering and pagination. Check out the [API reference](https://docs.medusajs.com/api/admin#customers_getcustomers) to learn more.
|
||||
|
||||
This request returns the following data in the response:
|
||||
|
||||
- `customers`: An array of customers.
|
||||
- `limit`: The maximum number of customers that can be returned in the request.
|
||||
- `offset`: The number of customers skipped in the result.
|
||||
- `count`: The total number of customers available.
|
||||
|
||||
:::info
|
||||
|
||||
You can learn more about pagination in the [API reference](https://docs.medusajs.com/api/admin#pagination).
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Create a Customer
|
||||
|
||||
Admins can create customer accounts. They have to supply the customer’s credentials and basic info.
|
||||
|
||||
You can create a customer account by sending a request to the [Create a Customer](https://docs.medusajs.com/api/admin#customers_postcustomers) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.customers.create({
|
||||
email,
|
||||
password,
|
||||
first_name,
|
||||
last_name,
|
||||
})
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminCreateCustomer } from "medusa-react"
|
||||
|
||||
const CreateCustomer = () => {
|
||||
const createCustomer = useAdminCreateCustomer()
|
||||
// ...
|
||||
|
||||
const handleCreate = () => {
|
||||
// ...
|
||||
createCustomer.mutate({
|
||||
first_name,
|
||||
last_name,
|
||||
email,
|
||||
password,
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
|
||||
return (
|
||||
<form>
|
||||
{/* Render form */}
|
||||
</form>
|
||||
)
|
||||
}
|
||||
|
||||
export default CreateCustomer
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/customers`, {
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
email,
|
||||
password,
|
||||
first_name,
|
||||
last_name,
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/customers' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"email": "<EMAIL>",
|
||||
"first_name": "<FIRST_NAME>",
|
||||
"last_name": "<LAST_NAME>",
|
||||
"password": "<PASSWORD>"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires the following body parameters:
|
||||
|
||||
- `email`: The email of the customer.
|
||||
- `password`: The password of the customer.
|
||||
- `first_name`: The customer’s first name.
|
||||
- `last_name`: the customer’s last name.
|
||||
|
||||
You can also pass other optional parameters. To learn more, check out the [API reference](https://docs.medusajs.com/api/admin#customers_postcustomers).
|
||||
|
||||
The request returns the created customer object in the response.
|
||||
|
||||
---
|
||||
|
||||
## Edit Customer’s Information
|
||||
|
||||
An admin can edit a customer’s basic information and credentials.
|
||||
|
||||
You can edit a customer’s information by sending a request to the [Update a Customer](https://docs.medusajs.com/api/admin#customers_postcustomerscustomer) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.customers.update(customerId, {
|
||||
first_name,
|
||||
})
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminUpdateCustomer } from "medusa-react"
|
||||
|
||||
const UpdateCustomer = () => {
|
||||
const updateCustomer = useAdminUpdateCustomer(customerId)
|
||||
// ...
|
||||
|
||||
const handleUpdate = () => {
|
||||
// ...
|
||||
updateCustomer.mutate({
|
||||
email,
|
||||
password,
|
||||
first_name,
|
||||
last_name,
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
|
||||
return (
|
||||
<form>
|
||||
{/* Render form */}
|
||||
</form>
|
||||
)
|
||||
}
|
||||
|
||||
export default UpdateCustomer
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/customers/${customerId}`, {
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
first_name,
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/customers/<CUSTOMER_ID>' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"first_name": "<FIRST_NAME>"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request accepts any of the customer’s fields as body parameters. In this example, you update the customer’s first name. You can learn more about accepted body parameters in the [API reference](https://docs.medusajs.com/api/admin#customers_postcustomerscustomer).
|
||||
|
||||
This request returns the updated customer object in the response.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Implement customer profiles in the storefront](../storefront/implement-customer-profiles.mdx)
|
||||
@@ -0,0 +1,190 @@
|
||||
---
|
||||
description: 'Learn how to send a confirmation email to the customer after they sign up. This guide uses SendGrid as an example Notification provider.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# How to Send Sign Up Confirmation Email
|
||||
|
||||
In this document, you’ll learn how to send a confirmation email to the customer after they sign up.
|
||||
|
||||
## Overview
|
||||
|
||||
When a customer registers, the event `customer.created` is triggered. You can then listen to this event in a subscriber to perform an action, such as send the customer a confirmation email.
|
||||
|
||||
This guide will explain how to create the subscriber and how to use SendGrid to send the confirmation email. SendGrid is only used to illustrate how the process works, but you’re free to use any other notification service.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Event Bus Module
|
||||
|
||||
The event bus module trigger the event to the listening subscribers. So, it’s required to have an event bus module installed and configured on your Medusa backend.
|
||||
|
||||
The [Local Event Bus module](../../../development/events/modules/local.md) works in a development environment. For production, it’s recommended to use the [Redis Event Bus module](../../../development/events/modules/redis.md).
|
||||
|
||||
### Notification Provider
|
||||
|
||||
As mentioned in the overview, this guide illustrates how to send the email using SendGrid. If you intend to follow along, you must have the [SendGrid plugin](../../../plugins/notifications/sendgrid.mdx) installed and configured.
|
||||
|
||||
You can also find other available Notification provider plugins in the [Plugins directory](https://medusajs.com/plugins/), or [create your own](../../../development/notification/create-notification-provider.md).
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Create the Subscriber
|
||||
|
||||
To subscribe to and handle an event, you must create a subscriber.
|
||||
|
||||
:::note
|
||||
|
||||
You can learn more about subscribers in the [Subscribers documentation](../../../development/events/subscribers.mdx).
|
||||
|
||||
:::
|
||||
|
||||
Create the file `src/subscribers/customer-confirmation.ts` with the following content:
|
||||
|
||||
```ts title=src/subscribers/customer-confirmation.ts
|
||||
type InjectedDependencies = {
|
||||
// TODO add necessary dependencies
|
||||
}
|
||||
|
||||
class CustomerConfirmationSubscriber {
|
||||
constructor(container: InjectedDependencies) {
|
||||
// TODO subscribe to event
|
||||
}
|
||||
}
|
||||
|
||||
export default CustomerConfirmationSubscriber
|
||||
```
|
||||
|
||||
You’ll be adding in the next step the necessary dependencies to the subscriber.
|
||||
|
||||
:::note
|
||||
|
||||
You can learn more about dependency injection in [this documentation](../../../development/fundamentals/dependency-injection.md).
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Subscribe to the Event
|
||||
|
||||
In this step, you’ll subscribe to the `customer.created` event to send the customer a confirmation email.
|
||||
|
||||
There are two ways to do this:
|
||||
|
||||
### Method 1: Using the NotificationService
|
||||
|
||||
If the notification provider you’re using already implements the logic to handle this event, you can subscribe to the event using the `NotificationService`:
|
||||
|
||||
```ts title=src/subscribers/customer-confirmation.ts
|
||||
import { NotificationService } from "@medusajs/medusa"
|
||||
|
||||
type InjectedDependencies = {
|
||||
notificationService: NotificationService
|
||||
}
|
||||
|
||||
class CustomerConfirmationSubscriber {
|
||||
constructor({ notificationService }: InjectedDependencies) {
|
||||
notificationService.subscribe(
|
||||
"customer.created",
|
||||
"<NOTIFICATION_PROVIDER_IDENTIFIER>"
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
export default CustomerConfirmationSubscriber
|
||||
```
|
||||
|
||||
Where `<NOTIFICATION_PROVIDER_IDENTIFIER>` is the identifier for your notification provider.
|
||||
|
||||
:::note
|
||||
|
||||
You can learn more about handling events with the Notification Service using [this documentation](../../../development/notification/create-notification-provider.md).
|
||||
|
||||
:::
|
||||
|
||||
### Method 2: Using the EventBusService
|
||||
|
||||
If the notification provider you’re using isn’t configured to handle this event, or you want to implement some other custom logic, you can subscribe to the event using the `EventBusService`:
|
||||
|
||||
```ts title=src/subscribers/customer-confirmation.ts
|
||||
import { Customer, EventBusService } from "@medusajs/medusa"
|
||||
|
||||
type InjectedDependencies = {
|
||||
eventBusService: EventBusService
|
||||
}
|
||||
|
||||
class CustomerConfirmationSubscriber {
|
||||
constructor({ eventBusService }: InjectedDependencies) {
|
||||
eventBusService.subscribe(
|
||||
"customer.created",
|
||||
this.handleCustomerConfirmation
|
||||
)
|
||||
}
|
||||
|
||||
handleCustomerConfirmation = async (data: Customer) => {
|
||||
// TODO: handle event
|
||||
}
|
||||
}
|
||||
|
||||
export default CustomerConfirmationSubscriber
|
||||
```
|
||||
|
||||
When using this method, you’ll have to handle the logic of sending the confirmation email to the customer inside the handler function, which in this case is `handleCustomerConfirmation`.
|
||||
|
||||
## Step 3: Handle the Event
|
||||
|
||||
The `handleCustomerConfirmation` method receives a `data` object as a parameter which is a payload emitted when the event was triggered. This object is the entire customer object. So, you can find in it fields like `first_name`, `last_name`, `email`, and more.
|
||||
|
||||
In this method, you should typically send an email to the customer. You can place any content in the email, such as welcoming them to your store or thanking them for registering.
|
||||
|
||||
### Example: Using SendGrid
|
||||
|
||||
For example, you can implement this subscriber to send emails using SendGrid:
|
||||
|
||||
```ts title=src/subscribers/customer-confirmation.ts
|
||||
import { Customer, EventBusService } from "@medusajs/medusa"
|
||||
|
||||
type InjectedDependencies = {
|
||||
eventBusService: EventBusService,
|
||||
sendgridService: any
|
||||
}
|
||||
|
||||
class CustomerConfirmationSubscriber {
|
||||
protected sendGridService: any
|
||||
|
||||
constructor({
|
||||
eventBusService,
|
||||
sendgridService,
|
||||
}: InjectedDependencies) {
|
||||
this.sendGridService = sendgridService
|
||||
eventBusService.subscribe(
|
||||
"customer.created",
|
||||
this.handleCustomerConfirmation
|
||||
)
|
||||
}
|
||||
|
||||
handleCustomerConfirmation = async (data: Customer) => {
|
||||
this.sendGridService.sendEmail({
|
||||
templateId: "customer-confirmation",
|
||||
from: "hello@medusajs.com",
|
||||
to: data.email,
|
||||
data: {
|
||||
// any data necessary for your template...
|
||||
first_name: data.first_name,
|
||||
last_name: data.last_name,
|
||||
},
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
export default CustomerConfirmationSubscriber
|
||||
```
|
||||
|
||||
Notice that you should replace the values in the object passed to the `sendEmail` method:
|
||||
|
||||
- `templateId`: Should be the ID of your confirmation email template in SendGrid.
|
||||
- `from`: Should be the from email.
|
||||
- `to`: Should be the customer’s email.
|
||||
- `data`: Should be an object holding any data that should be passed to your SendGrid email template.
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
description: 'Learn what Customer Groups are and how they can be used in the Medusa backend. Customer Groups allow to combine customers with similar attributes into a single group.'
|
||||
---
|
||||
|
||||
# Customer Groups
|
||||
|
||||
In this document, you’ll learn about Customer Groups and how they can be used in Medusa.
|
||||
|
||||
## Introduction
|
||||
|
||||
Customer groups allow you to combine customers with similar attributes such as purchase habits, region, or for any reason that works for your business model.
|
||||
|
||||
You can then assign different prices for customer groups using price lists.
|
||||
|
||||
### Examples Use Cases
|
||||
|
||||
The customer groups feature can be used in a variety of use cases including:
|
||||
|
||||
- Implement a B2B business model by assigning a specific customer group for wholesale customers.
|
||||
- Combine customers that make purchases frequently into a group and give them a special discount.
|
||||
- Create different customer groups based on different buyer personas.
|
||||
|
||||
---
|
||||
|
||||
## CustomerGroup Entity Overview
|
||||
|
||||
A customer group is stored in the database as a [CustomerGroup](../../references/entities/classes/CustomerGroup.md) entity. This entity has two attributes other than the `id`: `name` and `metadata`.
|
||||
|
||||
Similar to all entities in Medusa, you can use the `metadata` object attribute to store any custom data you want. For example, you can add some flag or tag to the customer group for a custom use case:
|
||||
|
||||
```js noReport
|
||||
metadata: {
|
||||
is_seller: true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Relations to Other Entities
|
||||
|
||||
### Customer
|
||||
|
||||
A customer can belong to multiple customer groups, and a customer group can have more than one customer. After creating a customer group, you can manage customers in that group.
|
||||
|
||||
The relation between the `Customer` and `CustomerGroup` entities is available on both entities:
|
||||
|
||||
- You can access the customer groups of a customer by expanding the `groups` relation and accessing `customer.groups`.
|
||||
- You can access the customers in a customer group by expanding the `customers` relation and accessing `customerGroup.customers`.
|
||||
|
||||
### PriceList
|
||||
|
||||
A price list can have multiple conditions to define in which cases it should be applied. One of those conditions is customer groups. You can specify more than one customer group to apply the prices on.
|
||||
|
||||
The relation between the `PriceList` and `CustomerGroup` entities is available on both entities:
|
||||
|
||||
- You can access the customer groups of a price list by expanding the `customer_groups` relation and accessing `price_list.customer_groups`.
|
||||
- You can access the price lists that are applied to a customer group by expanding the `price_lists` relation and accessing `customerGroup.price_lists`.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Manage customer groups using the Admin APIs](./admin/manage-customer-groups.mdx)
|
||||
@@ -0,0 +1,81 @@
|
||||
---
|
||||
description: 'Learn about what Customers are in Medusa and how they are implemented. Customers are individuals that make purchases in your store.'
|
||||
---
|
||||
|
||||
# Customers
|
||||
|
||||
In this document, you’ll learn about Customers and their relation to other entities in Medusa.
|
||||
|
||||
## Introduction
|
||||
|
||||
Customers are individuals that make purchases in your store. In Medusa, there are two types of customers: registered customers and guests or unregistered customers.
|
||||
|
||||
Both registered and unregistered customers can make purchases. However, only registered customers can log into their accounts and manage their details and orders.
|
||||
|
||||
An admin user can view and manage their customers, their details, their orders, and what customer group they’re in.
|
||||
|
||||
---
|
||||
|
||||
## Customer Entity Overview
|
||||
|
||||
A customer is stored in the database as a `Customer` entity. A customer has attributes related to the customer’s details such as `first_name`, `last_name`, and `phone`. However, the only required attribute is `email`.
|
||||
|
||||
### has_account Attribute
|
||||
|
||||
As mentioned earlier, customers can be either registered or unregistered. The type of customer is identified in the `has_account` attribute. This is a boolean attribute that indicates whether the customer is registered.
|
||||
|
||||
For example, when a guest customer places an order, a new `Customer` record is created with the email used (if it doesn’t already exist) and the value for `has_account` is `false`. When the unregistered customer creates an account using the same email, a new `Customer` record will be created with the value of `has_account` set to `true`.
|
||||
|
||||
### Email Uniqueness
|
||||
|
||||
An email is unique to a type of customer. So, an email can be associated with only one registered customer (where `has_account` is `true`), and one unregistered customer (where `has_account` is `false`).
|
||||
|
||||
In the example mentioned above, after the unregistered customer places an order with an email, then creates an account with the same email, two `Customer` records are created. Each of these records have different `has_account` value.
|
||||
|
||||
:::info
|
||||
|
||||
This architecture allows creating the Claim Order flow, where a registered customer can claim an order they placed as an unregistered customer. You can learn more about it in [this documentation](../orders/storefront/implement-claim-order.mdx).
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Relations to Other Entities
|
||||
|
||||
### CustomerGroup
|
||||
|
||||
Customer groups allow dividing customers into groups of similar attributes, then apply special pricing or rules for these customer groups.
|
||||
|
||||
:::info
|
||||
|
||||
You can learn more about customer groups in [this documentation](./customer-groups.md).
|
||||
|
||||
:::
|
||||
|
||||
A customer can belong to more than one customer group. The relation between the `Customer` and `CustomerGroup` entities is available on both entities:
|
||||
|
||||
- You can access the customer groups of a customer by expanding the `groups` relation and accessing `customer.groups`.
|
||||
- You can access the customers in a customer group by expanding the `customers` relation and accessing `customerGroup.customers`.
|
||||
|
||||
### Orders
|
||||
|
||||
Customers can have more than one order. The relation between the `Customer` and `Order` entities is available on both entities:
|
||||
|
||||
- You can access the orders of a customer by expanding the `orders` relation and accessing `customer.orders`.
|
||||
- You can access the customer that placed an order by expanding the `customer` relation and accessing `order.customer`.
|
||||
|
||||
### Address
|
||||
|
||||
A customer can have a billing address and more than one shipping address. Both billing and shipping addresses are represented by the `Address` entity.
|
||||
|
||||
The relation between the `Customer` and `Address` entities is available on both entities:
|
||||
|
||||
- You can access the billing address of a customer by expanding the `billing_address` relation and accessing `customer.billing_address`. You can also access the shipping addresses of a customer by expanding the `shipping_addresses` relation and accessing `customer.shipping_addresses`.
|
||||
- Likewise, you can access the customer that an address is associated with by expanding the `customer` relation and accessing `address.customer`.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Implement customer profiles in the storefront](./storefront/implement-customer-profiles.mdx)
|
||||
- [Manage customers using the admin APIs](./admin/manage-customers.mdx)
|
||||
@@ -0,0 +1,155 @@
|
||||
---
|
||||
description: "Customers are individuals that make purchases in your store. Learn about the available features and guides."
|
||||
---
|
||||
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import Icons from '@theme/Icon';
|
||||
|
||||
# Customers
|
||||
|
||||
Customers are individuals that make purchases in your store. This overview introduces the available features related to customers.
|
||||
|
||||
:::note
|
||||
|
||||
Not a developer? Check out the [Customers user guide](../../user-guide/customers/index.md).
|
||||
|
||||
:::
|
||||
|
||||
## Features
|
||||
|
||||
### Customer Accounts
|
||||
|
||||
Customers can make purchases as guests, or they can create an account.
|
||||
|
||||
When a customer creates an account, they can manage their details and review their order history.
|
||||
|
||||
An admin can manage all customers and their details.
|
||||
|
||||
<DocCardList colSize={4} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/customers/storefront/implement-customer-profiles',
|
||||
label: 'Storefront: Add Customer Profiles',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to implement customer accounts in a storefront.',
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/customers/admin/manage-customers',
|
||||
label: 'Admin: Manage Customers',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to manage customers using Admin APIs.',
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/user-guide/customers/manage',
|
||||
label: 'User Guide: Manage Customers',
|
||||
customProps: {
|
||||
icon: Icons['users-solid'],
|
||||
description: 'Learn how to manage customers in Medusa Admin.'
|
||||
}
|
||||
},
|
||||
]} />
|
||||
|
||||
### Customer Groups
|
||||
|
||||
Admins can segment customers or assign them to different customer groups. This can be useful for marketing purposes.
|
||||
|
||||
For example, an admin can specify a different pricing or special discounts for specific customer groups.
|
||||
|
||||
<DocCardList colSize={4} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/customers/admin/manage-customer-groups',
|
||||
label: 'Admin: Manage Customer Groups',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to manage customer groups using Admin APIs.',
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/user-guide/customers/groups',
|
||||
label: 'User Guide: Customer Groups',
|
||||
customProps: {
|
||||
icon: Icons['users-solid'],
|
||||
description: 'Learn how to manage customer groups in Medusa Admin.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: 'https://docs.medusajs.com/api/admin#customer-groups',
|
||||
label: 'Admin APIs: Customer Groups',
|
||||
customProps: {
|
||||
icon: Icons['server-solid'],
|
||||
description: 'Check available Admin REST APIs for Customer Groups.'
|
||||
}
|
||||
},
|
||||
]} />
|
||||
|
||||
---
|
||||
|
||||
## Understand the Architecture
|
||||
|
||||
Learn how Customer-related entities are built, their relation to other modules, and more.
|
||||
|
||||
<DocCardList colSize={6} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/customers',
|
||||
label: 'Architecture: Customer',
|
||||
customProps: {
|
||||
icon: Icons['circle-stack-solid'],
|
||||
description: 'Learn about the Customer Architecture.',
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/customers/customer-groups',
|
||||
label: 'Architecture: Customer Group',
|
||||
customProps: {
|
||||
icon: Icons['circle-stack-solid'],
|
||||
description: 'Learn about the Customer Group Architecture.',
|
||||
}
|
||||
},
|
||||
]} />
|
||||
|
||||
---
|
||||
|
||||
## Related Modules
|
||||
|
||||
Discover Customers’ relation to other modules in Medusa.
|
||||
|
||||
<DocCardList colSize={4} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/orders/overview',
|
||||
label: 'Orders',
|
||||
customProps: {
|
||||
icon: Icons['check-circle-solid'],
|
||||
description: 'Customers can place orders, request returns and exchanges, and more.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/discounts/overview',
|
||||
label: 'Discounts',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Discounts can be associated with a specific customer group.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/price-lists/overview',
|
||||
label: 'Price Lists',
|
||||
customProps: {
|
||||
icon: Icons['currency-dollar-solid'],
|
||||
description: 'Set special prices for specific customer groups.'
|
||||
}
|
||||
},
|
||||
]} />
|
||||
@@ -0,0 +1,668 @@
|
||||
---
|
||||
description: 'Learn how to implement customer account functionalities in your storefront using the REST APIs. This includes implementing customer registration, login, edit profile, and more.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# How to Implement Customer Profiles
|
||||
|
||||
In this document, you’ll learn how to implement customer account functionalities in a storefront.
|
||||
|
||||
## Overview
|
||||
|
||||
Medusa provides the necessary functionalities and endpoints to allow integrating essential customer features. Customers can create accounts to manage their information and keep track of their orders.
|
||||
|
||||
### Scenario
|
||||
|
||||
You want to implement the following features in a storefront:
|
||||
|
||||
- Customer registration
|
||||
- Customer login and logout
|
||||
- Allow customers to reset their password
|
||||
- Allow customers to manage their basic information and shipping addresses
|
||||
- Show customers their orders
|
||||
|
||||
:::note
|
||||
|
||||
You can use Medusa’s Store APIs to achieve more functionalities as well. Check out the [API reference](https://docs.medusajs.com/api/store#customers) to learn more.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa Components
|
||||
|
||||
It's 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.
|
||||
|
||||
It's also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install the [Next.js Starter Template](../../../starters/nextjs-medusa-starter.mdx).
|
||||
|
||||
### 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 installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#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).
|
||||
|
||||
---
|
||||
|
||||
## Register a Customer
|
||||
|
||||
A customer can register with an email and a password to store and manage their data.
|
||||
|
||||
You can register a new customer by sending a request to the [Create a Customer](https://docs.medusajs.com/api/store#customers_postcustomers) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.customers.create({
|
||||
email,
|
||||
password,
|
||||
first_name,
|
||||
last_name,
|
||||
})
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useCreateCustomer } from "medusa-react"
|
||||
|
||||
const RegisterCustomer = () => {
|
||||
const createCustomer = useCreateCustomer()
|
||||
// ...
|
||||
|
||||
const handleCreate = () => {
|
||||
// ...
|
||||
createCustomer.mutate({
|
||||
first_name,
|
||||
last_name,
|
||||
email,
|
||||
password,
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
|
||||
return (
|
||||
<form>
|
||||
{/* Render form */}
|
||||
</form>
|
||||
)
|
||||
}
|
||||
|
||||
export default RegisterCustomer
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/customers`, {
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
email,
|
||||
password,
|
||||
first_name,
|
||||
last_name,
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires the following body parameters:
|
||||
|
||||
- `email`: An email used to log in after registration. This email must be unique. You can check if an email is unique using the “[Check if email exists](https://docs.medusajs.com/api/store#auth_getauthemail)” endpoint.
|
||||
- `password`: A password used to log in after registration.
|
||||
- `first_name`: The customer’s first name.
|
||||
- `last_name`: The customer’s last name.
|
||||
|
||||
This request also accepts optional body parameters, which you can check out in the [API reference](https://docs.medusajs.com/api/store#customers_postcustomers).
|
||||
|
||||
It returns the created customer object in the response.
|
||||
|
||||
---
|
||||
|
||||
## Log in a Customer
|
||||
|
||||
A customer can log in to your store to manage their data and make purchases using their account.
|
||||
|
||||
You can log in a customer into your store by sending a request to the [Customer Login](https://docs.medusajs.com/api/store#auth_postauth) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.auth.authenticate({
|
||||
email,
|
||||
password,
|
||||
})
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/auth`, {
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
email,
|
||||
password,
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires the body parameters `email` and `password`. It returns the customer object in the response.
|
||||
|
||||
If you’re using the Medusa JS Client, the customer’s session will already be set and used in all future requests.
|
||||
|
||||
However, if you’re using the Fetch API, you must include the option `credentials` with the value `include` to make sure all future requests are authenticated.
|
||||
|
||||
---
|
||||
|
||||
## Log out a Customer
|
||||
|
||||
You can log out a customer by sending a request to the [Customer Logout](https://docs.medusajs.com/api/store#auth_deleteauth) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.auth.deleteSession()
|
||||
.then(() => {
|
||||
// success
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/auth`, {
|
||||
method: "DELETE",
|
||||
credentials: "include",
|
||||
})
|
||||
.then(() => {
|
||||
// success
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
If this request is successful, the customer’s session will be deleted and they’ll be logged out.
|
||||
|
||||
---
|
||||
|
||||
## Reset Password
|
||||
|
||||
Customers might need to reset their password in case they forget it. To reset a customer’s password, you need to implement two steps.
|
||||
|
||||
### Step 1: Request Password Reset
|
||||
|
||||
The customer must first enter their account’s email. Then, if an account with that email address exists, an email will be sent to that email address with a link that points the customer to step 2.
|
||||
|
||||
You can request to reset a customer’s password by sending a request to the [Request Password Reset](https://docs.medusajs.com/api/store#customers_postcustomerscustomerpasswordtoken) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.customers.generatePasswordToken({
|
||||
email,
|
||||
})
|
||||
.then(() => {
|
||||
// successful
|
||||
})
|
||||
.catch(() => {
|
||||
// failed
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/customers/password-token`, {
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
email,
|
||||
}),
|
||||
})
|
||||
.then(() => {
|
||||
// successful
|
||||
})
|
||||
.catch(() => {
|
||||
// failed
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires the body parameter `email`. Its value must be the email associated with the customer’s account.
|
||||
|
||||
If the request has been processed successfully, it returns a `204` status code in the response. In case it fails, an error will be thrown.
|
||||
|
||||
:::note
|
||||
|
||||
If the customer doesn’t receive an email after this request, make sure that you’ve set up a Notification provider like [SendGrid](../../../plugins/notifications/sendgrid.mdx) successfully. You also need to add a subscriber that handles the [customer.password_reset](../../../development/events/events-list.md#customer-events) event and sends the email.
|
||||
|
||||
:::
|
||||
|
||||
### Step 2: Verify and Reset Password
|
||||
|
||||
After the first step, the customer should receive an email with a link to a page in the storefront. This page should accept a `token` query parameter. Then, the customer should be prompted to enter their email and password.
|
||||
|
||||
You can then reset the customer’s password to the new password they enter by sending a request to the [Reset Password](https://docs.medusajs.com/api/store#customers_postcustomersresetpassword) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.customers.resetPassword({
|
||||
email,
|
||||
password,
|
||||
token,
|
||||
})
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/customers/password-reset`, {
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
email,
|
||||
password,
|
||||
token,
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires the following body parameters:
|
||||
|
||||
- `email`: The email of the customer. This must be the email associated with the account.
|
||||
- `password`: The new password the customer wants to use for their account.
|
||||
- `token`: The token passed as a query into the page.
|
||||
|
||||
If successful, this request returns the customer object in the response.
|
||||
|
||||
---
|
||||
|
||||
## Edit a Customer’s Info
|
||||
|
||||
A logged-in customer can edit their info, such as their first name or email address.
|
||||
|
||||
You can edit a customer’s info using the [Update Customer](https://docs.medusajs.com/api/store#customers_postcustomerscustomer) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.customers.update({
|
||||
first_name,
|
||||
})
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useUpdateMe } from "medusa-react"
|
||||
|
||||
const UpdateCustomer = () => {
|
||||
const updateCustomer = useUpdateMe()
|
||||
// ...
|
||||
|
||||
const handleUpdate = () => {
|
||||
// ...
|
||||
updateCustomer.mutate({
|
||||
id: customer_id,
|
||||
first_name,
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
|
||||
return (
|
||||
<form>
|
||||
{/* Render form */}
|
||||
</form>
|
||||
)
|
||||
}
|
||||
|
||||
export default UpdateCustomer
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/customers/me`, {
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
first_name,
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request accepts any of the customer’s details that should be updated as body parameters. In the example above, the `first_name` of the customer is updated. You can check out the [API reference](https://docs.medusajs.com/api/api/store#customers_postcustomerscustomer) for a full list of accepted body parameters.
|
||||
|
||||
It returns in the response the updated customer object.
|
||||
|
||||
---
|
||||
|
||||
## Manage Shipping Addresses
|
||||
|
||||
A logged-in customer uses their shipping addresses during the checkout process. They can have more than one shipping address, and they can choose one of them when placing an order.
|
||||
|
||||
:::tip
|
||||
|
||||
The customer object returned in the requests mentioned in this document include a `shipping_addresses` property. It’s an array of the customer’s shipping addresses. You can access it to display the customer’s shipping addresses.
|
||||
|
||||
:::
|
||||
|
||||
### Add a Shipping Address
|
||||
|
||||
You can add a shipping address to a customer’s account by sending a request to the [Add a Shipping Address](https://docs.medusajs.com/api/store#customers_postcustomerscustomeraddresses) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.customers.addresses.addAddress({
|
||||
address: {
|
||||
first_name,
|
||||
last_name,
|
||||
address_1,
|
||||
city,
|
||||
country_code,
|
||||
postal_code,
|
||||
phone,
|
||||
company,
|
||||
address_2,
|
||||
province,
|
||||
metadata,
|
||||
},
|
||||
})
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/customers/me/addresses`, {
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
address: {
|
||||
first_name,
|
||||
last_name,
|
||||
address_1,
|
||||
city,
|
||||
country_code,
|
||||
postal_code,
|
||||
phone,
|
||||
company,
|
||||
address_2,
|
||||
province,
|
||||
metadata,
|
||||
},
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires an `address` object as a body parameter. The `address` object must have the following properties:
|
||||
|
||||
- `first_name`: The first name associated with the shipping address
|
||||
- `last_name`: The last name associated with the shipping address
|
||||
- `address_1`: The first address line of the shipping address.
|
||||
- `city`: The city of the shipping address.
|
||||
- `country_code`: The 2 character ISO code of the country in lower case.
|
||||
- `postal_code`: The postal code of the shipping address
|
||||
|
||||
It also accepts other optional body parameters, which you can learn more about in the [API reference](https://docs.medusajs.com/api/store#customers_postcustomerscustomeraddresses).
|
||||
|
||||
This request returns the updated customer object in the response.
|
||||
|
||||
### Edit a Shipping Address
|
||||
|
||||
You can edit a customer’s shipping address using the [Update a Shipping Address](https://docs.medusajs.com/api/store#customers_postcustomerscustomeraddressesaddress) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.customers.addresses.updateAddress(addressId, {
|
||||
first_name,
|
||||
})
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/customers/me/addresses/${addressId}`,
|
||||
{
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
first_name,
|
||||
}),
|
||||
}
|
||||
)
|
||||
.then((response) => response.json())
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires the address’s ID as a path parameter. It accepts as a body parameter any of the address’s properties. In the example above, the `first_name` of the shipping address is updated. You can check the [API reference](https://docs.medusajs.com/api/store#customers_postcustomerscustomeraddressesaddress) for all the available body parameters.
|
||||
|
||||
This request returns the updated customer object in the response.
|
||||
|
||||
### Delete a Shipping Address
|
||||
|
||||
You can delete a shipping address by sending a request to the [Delete an Address](https://docs.medusajs.com/api/store#customers_deletecustomerscustomeraddressesaddress) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.customers.addresses.deleteAddress(addressId)
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/customers/me/addresses/${addressId}`,
|
||||
{
|
||||
method: "DELETE",
|
||||
credentials: "include",
|
||||
}
|
||||
)
|
||||
.then((response) => response.json())
|
||||
.then(({ customer }) => {
|
||||
console.log(customer.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires the address’s ID as a path parameter. It returns in the response the updated customer object.
|
||||
|
||||
---
|
||||
|
||||
## Retrieve a Customer’s Orders
|
||||
|
||||
Logged-in customers can see their orders along with the orders’ details.
|
||||
|
||||
You can retrieve a customer’s orders by sending a request to the [List Orders](https://docs.medusajs.com/api/store#customers_getcustomerscustomerorders) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.customers.listOrders()
|
||||
.then(({ orders, limit, offset, count }) => {
|
||||
console.log(orders)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useCustomerOrders } from "medusa-react"
|
||||
import { Order } from "@medusajs/medusa"
|
||||
|
||||
const Orders = () => {
|
||||
// refetch a function that can be used to
|
||||
// re-retrieve orders after the customer logs in
|
||||
const { orders, isLoading, refetch } = useCustomerOrders()
|
||||
|
||||
return (
|
||||
<div>
|
||||
{isLoading && <span>Loading orders...</span>}
|
||||
{orders?.length && (
|
||||
<ul>
|
||||
{orders.map((order: Order) => (
|
||||
<li key={order.id}>{order.display_id}</li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default Orders
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/customers/me/orders`, {
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ orders, limit, offset, count }) => {
|
||||
console.log(orders)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request doesn’t require any path or query parameters. You can, however, send optional query parameters used for filters, pagination, and sorting. You can learn more in the [API reference](https://docs.medusajs.com/api/store#customers_getcustomerscustomerorders).
|
||||
|
||||
It returns the following data in the response:
|
||||
|
||||
- `orders`: An array of orders.
|
||||
- `limit`: The maximum number of orders that can be returned in the request.
|
||||
- `offset`: The number of orders skipped in the result.
|
||||
- `count`: The total number of orders available.
|
||||
|
||||
:::info
|
||||
|
||||
You can learn more about pagination in the [API reference](https://docs.medusajs.com/api/store#pagination).
|
||||
|
||||
:::
|
||||
Reference in New Issue
Block a user