From 123d910ef68396c0ef2942750283c48ae341961d Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Wed, 28 Dec 2022 19:36:18 +0200 Subject: [PATCH] docs: added Manage Customers documentation (#2911) * docs: added Manage Customers documentation * fixed link --- .../advanced/admin/manage-customers.mdx | 230 ++++++++++++++++++ .../advanced/admin/manage-discounts.mdx | 2 +- .../content/advanced/admin/manage-regions.mdx | 2 +- .../advanced/admin/use-customergroups-api.mdx | 2 +- .../advanced/backend/customers/index.md | 1 + .../backend/sales-channels/manage-admin.mdx | 2 +- .../advanced/storefront/customer-profiles.mdx | 1 + www/docs/sidebars.js | 37 +-- www/docs/src/theme/DocItem/Footer/index.js | 2 - 9 files changed, 257 insertions(+), 22 deletions(-) create mode 100644 docs/content/advanced/admin/manage-customers.mdx diff --git a/docs/content/advanced/admin/manage-customers.mdx b/docs/content/advanced/admin/manage-customers.mdx new file mode 100644 index 0000000000..e91cf1009e --- /dev/null +++ b/docs/content/advanced/admin/manage-customers.mdx @@ -0,0 +1,230 @@ +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 server installed and set up. If not, you can follow the [quickstart guide](../../quickstart/quick-start.mdx) to get started. + +### JS Client + +This guide includes code snippets to send requests to your Medusa server 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). + +### 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](/api/admin/#section/Authentication). + +--- + +## List Customers + +You can show a list of customers by sending a request to the [List Customers](/api/admin/#tag/Customer/operation/GetCustomers) endpoint: + + + + +```ts +medusa.admin.customers.list() +.then(({ customers, limit, offset, count }) => { + console.log(customers.length); +}); +``` + + + + +```ts +fetch(`/admin/customers`, { + credentials: 'include', +}) +.then((response) => response.json()) +.then(({ customers, limit, offset, count }) => { + console.log(customers.length); +}); +``` + + + + +```bash +curl -L -X GET '/admin/customers' \ +-H 'Authorization: Bearer ' +``` + + + + +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](/api/admin/#tag/Customer/operation/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](/api/admin/#section/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](/api/admin/#tag/Customer/operation/PostCustomers) endpoint: + + + + +```ts +medusa.admin.customers.create({ + email, + password, + first_name, + last_name +}) +.then(({ customer }) => { + console.log(customer.id); +}); +``` + + + + +```ts +fetch(`/admin/customers`, { + method: 'POST', + credentials: 'include', + body: JSON.stringify({ + email, + password, + first_name, + last_name + }) +}) +.then((response) => response.json()) +.then(({ customer }) => { + console.log(customer.id); +}); +``` + + + + +```bash +curl -L -X POST '/admin/customers' \ +-H 'Authorization: Bearer ' \ +-H 'Content-Type: application/json' \ +--data-raw '{ + "email": "", + "first_name": "", + "last_name": "", + "password": "" +}' +``` + + + + +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](/api/admin/#tag/Customer/operation/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](/api/admin/#tag/Customer/operation/PostCustomersCustomer) endpoint: + + + + +```ts +medusa.admin.customers.update(customerId, { + first_name +}) +.then(({ customer }) => { + console.log(customer.id); +}); +``` + + + + +```ts +fetch(`/admin/customers/${customerId}`, { + method: 'POST', + credentials: 'include', + body: JSON.stringify({ + first_name + }) +}) +.then((response) => response.json()) +.then(({ customer }) => { + console.log(customer.id); +}); +``` + + + + +```bash +curl -L -X POST '/admin/customers/' \ +-H 'Authorization: Bearer ' \ +-H 'Content-Type: application/json' \ +--data-raw '{ + "first_name": "" +}' +``` + + + + +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](/api/admin/#tag/Customer/operation/PostCustomersCustomer). + +This request returns the updated customer object in the response. + +--- + +## See Also + +- [Manage customer groups](./use-customergroups-api.mdx) +- [Customers admin API reference](/api/admin) +- [Customers overview](../backend/customers/index.md) +- [Implement customer profiles in the storefront](../storefront/customer-profiles.mdx) diff --git a/docs/content/advanced/admin/manage-discounts.mdx b/docs/content/advanced/admin/manage-discounts.mdx index 16631968fa..c533a6559a 100644 --- a/docs/content/advanced/admin/manage-discounts.mdx +++ b/docs/content/advanced/admin/manage-discounts.mdx @@ -1,7 +1,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Manage Discounts using Admin APIs +# How to Manage Discounts using Admin APIs In this document, you’ll learn how to use the Admin’s Discount APIs to manage discounts, discount conditions, and more. diff --git a/docs/content/advanced/admin/manage-regions.mdx b/docs/content/advanced/admin/manage-regions.mdx index 0fdca9b319..a2d73bcbf8 100644 --- a/docs/content/advanced/admin/manage-regions.mdx +++ b/docs/content/advanced/admin/manage-regions.mdx @@ -1,7 +1,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Manage Regions using Admin APIs +# How to Manage Regions using Admin APIs In this document, you’ll learn how to manage regions using the Admin APIs. diff --git a/docs/content/advanced/admin/use-customergroups-api.mdx b/docs/content/advanced/admin/use-customergroups-api.mdx index c00f77b8d4..e353c1a692 100644 --- a/docs/content/advanced/admin/use-customergroups-api.mdx +++ b/docs/content/advanced/admin/use-customergroups-api.mdx @@ -1,7 +1,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# How to Use CustomerGroup APIs +# 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. diff --git a/docs/content/advanced/backend/customers/index.md b/docs/content/advanced/backend/customers/index.md index 3cacf8a3b3..1f5d6cb104 100644 --- a/docs/content/advanced/backend/customers/index.md +++ b/docs/content/advanced/backend/customers/index.md @@ -74,4 +74,5 @@ The relation between the `Customer` and `Address` entities is available on both ## See Also - [Implement customer profiles in the storefront](../../storefront/customer-profiles.mdx) +- [Manage customers using the admin APIs](../../admin/manage-customers.mdx) - Customers [Admin](/api/admin/#tag/Customer) and [Storefront](/api/store/#tag/Customer) API References diff --git a/docs/content/advanced/backend/sales-channels/manage-admin.mdx b/docs/content/advanced/backend/sales-channels/manage-admin.mdx index a9dfa95e6e..b1211b7e28 100644 --- a/docs/content/advanced/backend/sales-channels/manage-admin.mdx +++ b/docs/content/advanced/backend/sales-channels/manage-admin.mdx @@ -1,7 +1,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# How to Use SalesChannels APIs +# How to Manage Sales Channels In this document, you’ll learn how to manage sales channels and their products and orders using the Admin APIs. diff --git a/docs/content/advanced/storefront/customer-profiles.mdx b/docs/content/advanced/storefront/customer-profiles.mdx index 9a59a84184..8a1f5435d0 100644 --- a/docs/content/advanced/storefront/customer-profiles.mdx +++ b/docs/content/advanced/storefront/customer-profiles.mdx @@ -547,3 +547,4 @@ You can learn more about pagination in the [API reference](/api/store/#section/P - [Implement order-claim flow](./implement-claim-order.mdx) - [Customers Store API reference](/api/store) - [Customers overview](../backend/customers/index.md) +- [Manage customers using the admin APIs](../admin/manage-customers.mdx) diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index cc2e2371be..5616fd8b12 100644 --- a/www/docs/sidebars.js +++ b/www/docs/sidebars.js @@ -290,8 +290,18 @@ module.exports = { items: [ { type: "doc", - id: "advanced/admin/manage-regions", - label: "Manage Regions" + id: "advanced/admin/order-edit", + label: "Edit an Order" + }, + { + type: "doc", + id: "advanced/admin/manage-customers", + label: "Manage Customers" + }, + { + type: "doc", + id: "advanced/admin/use-customergroups-api", + label: "Manage Customer Groups" }, { type: "doc", @@ -306,27 +316,22 @@ module.exports = { { type: "doc", id: "advanced/backend/price-lists/use-api", - label: "Use PriceList APIs" - }, - { - type: "doc", - id: "advanced/backend/sales-channels/manage-admin", - label: "Use SalesChannel APIs" - }, - { - type: "doc", - id: "advanced/admin/use-customergroups-api", - label: "Use CustomerGroup APIs" + label: "Manage PriceLists" }, { type: "doc", id: "advanced/admin/manage-discounts", - label: "Use Discount APIs" + label: "Manage Discounts" }, { type: "doc", - id: "advanced/admin/order-edit", - label: "Edit an Order" + id: "advanced/admin/manage-regions", + label: "Manage Regions" + }, + { + type: "doc", + id: "advanced/backend/sales-channels/manage-admin", + label: "Manage Sales Channels" }, ] }, diff --git a/www/docs/src/theme/DocItem/Footer/index.js b/www/docs/src/theme/DocItem/Footer/index.js index 57a8d9c0a4..3776679a9e 100644 --- a/www/docs/src/theme/DocItem/Footer/index.js +++ b/www/docs/src/theme/DocItem/Footer/index.js @@ -8,8 +8,6 @@ export default function FooterWrapper(props) { const { metadata } = useDoc() const { footerFeedback = { event: '' } } = useThemeConfig(); - console.log(footerFeedback) - return ( <> {!metadata.frontMatter?.hide_footer && (