Medusa How-to & Tutorials

https://docs.medusajs.com/resources/how-to-tutorials
Admin
This section provides how-to guides and tutorials for customizing the Medusa e-commerce server and...
Tokens:138,296
Snippets:878
Trust Score:9.8
Update:8 months ago
Show doc for...
Tokens:
Raw
### Start Medusa Application

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/first-purchase-discounts/index.html

Starts the Medusa backend development server. This command is used after installation to run your Medusa application locally. Ensure you have Node.js and npm/yarn installed.

```bash
npm run dev
```

--------------------------------

### Start Medusa Application

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/saved-payment-methods/index.html

This command starts the Medusa application. It is a prerequisite for testing saved payment methods.

```bash
npm run dev
```

```bash
yarn dev
```

--------------------------------

### Install Medusa Application

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/first-purchase-discounts/index.html

Installs a new Medusa application and the Next.js Starter Storefront. This command requires Node.js v20+ and Git. It sets up both the headless backend and a frontend for your e-commerce platform.

```bash
npx create-medusa-app@latest
```

--------------------------------

### Install jsonwebtoken for Phone Authentication Module

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/phone-auth

Before implementing the phone authentication module, you need to install the 'jsonwebtoken' package. This is a prerequisite for handling JWTs within the authentication process.

```bash
npm install jsonwebtoken
# or
yarn add jsonwebtoken
```

--------------------------------

### Install Twilio SDK (Yarn)

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/phone-auth

Installs the Twilio SDK package using Yarn, which is required to interact with the Twilio API for sending SMS notifications.

```bash
yarn add twilio
```

--------------------------------

### Install Medusa Application with Next.js Starter

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/gift-message

Installs a Medusa application and the Next.js Starter Storefront using yarn. This sets up the backend and a basic frontend for customization.

```bash
yarn dlx create-medusa-app@latest
```

--------------------------------

### Run Medusa Application and Next.js Storefront

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/saved-payment-methods/index.html

Commands to start the Medusa backend application and the Next.js Starter Storefront. Ensure you are in the respective application directories before running these commands.

```bash
npm run dev
```

```bash
npm run dev
```

--------------------------------

### Install Phone Input Package for Next.js Storefront

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/phone-auth

To enhance the user experience in the Next.js storefront, install a dedicated phone input package. This package provides a user-friendly interface for entering phone numbers.

```bash
npm install react-phone-number-input
# or
yarn add react-phone-number-input
```

--------------------------------

### Install react-phone-number-input for Storefront

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/phone-auth

This command installs the 'react-phone-number-input' package using Yarn. This package provides a user interface component for easily inputting and validating phone numbers in the Next.js Starter Storefront, facilitating phone authentication.

```bash
yarn add react-phone-number-input
```

--------------------------------

### Start Medusa Application (Shell)

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/saved-payment-methods

Command to start the Medusa backend application in development mode. This is necessary for the storefront to connect to the API.

```shell
yarn dev
```

--------------------------------

### Install PDF Generation Dependencies

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/invoice-generator

Installs the necessary libraries for PDF generation in your Medusa.js project. `pdfmake` is used for creating PDFs, and `@types/pdfmake` provides TypeScript support.

```bash
yarn add pdfmake
yarn add --dev @types/pdfmake
```

```bash
pnpm add pdfmake
pnpm add --dev @types/pdfmake
```

```bash
npm install pdfmake
npm install --save-dev @types/pdfmake
```

--------------------------------

### Create Loyalty Points API Route (TypeScript)

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/loyalty-points

This snippet shows how to create a GET API route at `/store/customers/me/loyalty-points` to retrieve the authenticated customer's loyalty points using the Loyalty Module Service. It resolves the service from the Medusa container and accesses the authenticated customer ID from the request context.

```typescript
import {
  AuthenticatedMedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { LOYALTY_MODULE } from "../../../modules/loyalty"
import LoyaltyModuleService from "../../../modules/loyalty/service"

export async function GET(
  req: AuthenticatedMedusaRequest,
  res: MedusaResponse
) {
  const loyaltyModuleService: LoyaltyModuleService = req.scope.resolve(
    LOYALTY_MODULE
  )

  const points = await loyaltyModuleService.getPoints(
    req.auth_context.actor_id
  )

  res.json({
    points,
  })
}
```

--------------------------------

### Create Category Media Modal Component (TypeScript)

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/category-images

This snippet shows the initial setup of the `CategoryMediaModal` component in TypeScript. It includes defining props, state variables for modal open status, uploaded files, thumbnail ID, and references for file inputs. It also integrates custom hooks for image mutations and Tanstack Query for data management.

```tsx
import { useCategoryImageMutations } from "../../hooks/use-category-image"
import { useState, useRef } from "react"
import { useQueryClient } from "@tanstack/react-query"
import { toast } from "react-hot-toast"

type CategoryImage = {
  id: string
  url: string
  type: "thumbnail" | "image" | "gallery"
}

type UploadedFile = {
  id: string
  url: string
  type: "thumbnail" | "image" | "gallery"
}

type CategoryMediaModalProps = {
  categoryId: string
  existingImages: CategoryImage[]
}

export const CategoryMediaModal = ({
  categoryId,
  existingImages,
}: CategoryMediaModalProps) => {
  const [open, setOpen] = useState(false)
  const [uploadedFiles, setUploadedFiles] = useState<UploadedFile[]>([])
  const [currentThumbnailId, setCurrentThumbnailId] = useState<string | null>(
    null
  )
  const fileInputRef = useRef<HTMLInputElement>(null)
  const queryClient = useQueryClient()

  const {
    uploadFilesMutation,
    createImagesMutation,
  } = useCategoryImageMutations({
    categoryId,
    onCreateSuccess: () => {
      setOpen(false)
      resetModalState()
    },
  })

  const isSaving = 
    createImagesMutation.isPending

  // TODO add functions
```

--------------------------------

### Create Reorder Workflow in TypeScript

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/re-order/index.html

This snippet demonstrates how to create a reorder workflow using MedusaJS's Workflows SDK. It defines the input type and uses `createWorkflow` to initialize the workflow, starting with fetching order details via `useQueryGraphStep`. Dependencies include `@medusajs/framework/workflows-sdk` and `@medusajs/medusa/core-flows`.

```typescript
import {
  createWorkflow,
  transform,
  WorkflowResponse,
} from "@medusajs/framework/workflows-sdk"
import {
  addShippingMethodToCartWorkflow,
  createCartWorkflow,
  useQueryGraphStep,
} from "@medusajs/medusa/core-flows"

type ReorderWorkflowInput = {
  order_id: string
}

export const reorderWorkflow = createWorkflow(
  "reorder",
  ({ order_id }: ReorderWorkflowInput) => {
    const { data: orders } = useQueryGraphStep({
      entity: "order",
      fields: [
        "*",
        "items.*",
        "shipping_address.*",
        "billing_address.*",
        "region.*",
        "sales_channel.*",
        "shipping_methods.*",
        "customer.*",
      ],
      filters: {
        id: order_id,
      },
    })

    // TODO create a cart with the order's items
  }
)

```

--------------------------------

### Navigate to Storefront Directory

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/re-order

This command changes the current directory to the Next.js Starter Storefront. Ensure you replace `{your-project-storefront}` with the actual name of your storefront directory. This is a prerequisite for modifying storefront files.

```bash
cd ../{your-project-storefront} # change based on your project name
```

--------------------------------

### Navigate to Storefront Directory

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/category-images/index.html

Provides instructions on how to navigate to the Next.js Starter Storefront directory. This is a prerequisite for making storefront-related updates, such as displaying category images.

```bash
cd ../medusa-category-images-storefront # change based on your project name
```

--------------------------------

### Change Directory to Storefront Project

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/saved-payment-methods

This command demonstrates navigating to the Next.js Starter Storefront project directory from the Medusa backend project. Adjust the path based on your project's naming convention.

```bash
cd ../medusa-payment-storefront # change based on your project name
```

--------------------------------

### Abandoned Cart Email Template Example (HTML)

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/abandoned-cart

An example HTML template for abandoned cart emails. This template displays product details, a call-to-action button, and dynamic content placeholders for customer and item information. It is designed for use with SendGrid's dynamic templating system.

```html
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Complete Your Purchase</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            background-color: #f8f9fa;
            margin: 0;
            padding: 20px;
        }
        .container {
            max-width: 600px;
            background: #ffffff;
            padding: 20px;
            border-radius: 10px;
            box-shadow: 0px 4px 10px rgba(0, 0, 0, 0.1);
            text-align: center;
        }
        .header {
            font-size: 26px;
            font-weight: bold;
            color: #333;
            margin-bottom: 20px;
        }
        .message {
            font-size: 16px;
            color: #555;
            margin-bottom: 20px;
        }
        .item {
            display: flex;
            align-items: center;
            background: #f9f9f9;
            padding: 10px;
            border-radius: 8px;
            margin-bottom: 15px;
        }
        .item img {
            width: 80px;
            height: auto;
            margin-right: 15px;
            border-radius: 5px;
        }
        .item-details {
            text-align: left;
            flex-grow: 1;
        }
        .item-details strong {
            font-size: 18px;
            color: #333;
        }
        .item-details p {
            font-size: 14px;
            color: #777;
            margin: 5px 0;
        }
        .button {
            display: inline-block;
            background-color: #007bff;
            color: #ffffff;
            text-decoration: none;
            font-size: 18px;
            padding: 12px 20px;
            border-radius: 5px;
            margin-top: 20px;
            transition: background 0.3s ease;
        }
        .button:hover {
            background-color: #0056b3;
        }
        .footer {
            font-size: 12px;
            color: #888;
            margin-top: 20px;
        }
    </style>
</head>
<body>
    <div class="container">
        <div class="header">Hi {{customer.first_name}}, your cart is waiting! 🛍️</div>
        <p class="message">You left some great items in your cart. Complete your purchase before they're gone!</p>
        
        {{#each items}}
        <div class="item">
            <img src="{{thumbnail}}" alt="{{product_title}}">
            <div class="item-details">
                <strong>{{product_title}}</strong>
                <p>{{subtitle}}</p>
                <p>Quantity: <strong>{{quantity}}</strong></p>
                <p>Price: <strong>$ {{unit_price}}</strong></p>
            </div>
        </div>
        {{/each}}
        
        <a href="https://yourstore.com/cart/recover/{{cart_id}}" class="button">Return to Cart & Checkout</a>
        <p class="footer">Need help? <a href="mailto:support@yourstore.com">Contact us</a></p>
    </div>
</body>
</html>
```

--------------------------------

### Navigate to Storefront Directory (Shell)

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/saved-payment-methods

Command to change the current directory to the Next.js Starter Storefront. This is a prerequisite for running storefront-related commands.

```shell
cd ../{your-project}-storefront
# change based on your project name
```

--------------------------------

### Generate Admin Invoice API Route (TypeScript)

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/invoice-generator

Creates a GET API route at `/admin/orders/:id/invoices` for admin users to download order invoices. It executes the `generateInvoicePdfWorkflow` to get the PDF buffer, reconstructs it using `Buffer.from`, sets appropriate response headers for a PDF file, and sends the buffer as the response.

```typescript
import { MedusaRequest, MedusaResponse } from "@medusajs/framework"
import { generateInvoicePdfWorkflow } from "../../../../../workflows/generate-invoice-pdf"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
): Promise<void> {
  const { id } = req.params

  const { result: {
    pdf_buffer,
  } } = await generateInvoicePdfWorkflow(req.scope)
    .run({
      input: {
        order_id: id,
      },
    })

  const buffer = Buffer.from(pdf_buffer)

  res.set({
    "Content-Type": "application/pdf",
    "Content-Disposition": `attachment; filename="invoice-${id}.pdf"`,
    "Content-Length": buffer.length,
  })
  
  res.send(buffer)
}
```

--------------------------------

### GET /admin/categories/:category_id/images

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/category-images/index.html

Retrieves all images associated with a specific product category.

```APIDOC
## GET /admin/categories/:category_id/images

### Description
Retrieves all images associated with a specific product category.

### Method
GET

### Endpoint
/admin/categories/:category_id/images

### Parameters
#### Path Parameters
- **category_id** (string) - Required - The ID of the product category whose images are to be retrieved.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **category_images** (array) - An array of image objects associated with the category.

#### Response Example
```json
{
  "category_images": [
    {
      "id": "img_xyz789",
      "type": "image",
      "url": "http://example.com/image.jpg",
      "file_id": "file_abc123",
      "category_id": "cat_def456"
    }
  ]
}
```
```

--------------------------------

### GET /store/customers/me/loyalty-points

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/loyalty-points

Retrieves the loyalty points of the authenticated customer. This endpoint is accessible only to authenticated users and returns the customer's loyalty points.

```APIDOC
## GET /store/customers/me/loyalty-points

### Description
Retrieves the loyalty points of the authenticated customer. This endpoint is accessible only to authenticated users and returns the customer's loyalty points.

### Method
GET

### Endpoint
/store/customers/me/loyalty-points

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **points** (number) - The loyalty points of the authenticated customer.

#### Response Example
```json
{
  "points": 150
}
```
```

--------------------------------

### Register Customer API Request (cURL)

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/phone-auth

Registers a new customer by sending a POST request to the /store/customers API route. Requires publishable API key and registration token in headers, and customer details in the request body. Returns the created customer's details.

```curl
curl -X POST 'http://localhost:9000/store/customers' \
--header 'x-publishable-api-key: {publishable_api_key}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {reg_token}' \
--data-raw '{ \
    "email": "+19077890116@gmail.com", \
    "phone": "19077890116", \
    "first_name": "John", \
    "last_name": "Smith" \
}'
```

--------------------------------

### Implement convertCategoryThumbnailsStep Logic in TypeScript

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/category-images

Provides the implementation for the `convertCategoryThumbnailsStep` in TypeScript. It resolves the `ProductMediaModuleService`, finds existing thumbnails, converts them to regular images, and returns the updated images and compensation data. If no thumbnails exist, it returns an empty response.

```typescript
const productMediaService: ProductMediaModuleService =
  container.resolve(PRODUCT_MEDIA_MODULE)

// Find existing thumbnails in the specified categories
const existingThumbnails = await productMediaService.listProductCategoryImages({
  type: "thumbnail",
  category_id: input.category_ids,
})

if (existingThumbnails.length === 0) {
  return new StepResponse([], [])
}

// Store previous states for compensation
const compensationData: string[] = existingThumbnails.map((t) => t.id)

// Convert existing thumbnails to "image" type
await productMediaService.updateProductCategoryImages(
  existingThumbnails.map((t) => ({
    id: t.id,
    type: "image" as const,
  }))
)

return new StepResponse(existingThumbnails, compensationData)
```

--------------------------------

### Generate Invoice Store API Route

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/invoice-generator

This API route allows store users (customers) to download their order invoices. It exposes a GET endpoint at `/store/orders/:id/invoices`.

```APIDOC
## GET /store/orders/:id/invoices

### Description
This endpoint allows store users (customers) to download their specific order's invoice as a PDF.

### Method
GET

### Endpoint
/store/orders/:id/invoices

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the order for which to generate the invoice.

### Request Example
```
GET /store/orders/order_123/invoices
```

### Response
#### Success Response (200)
- **application/pdf** - The generated invoice PDF file.

#### Response Example
(Binary PDF data)
```

--------------------------------

### Create Discount Pop-Up Component (React/TypeScript)

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/first-purchase-discounts

This snippet demonstrates the creation of a discount pop-up component using React and TypeScript for a MedusaJS storefront. It utilizes local storage to ensure the pop-up is only shown to first-time customers. Dependencies include MedusaJS UI components, a custom modal, and a hook for managing modal state.

```tsx
"use client"
import { Button, Heading, Text } from "@medusajs/ui"
import Modal from "@modules/common/components/modal"
import useToggleState from "@lib/hooks/use-toggle-state"
import { useEffect } from "react"
import LocalizedClientLink from "@modules/common/components/localized-client-link"

const DISCOUNT_POPUP_KEY = "discount_popup_shown"

const DiscountPopup = () => {
  const { state, open, close } = useToggleState(false)

  useEffect(() => {
    // Check if the popup has been shown before
    const hasBeenShown = localStorage.getItem(DISCOUNT_POPUP_KEY)

    if (!hasBeenShown) {
      open()
      // Mark as shown
      localStorage.setItem(DISCOUNT_POPUP_KEY, "true")
    }
  }, [open])

  return (
    <Modal isOpen={state} close={close} size="small" data-testid="discount-popup">
      <div className="relative overflow-hidden bg-gradient-to-br from-amber-50 to-amber-100 rounded-t-lg px-6 pt-8 pb-6">
        {/* Decorative elements */}
        <div className="absolute top-0 right-0 w-20 h-20 bg-amber-200 rounded-full -mr-10 -mt-10 opacity-50"></div>
        <div className="absolute bottom-0 left-0 w-16 h-16 bg-amber-200 rounded-full -ml-8 -mb-8 opacity-40"></div>
        
        <div className="relative">
          {/* Sale tag */}
          <div className="absolute -top-2 -right-2 bg-rose-500 text-white text-xs font-bold px-3 py-1 rounded-full transform rotate-12 shadow-md">
            SAVE 10%
          </div>

          <Heading level="h2" className="text-2xl font-bold text-center text-amber-900">
            Limited Time Offer!
          </Heading>

          <div className="flex justify-center my-4">
            <div className="relative">
              <div className="text-5xl font-bold text-rose-600">10%</div>
              <div className="text-lg font-semibold text-amber-900 mt-1">OFF YOUR FIRST ORDER</div>
              <div className="absolute top-1/2 left-1/2 transform -translate-x-1/2 -translate-y-1/2 text-8xl text-amber-200 opacity-20 font-bold -z-10">
                %
              </div>
            </div>
          </div>
        </div>
      </div>

      <Modal.Body>
        <div className="flex flex-col items-center gap-y-6 py-6 px-6 bg-white">
          <Text className="text-center text-gray-700">
            Sign up now to receive an exclusive 10% discount on your first purchase. Join our community of satisfied customers!
          </Text>

          <div className="flex flex-col gap-y-4 w-full">
            <LocalizedClientLink href="/account" className="w-full">
              <Button 
                variant="primary"
                className="w-full h-12 font-semibold text-base shadow-md hover:shadow-lg transition-all"
                onClick={close}
              >
                Register & Save 10%
              </Button>
            </LocalizedClientLink>

            <Button 
              variant="secondary"
              className="w-full h-10 font-medium"
              onClick={close}
            >
              Maybe Later
            </Button>
          </div>

          <div className="text-xs text-gray-400 text-center mt-2">
            *Discount applies to your first order only
          </div>
        </div>
      </Modal.Body>
    </Modal>
  )
}

export default DiscountPopup

```

--------------------------------

### Generate Invoice Admin API Route

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/invoice-generator

This API route allows admin users to download an order's invoice. It exposes a GET endpoint at `/admin/orders/:id/invoices`.

```APIDOC
## GET /admin/orders/:id/invoices

### Description
This endpoint allows admin users to download a specific order's invoice as a PDF.

### Method
GET

### Endpoint
/admin/orders/:id/invoices

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the order for which to generate the invoice.

### Request Example
```
GET /admin/orders/order_123/invoices
```

### Response
#### Success Response (200)
- **application/pdf** - The generated invoice PDF file.

#### Response Example
(Binary PDF data)
```

--------------------------------

### Display Loyalty Points Component in Next.js Starter Storefront

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/loyalty-points

This snippet shows how to render the LoyaltyPoints component within the checkout summary of the Next.js Starter Storefront. It's a simple JSX inclusion to visualize loyalty points during checkout.

```jsx
<LoyaltyPoints cart={cart} />
```

--------------------------------

### Implement validateOptions for Twilio SMS Provider

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/phone-auth

Adds the static validateOptions method to the TwilioSmsService. This method ensures that 'accountSid', 'authToken', and 'from' are provided in the options when the module is registered. Throws an error if any required option is missing, preventing the Medusa application from starting.

```typescript
class TwilioSmsService extends AbstractNotificationProviderService {
  // ...
  static validateOptions(options: Record<any, any>): void | never {
    if (!options.accountSid) {
      throw new Error("Account SID is required")
    }
    if (!options.authToken) {
      throw new Error("Auth token is required")
    }
    if (!options.from) {
      throw new Error("From is required")
    }
  }
}
```

--------------------------------

### Create Product Media Module Service

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/category-images

Defines a service for the Product Media module by extending Medusa's `MedusaService`. This service automatically generates CRUD methods for the `ProductCategoryImage` data model, simplifying data management.

```typescript
import { MedusaService } from "@medusajs/framework/utils"
import ProductCategoryImage from "./models/product-category-image"

class ProductMediaModuleService extends MedusaService({
  ProductCategoryImage,
}) {}

export default ProductMediaModuleService
```

--------------------------------

### Register Customer

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/phone-auth

Registers a new customer using the provided registration token and customer details.

```APIDOC
## POST /store/customers

### Description
Registers a new customer. Requires a registration token in the header and customer details in the request body.

### Method
POST

### Endpoint
/store/customers

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **email** (string) - Required - The email address of the customer.
- **phone** (string) - Required - The phone number of the customer.
- **first_name** (string) - Required - The first name of the customer.
- **last_name** (string) - Required - The last name of the customer.

### Request Example
```json
{
    "email": "+19077890116@gmail.com",
    "phone": "19077890116",
    "first_name": "John",
    "last_name": "Smith"
}
```

### Headers
- **x-publishable-api-key** (string) - Required - The publishable API key.
- **Authorization** (string) - Required - Bearer token for registration.
- **Content-Type** (string) - Required - application/json

### Response
#### Success Response (200)
- **customer** (object) - Contains the details of the created customer.
  - **id** (string) - The unique identifier for the customer.
  - **email** (string) - The email address of the customer.
  - **company_name** (string | null) - The company name of the customer.
  - **first_name** (string) - The first name of the customer.
  - **last_name** (string) - The last name of the customer.
  - **phone** (string) - The phone number of the customer.
  - **metadata** (object | null) - Custom metadata for the customer.
  - **has_account** (boolean) - Indicates if the customer has an account.
  - **deleted_at** (string | null) - The timestamp when the customer was deleted.
  - **created_at** (string) - The timestamp when the customer was created.
  - **updated_at** (string) - The timestamp when the customer was last updated.
  - **addresses** (array) - An array of customer addresses.

#### Response Example
```json
{
  "customer": {
    "id": "cus_01JVPESW5SM1MSVPNM2MSC0ZEC",
    "email": "+19077890116@gmail.com",
    "company_name": null,
    "first_name": "John",
    "last_name": "Smith",
    "phone": "19077890116",
    "metadata": null,
    "has_account": true,
    "deleted_at": null,
    "created_at": "2025-05-20T09:01:13.273Z",
    "updated_at": "2025-05-20T09:01:13.273Z",
    "addresses": []
  }
}
```
```

--------------------------------

### Retrieve Invoice Configurations API Route (TypeScript)

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/invoice-generator

Implements a GET API route at `/admin/invoice-config` to retrieve default invoice configurations. It uses the Medusa Query module to fetch data from the `invoice_config` entity and returns the configuration in the JSON response.

```typescript
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const query = req.scope.resolve("query")

  const { data: [invoiceConfig] } = await query.graph({
    entity: "invoice_config",
    fields: ["*"],
  })

  res.json({
    invoice_config: invoiceConfig,
  })
}
```

--------------------------------

### Retrieve Registration Token for Phone Authentication (curl)

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/phone-auth

This `curl` command demonstrates how to request a registration token for a new customer using the phone authentication provider. It sends a POST request to the `/auth/customer/phone-auth/register` endpoint with the customer's phone number in the request body. The response includes a token necessary for subsequent registration steps.

```bash
curl -X POST 'http://localhost:9000/auth/customer/phone-auth/register' \
--header 'Content-Type: application/json' \
--data '{ \
    "phone": "+19077890116" \
}'
```

--------------------------------

### List Category Images API Route (TypeScript)

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/category-images

This snippet defines a GET API route to retrieve images associated with a specific product category. It's added to the existing `route.ts` file and uses Medusa's Query module to fetch data based on the `category_id` from the URL parameters.

```typescript
export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
): Promise<void> {
  const { category_id } = req.params
  const query = req.scope.resolve("query")

  const { data: categoryImages } = await query.graph({
    entity: "product_category_image",
    fields: ["*"],
    filters: {
      category_id,
    },
  })

  res.status(200).json({ category_images: categoryImages })
```

--------------------------------

### Fetch Loyalty Points from API (TypeScript)

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/loyalty-points

This function retrieves the authenticated customer's loyalty points by making a GET request to a specific API endpoint. It includes authentication headers and handles potential errors by returning null if the customer is not authenticated or the request fails. Dependencies include `sdk.client.fetch` and `getAuthHeaders`.

```typescript
export const getLoyaltyPoints = async () => {
  const headers = {
    ...(await getAuthHeaders()),
  }

  return sdk.client.fetch<{ points: number }>
    (`/store/customers/me/loyalty-points`,
    {
      method: "GET",
      headers,
    }
  )
    .then(({ points }) => points)
    .catch(() => null)
}
```

--------------------------------

### Register Customer with Phone Number (TypeScript)

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/phone-auth

This function registers a new customer using their phone number, first name, and last name. It obtains a registration token, sets it, creates the customer record, and then authenticates the customer. It returns the result of the authentication attempt or an error string.

```typescript
export const registerWithPhone = async ({
  firstName,
  lastName,
  phone,
}: { // Destructure firstName, lastName, and phone from the input object
  firstName: string
  lastName: string
  phone: string
}) => {
  try {
    const { token: regToken } = await sdk.client.fetch< // Fetch registration token
      { token: string }
    >(`/auth/customer/phone-auth/register`, { // API route for registration
      method: "POST",
      body: {
        phone,
      },
    })

    await setAuthToken(regToken as string) // Set the registration token
    const headers = {
      ...(await getAuthHeaders()), // Get authentication headers
    }

    const email = `${phone}@gmail.com` // Construct email from phone number
    const customerData = {
      email,
      first_name: firstName,
      last_name: lastName,
      phone,
    }

    await sdk.store.customer.create(
      customerData,
      {},
      headers
    )

    return await authenticateWithPhone(phone) // Authenticate the newly registered customer
  } catch (error: any) {
    return error.toString()
  }
}
```

--------------------------------

### Create Admin Widget for Invoice Download (React)

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/invoice-generator

This code snippet demonstrates the initial setup for an admin widget in Medusa.js using React. It defines the basic structure of a widget component and its configuration for injection into the admin panel. The widget is intended to be placed on the order details page.

```tsx
import { defineWidgetConfig } from "@medusajs/admin-sdk"
import { Button, Container, Heading, Text, toast } from "@medusajs/ui"
import { AdminOrder, DetailWidgetProps } from "@medusajs/framework/types"
import { sdk } from "../lib/sdk"
import { useState } from "react"

const OrderInvoiceWidget = ({ data: order }: DetailWidgetProps<AdminOrder>) => {
  // TODO implement widget
}

export const config = defineWidgetConfig({
  zone: "order.details.side.before",
})

export default OrderInvoiceWidget

```
Tokens:
Raw