Customer Group API

The Customer Group API enables optical stores to organize customers into groups, manage group memberships, and associate default price lists with customer groups.

All Customer Group API endpoints require authentication. Routes that operate in a store context also require a valid x-store-id header.

Overview

Customer groups can be:

Created with a name, description, and default price list
Listed with pagination, filtering, and sorting
Retrieved by ID for individual group details
Deleted in bulk operations
Used to assign customers to groups for pricing and organization
Associated with default price lists for automatic pricing

Endpoint Details

Base URL: https://joptic.jethings.com
Content-Type: application/json

Required Headers

x-store-id: <store_id>
Authorization: Bearer <token>

Endpoints that require x-store-id enforce store-level access control. Ensure the requesting user has an active relation with the store.

Authentication

All endpoints require user authentication. The user ID is extracted from the JWT token (req.user.sub), and store access is validated via the @StoreId() decorator.

Rate Limiting

Endpoints are protected with rate limiting:

GET endpoints: 60 requests per minute (long throttle)
POST endpoints: 10 requests per minute (medium throttle)
DELETE endpoints: 3 requests per minute (short throttle)

Create Customer Group

POST /customer-group Create a new customer group with an optional description and default price list association. Requires Authentication: Bearer token in Authorization header
Requires Header: x-store-id Rate Limited: 10 requests per minute

Required Headers

Key	Value	Required	Description
`x-store-id`	`string`	Yes	Store identifier (used by `@StoreId()` decorator)

Request Body

Field	Type	Required	Description
`name`	`string`	✅ Yes	Customer group name (max 255 characters)
`defaultPriceListId`	`string`	✅ Yes	ID of the default price list for this group
`description`	`string`	No	Optional description of the customer group

Request Body Example

{
  "name": "VIP Customers",
  "defaultPriceListId": "price_list_123",
  "description": "Premium customers with special pricing"
}

Success Response

Status Code: 201 Created

{
  "id": "cgrp_abc123",
  "groupName": "VIP Customers",
  "description": "Premium customers with special pricing",
  "defaultPriceList": "price_list_123",
  "createdAt": "2025-11-03T10:00:00.000Z",
  "updatedAt": "2025-11-03T10:00:00.000Z"
}

Response Fields

Field	Type	Description
`id`	`string`	Unique customer group ID
`groupName`	`string`	Customer group name
`description`	`string`	Description of the group
`defaultPriceList`	`string`	Default price list ID
`createdAt`	`string`	Creation timestamp (ISO 8601)
`updatedAt`	`string`	Last update timestamp (ISO 8601)

Possible Errors

Code	Message
400	Bad Request - Invalid input data
401	Unauthorized
403	Forbidden - User does not have access to the store
500	Internal Server Error

Example Requests

curl -X POST "https://joptic.jethings.com/customer-group" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Customers",
    "defaultPriceListId": "price_list_123",
    "description": "Premium customers with special pricing"
  }'

const groupData = {
  name: "VIP Customers",
  defaultPriceListId: "price_list_123",
  description: "Premium customers with special pricing"
}

const response = await fetch("https://joptic.jethings.com/customer-group", {
  method: "POST",
  headers: {
    "x-store-id": "your-store-id",
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(groupData),
})

const result = await response.json()

import requests

url = "https://joptic.jethings.com/customer-group"

group_data = {
    "name": "VIP Customers",
    "defaultPriceListId": "price_list_123",
    "description": "Premium customers with special pricing"
}

response = requests.post(
    url,
    headers={
        "x-store-id": "your-store-id",
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json"
    },
    json=group_data
)

print(response.json())

The customer group is created without store association in the current implementation. The default price list ID should reference an existing price list in your system.

Get All Customer Groups

GET /customer-group Retrieve a paginated list of customer groups with optional filters and search capabilities. Requires Authentication: Bearer token in Authorization header
Requires Header: x-store-id Rate Limited: 60 requests per minute

Required Headers

Key	Value	Required	Description
`x-store-id`	`string`	Yes	Store identifier (used by `@StoreId()` decorator)

Query Parameters

Parameter	Type	Required	Description	Default
`search`	`string`	No	Partial match for group name or description	—
`name`	`string`	No	Partial match for group name	—
`isActive`	`boolean`	No	Filter by active status (currently not implemented)	—
`page`	`number`	No	Page number (1-based)	`1`
`limit`	`number`	No	Items per page (1–100)	`10`
`sortBy`	`string`	No	Sort field (`name`, `createdAt`, `updatedAt`)	`createdAt`
`sortOrder`	`string`	No	Sort direction (`asc` or `desc`)	`desc`

Success Response

Status Code: 200 OK

{
  "data": [
    {
      "id": "cgrp_abc123",
      "name": "VIP Customers",
      "description": "Premium customers with special pricing",
      "createdAt": "2025-10-01T09:00:00.000Z",
      "updatedAt": "2025-10-15T12:30:00.000Z"
    },
    {
      "id": "cgrp_def456",
      "name": "Regular Customers",
      "description": "Standard customer group",
      "createdAt": "2025-09-15T08:00:00.000Z",
      "updatedAt": "2025-09-20T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 4,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Response Fields

CustomerGroup Object

Field	Type	Description
`id`	`string`	Unique customer group ID
`name`	`string`	Group name
`description`	`string`	Description of the group
`createdAt`	`string`	Creation timestamp (ISO 8601)
`updatedAt`	`string`	Last update timestamp (ISO 8601)

Pagination Object

Field	Type	Description
`page`	`number`	Current page number
`limit`	`number`	Number of items per page
`total`	`number`	Total number of records
`totalPages`	`number`	Total pages available
`hasNext`	`boolean`	Whether a next page exists
`hasPrev`	`boolean`	Whether a previous page exists

Possible Errors

Code	Message
401	Unauthorized
403	Forbidden - User does not have access to the store
500	Internal Server Error

Example Requests

curl -X GET "https://joptic.jethings.com/customer-group?page=1&limit=10" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

const params = new URLSearchParams({
  page: "1",
  limit: "10",
  sortBy: "name",
  sortOrder: "asc"
})

const response = await fetch(`https://joptic.jethings.com/customer-group?${params}`, {
  method: "GET",
  headers: {
    "x-store-id": "your-store-id",
    Authorization: "Bearer <token>",
  },
})

const result = await response.json()

import requests

url = "https://joptic.jethings.com/customer-group"

params = {
    "page": 1,
    "limit": 10,
    "sortBy": "name",
    "sortOrder": "asc"
}

response = requests.get(
    url,
    headers={
        "x-store-id": "your-store-id",
        "Authorization": "Bearer <token>"
    },
    params=params
)

print(response.json())

Search by name or description:

curl -X GET "https://joptic.jethings.com/customer-group?search=VIP" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

The search parameter performs a case-insensitive search across both group name and description fields. Results are paginated for performance. Default sorting is by creation date (newest first).

Get Customer Group by ID

GET /customer-group/:id Retrieve a single customer group by its ID. Requires Authentication: Bearer token in Authorization header Rate Limited: 60 requests per minute

Path Parameters

Parameter	Type	Required	Description
`id`	`string`	✅ Yes	The customer group ID

Success Response

Status Code: 200 OK

{
  "id": "cgrp_abc123",
  "name": "VIP Customers",
  "description": "Premium customers with special pricing",
  "createdAt": "2025-10-01T09:00:00.000Z",
  "updatedAt": "2025-10-15T12:30:00.000Z"
}

Response Fields

Field	Type	Description
`id`	`string`	Unique customer group ID
`name`	`string`	Group name
`description`	`string`	Description of the group
`createdAt`	`string`	Creation timestamp (ISO 8601)
`updatedAt`	`string`	Last update timestamp (ISO 8601)

Possible Errors

Code	Message
401	Unauthorized
404	Not Found - Customer group not found
500	Internal Server Error

Example Requests

curl -X GET "https://joptic.jethings.com/customer-group/cgrp_abc123" \
  -H "Authorization: Bearer <token>"

const response = await fetch("https://joptic.jethings.com/customer-group/cgrp_abc123", {
  method: "GET",
  headers: {
    Authorization: "Bearer <token>",
  },
})

const result = await response.json()

import requests

url = "https://joptic.jethings.com/customer-group/cgrp_abc123"

response = requests.get(
    url,
    headers={
        "Authorization": "Bearer <token>"
    }
)

print(response.json())

This endpoint does not require the x-store-id header. It retrieves the customer group by ID regardless of store association.

Delete Customer Groups (Bulk)

DELETE /customer-group Delete one or more customer groups by their IDs. This is a bulk delete operation that allows removing multiple groups in a single request. Requires Authentication: Bearer token in Authorization header Rate Limited: 3 requests per minute

Request Body

Field	Type	Required	Description
`ids`	`array<string>`	✅ Yes	Array of customer group IDs to delete

Request Body Example

{
  "ids": [
    "cgrp_abc123",
    "cgrp_def456",
    "cgrp_ghi789"
  ]
}

Success Response

Status Code: 200 OK

{
  "message": "Deleted 3 customer group(s)",
  "deletedCount": 3
}

Response Fields

Field	Type	Description
`message`	`string`	Success message with count
`deletedCount`	`number`	Number of customer groups deleted

Possible Errors

Code	Message
400	Bad Request - No IDs provided or empty array
401	Unauthorized
404	Not Found - No matching customer groups found
500	Internal Server Error

Example Requests

curl -X DELETE "https://joptic.jethings.com/customer-group" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["cgrp_abc123", "cgrp_def456"]
  }'

const deleteData = {
  ids: ["cgrp_abc123", "cgrp_def456"]
}

const response = await fetch("https://joptic.jethings.com/customer-group", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(deleteData),
})

const result = await response.json()

import requests

url = "https://joptic.jethings.com/customer-group"

delete_data = {
    "ids": ["cgrp_abc123", "cgrp_def456"]
}

response = requests.delete(
    url,
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json"
    },
    json=delete_data
)

print(response.json())

This is a bulk delete operation. Only valid customer group IDs are deleted (invalid IDs are ignored). Returns the count of successfully deleted groups. This operation is permanent and cannot be undone. Rate limited to 3 requests per minute for safety.

Assign Customer to Group

POST /customer-group/assign-group Assign a customer to a customer group. This creates a relationship between a customer and a customer group. Requires Authentication: Bearer token in Authorization header Rate Limited: 10 requests per minute

Request Body

Field	Type	Required	Description
`customerId`	`string`	✅ Yes	ID of the customer to assign
`CustomerGroupId`	`string`	✅ Yes	ID of the customer group

Request Body Example

{
  "customerId": "customer_123",
  "CustomerGroupId": "cgrp_abc123"
}

Success Response

Status Code: 200 OK

{
  "id": "relation_xyz789",
  "customerGroupId": "cgrp_abc123",
  "customerId": "customer_123",
  "createdAt": "2025-11-03T10:00:00.000Z"
}

Response Fields

Field	Type	Description
`id`	`string`	Unique relation ID
`customerGroupId`	`string`	Customer group ID
`customerId`	`string`	Customer ID
`createdAt`	`string`	Creation timestamp (ISO 8601)

Possible Errors

Code	Message
400	Bad Request - Invalid input data or missing required fields
401	Unauthorized
404	Not Found - Customer or customer group not found
500	Internal Server Error

Example Requests

curl -X POST "https://joptic.jethings.com/customer-group/assign-group" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_123",
    "CustomerGroupId": "cgrp_abc123"
  }'

const assignData = {
  customerId: "customer_123",
  CustomerGroupId: "cgrp_abc123"
}

const response = await fetch("https://joptic.jethings.com/customer-group/assign-group", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(assignData),
})

const result = await response.json()

import requests

url = "https://joptic.jethings.com/customer-group/assign-group"

assign_data = {
    "customerId": "customer_123",
    "CustomerGroupId": "cgrp_abc123"
}

response = requests.post(
    url,
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json"
    },
    json=assign_data
)

print(response.json())

If a customer is already assigned to the group, the operation may fail or create a duplicate relation depending on your database constraints. Ensure the customer and customer group IDs exist before assignment.

Business Logic

Customer Group Management

Default Price List Association

Default Price List AssociationCustomer groups can have default price lists:

When creating a group, you must specify a defaultPriceListId
This price list can be used for automatic pricing when processing orders for customers in the group
The price list ID must reference an existing price list in your system
Default price lists help streamline pricing for groups of customers

Store Access Control

Store Access ControlCustomer group operations are protected:

Users must have an active relation with the store (via userStoreRelation)
The x-store-id header is required for store-scoped operations
If a user doesn’t have access to the store, a 403 Forbidden error is returned
This ensures users can only manage customer groups for stores they have access to

Search Functionality

Search FunctionalityThe search parameter is flexible:

Searches across both group name and description fields
Uses case-insensitive partial matching (LIKE queries)
The name parameter is an alias for searching by name specifically
Search results are combined and paginated

Sorting Options

Sorting OptionsCustomer groups can be sorted by:

name - Sort alphabetically by group name
createdAt - Sort by creation date (default)
updatedAt - Sort by last update date
Sort order can be asc (ascending) or desc (descending, default)

Customer Assignment

Customer AssignmentAssigning customers to groups:

Creates a relation between a customer and a customer group
A customer can be assigned to multiple groups (if your schema allows)
The assignment creates a record in the customerGroupRelation table
This relation can be used for filtering, pricing, and reporting

Customer Group States

Active Group

Active
Group is available for customer assignment

With Default Price List

Price List Associated
Group has a default price list for automatic pricing

Searchable

Searchable
Groups can be found by name or description

Sortable

Sortable
Groups can be sorted by name, createdAt, or updatedAt

Error Responses

All endpoints may return standard HTTP error codes:

400 Bad Request - Invalid request parameters or body
401 Unauthorized - Missing or invalid authentication token
403 Forbidden - User does not have access to the store
404 Not Found - Resource not found (customer, customer group, etc.)
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Error Response Format

{
  "statusCode": 403,
  "message": "You do not have access to this store",
  "error": "Forbidden"
}

Common Error Scenarios

403 Forbidden - Store Access

{
  "statusCode": 403,
  "message": "You do not have access to this store"
}

Occurs when the user doesn’t have an active relation with the store specified in the x-store-id header. 400 Bad Request - Validation Error

{
  "statusCode": 400,
  "message": ["name must be a string", "defaultPriceListId must be a string"],
  "error": "Bad Request"
}

Occurs when required fields are missing or data types are incorrect. 404 Not Found - Customer or Group

{
  "statusCode": 404,
  "message": "Customer not found"
}

Occurs when trying to assign a customer that doesn’t exist or reference a non-existent customer group.

Usage Examples

Example 1: Create a customer group

curl -X POST "https://joptic.jethings.com/customer-group" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Members",
    "defaultPriceListId": "price_list_123",
    "description": "Customers with premium membership benefits"
  }'

Example 2: Get all customer groups with pagination

curl -X GET "https://joptic.jethings.com/customer-group?page=1&limit=20&sortBy=name&sortOrder=asc" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Example 3: Search customer groups

curl -X GET "https://joptic.jethings.com/customer-group?search=VIP&page=1&limit=10" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Example 4: Get customer group by ID

curl -X GET "https://joptic.jethings.com/customer-group/cgrp_abc123" \
  -H "Authorization: Bearer <token>"

Example 5: Delete multiple customer groups

curl -X DELETE "https://joptic.jethings.com/customer-group" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["cgrp_abc123", "cgrp_def456"]
  }'

Example 6: Assign customer to group

curl -X POST "https://joptic.jethings.com/customer-group/assign-group" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_123",
    "CustomerGroupId": "cgrp_abc123"
  }'

Best Practices

Group Organization

Use descriptive group names that indicate the customer category or tier
Organize customers by membership level, purchase behavior, or business relationship
Use descriptions to provide additional context about the group’s purpose
Keep group names consistent and meaningful

Default Price Lists

Associate appropriate price lists with customer groups for automatic pricing
Ensure the price list ID exists before creating a group
Update price list associations when business needs change
Use price lists to differentiate pricing for different customer segments

Customer Assignment

Assign customers to groups during customer creation for better organization
Use groups to apply consistent pricing across customer segments
Monitor group membership for reporting and analytics
Reassign customers to groups when their status changes

Pagination

Use pagination when fetching large lists of groups
Default limit of 10 is suitable for most use cases
Maximum limit of 100 should be used sparingly
Always check hasNext and hasPrev for navigation

Search and Filtering

Use the search parameter for quick lookups by name or description
Combine search with pagination for efficient data retrieval
Use the name parameter for more specific name-based filtering
Leverage sorting options to organize results by relevance

Rate Limiting

GET endpoints: 60 requests per minute
POST endpoints: 10 requests per minute
DELETE endpoints: 3 requests per minute
Implement retry logic with exponential backoff for rate limit errors
Batch operations when possible to reduce API calls

Error Handling

Always check for 403 errors when accessing store-scoped endpoints
Validate customer and group IDs before assignment
Handle 400 validation errors by checking request body structure
Implement proper error handling for network and server errors

Customer groups work in conjunction with other customer and pricing management endpoints:

Customer API (/customer) - Manage customers that can be assigned to groups
Price List API (/price-lists) - Manage price lists that can be associated with groups

Customer groups help organize customers by category, making it easier to manage pricing, apply discounts, and segment customers for marketing and reporting purposes. Groups can be associated with default price lists for automatic pricing.

Summary

Endpoint	Method	Description
`/customer-group`	`POST`	Create a new customer group (rate: 10/min)
`/customer-group`	`GET`	Paginated list of customer groups (rate: 60/min)
`/customer-group/:id`	`GET`	Get a customer group by ID (rate: 60/min)
`/customer-group`	`DELETE`	Delete multiple customer groups (rate: 3/min)
`/customer-group/assign-group`	`POST`	Assign a customer to a group (rate: 10/min)

Customer API

Create and manage optical customers

Price List API

Manage price lists for customer groups

​Customer Group API

​Overview

​Endpoint Details

​Required Headers

​Authentication

​Rate Limiting

​Create Customer Group

​Required Headers

​Request Body

​Request Body Example

​Success Response

​Response Fields

​Possible Errors

​Example Requests

​Get All Customer Groups

​Required Headers

​Query Parameters

​Success Response

​Response Fields

​CustomerGroup Object

​Pagination Object

​Possible Errors

​Example Requests

​Get Customer Group by ID

​Path Parameters

​Success Response

​Response Fields

​Possible Errors

​Example Requests

​Delete Customer Groups (Bulk)

​Request Body

​Request Body Example

​Success Response

​Response Fields

​Possible Errors

​Example Requests

​Assign Customer to Group

​Request Body

​Request Body Example

​Success Response

​Response Fields

​Possible Errors

​Example Requests

​Business Logic

​Customer Group Management

​Customer Group States

Active Group

With Default Price List

Searchable

Sortable

​Error Responses

​Error Response Format

​Common Error Scenarios

​Usage Examples

​Example 1: Create a customer group

​Example 2: Get all customer groups with pagination

​Example 3: Search customer groups

​Example 4: Get customer group by ID

​Example 5: Delete multiple customer groups

​Example 6: Assign customer to group

​Best Practices

​Related Endpoints

​Summary

Customer API

Price List API

Customer Group API

Overview

Endpoint Details

Required Headers

Authentication

Rate Limiting

Create Customer Group

Required Headers

Request Body

Request Body Example

Success Response

Response Fields

Possible Errors

Example Requests

Get All Customer Groups

Required Headers

Query Parameters

Success Response

Response Fields

CustomerGroup Object

Pagination Object

Possible Errors

Example Requests

Get Customer Group by ID

Path Parameters

Success Response

Response Fields

Possible Errors

Example Requests

Delete Customer Groups (Bulk)

Request Body

Request Body Example

Success Response

Response Fields

Possible Errors

Example Requests

Assign Customer to Group

Request Body

Request Body Example

Success Response

Response Fields

Possible Errors

Example Requests

Business Logic

Customer Group Management

Customer Group States

Error Responses

Error Response Format

Common Error Scenarios

Usage Examples

Example 1: Create a customer group

Example 2: Get all customer groups with pagination

Example 3: Search customer groups

Example 4: Get customer group by ID

Example 5: Delete multiple customer groups

Example 6: Assign customer to group

Best Practices

Related Endpoints

Summary