Help us improve
Share bugs, ideas, or general feedback.
From medusa-commerce
Manages Medusa v2 customers: profiles, addresses, groups; email/password and social OAuth auth flows, account endpoints. Use for customer CRUD/auth tasks.
npx claudepluginhub orcaqubits/agentic-commerce-skills-plugins --plugin medusa-commerceHow this skill is triggered — by the user, by Claude, or both
Slash command
/medusa-commerce:medusa-customersThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Fetch live docs**:
Manages BigCommerce customers via REST API: CRUD for customers/addresses/attributes, groups, SSO login, form fields, settings, and segmentation for data integrations.
Manages Shopify customers via GraphQL Admin API mutations/queries for create/update/delete/tags/metafields, Customer Account API, Multipass SSO, segmentation, B2B accounts.
Manage Medusa v2 catalog—products, variants, options, collections, categories, tags, and product metadata. Useful when working with Medusa product data.
Share bugs, ideas, or general feedback.
Fetch live docs:
site:docs.medusajs.com customer module for customer data model and service methodssite:docs.medusajs.com auth module for authentication providers and flowssite:docs.medusajs.com customer group for group management and pricing ruleshttps://docs.medusajs.com/resources/references/customer and review the ICustomerModuleService interfacemedusajs v2 auth provider social login 2026 for latest authentication patterns| Entity | Relationship | Key Fields |
|---|---|---|
| Customer | Root | email, first_name, last_name, phone, has_account, metadata |
| Addresses[] | Customer → many | address fields, country_code, is_default_shipping/billing |
| CustomerGroups[] | Customer ↔ many | Many-to-many group membership |
| Orders[] | Customer → many (link) | Via Order Module link |
| Field | Type | Description |
|---|---|---|
email | string | Unique identifier for the customer |
has_account | boolean | true for registered, false for guest |
first_name / last_name | string | Customer name |
phone | string | Phone number |
metadata | JSONB | Custom key-value data |
Medusa v2 separates customer identity from authentication via the Auth Module:
Auth Module
├── AuthIdentity
│ ├── provider_identities[] (emailpass, google, github...)
│ └── app_metadata (linked customer_id)
└── Auth Providers (built-in + custom)
Register/Login ──> Auth Module validates ──> JWT token
──> Token includes auth_identity_id ──> Linked to customer_id
| Provider | Type | Configuration |
|---|---|---|
emailpass | Built-in | No external config needed |
google | OAuth2 | Client ID + secret |
github | OAuth2 | Client ID + secret |
| Custom | Extensible | Implement AbstractAuthModuleProvider |
| Step | Endpoint | Purpose |
|---|---|---|
| Register | /auth/customer/emailpass/register | Create auth identity |
| Login | /auth/customer/emailpass | Authenticate, get token |
| Create customer | /store/customers | Create customer profile (with token) |
| Step | Endpoint | Purpose |
|---|---|---|
| Initiate | /auth/customer/{provider} | Get redirect URL |
| Callback | /auth/customer/{provider}/callback | Exchange code for token |
| Create/Link | /store/customers | Create or link customer profile |
Fetch live docs for OAuth2 callback handling, redirect URIs, and token exchange flow.
| Field | Type | Description |
|---|---|---|
name | string | Group name (e.g., "VIP", "Wholesale") |
metadata | JSONB | Custom group data |
customers | relation | Many-to-many with customers |
| Use Case | Mechanism |
|---|---|
| Group-specific pricing | Price List rules linked to customer groups |
| Conditional promotions | Promotion rules targeting customer groups |
| Access control | Custom middleware checking group membership |
| Operation | Method |
|---|---|
| Create group | customerModuleService.createCustomerGroups() |
| Add to group | customerModuleService.addCustomerToGroup() |
| Remove from group | customerModuleService.removeCustomerFromGroup() |
| List groups | customerModuleService.listCustomerGroups() |
| Field | Required | Notes |
|---|---|---|
first_name / last_name | Yes | |
address_1 | Yes | Street address |
city | Yes | |
country_code | Yes | ISO 2-letter code |
postal_code | Conditional | Required by country |
is_default_shipping / is_default_billing | No | Default flags |
| Workflow | Purpose |
|---|---|
createCustomerAddressesWorkflow | Add new address |
updateCustomerAddressesWorkflow | Update existing address |
deleteCustomerAddressesWorkflow | Remove address |
| Route Pattern | Method | Purpose |
|---|---|---|
/store/customers | POST | Create customer profile |
/store/customers/me | GET | Retrieve authenticated customer |
/store/customers/me | POST | Update customer profile |
/store/customers/me/addresses | GET/POST | List/add addresses |
/store/customers/me/addresses/:id | POST/DELETE | Update/remove address |
All /store/customers/me routes require a valid JWT in the Authorization header.
| Route Pattern | Method | Purpose |
|---|---|---|
/admin/customers | GET/POST | List/create customers |
/admin/customers/:id | GET/POST | Retrieve/update customer |
/admin/customer-groups | GET/POST | Manage groups |
/admin/customer-groups/:id/customers | POST | Add customers to group |
Fetch live docs for request body shapes and query parameters on each route.
emailpass and at least one OAuth2 provider for user convenienceprovider_identities, not in customer metadataapp_metadata.customer_idhas_account to distinguish registered customers from guest checkoutsmetadatais_default_shipping and is_default_billing to streamline checkoutFetch the Medusa v2 customer module and auth module documentation for exact service method signatures, auth provider configuration, and JWT handling before implementing.