Customer Groups

Customer groups organize customers into segments for pricing, promotions, and targeting. Groups can be manual (explicitly add/remove members) or automatic (membership computed from conditions like total spent, order count, tags, or location).

Each group can optionally have an active_price_key that assigns a pricing tier to all members, enabling wholesale or tiered pricing.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/customer-groups	Secret	List customer groups
POST	/v1/customer-groups	Secret	Create a customer group
GET	/v1/customer-groups/{id}	Secret	Get a customer group
PATCH	/v1/customer-groups/{id}	Secret	Update a customer group
DELETE	/v1/customer-groups/{id}	Secret	Delete a customer group
POST	/v1/customer-groups/{id}/members	Secret	Add customers to a group
DELETE	/v1/customer-groups/{id}/members/{customer_id}	Secret	Remove a customer from a group

---

List customer groups

GET /v1/customer-groups

Returns a paginated list of customer groups with member counts.

Query parameters

Parameter	Type	Default	Description
limit	integer	25	Results per page (1–250)
cursor	string	-	Pagination cursor from a previous response
sort	string	created_at	Sort field: created_at, updated_at, name
order	string	desc	Sort direction: asc, desc
search	string	-	Filter by name (case-insensitive substring match, max 200 chars)
customer_id	string	-	Filter groups containing this customer
expand	string	-	Comma-separated: members
fields	string	-	Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/customer-groups?search=wholesale&limit=10 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "cg_abc123",
			"name": "Wholesale",
			"handle": "wholesale",
			"description": "B2B wholesale customers",
			"type": "manual",
			"conditions": [],
			"condition_match": "all",
			"active_price_key": "wholesale",
			"member_count": 12,
			"metadata": {},
			"created_at": "2026-06-01T10:00:00Z",
			"updated_at": "2026-06-01T10:00:00Z"
		}
	],
	"pagination": {
		"cursor": "eyJ0IjoiMjAyNi...",
		"has_more": false,
		"total": 1
	}
}

---

Create a customer group

POST /v1/customer-groups

Creates a new customer group. Returns the created group with 201.

Request body

Field	Type	Required	Description
name	string	Yes	Group name (1–255 chars)
handle	string	No	URL-friendly slug (auto-generated from name if omitted). Must match ^[a-z0-9]+(?:-[a-z0-9]+)*$
description	string	No	Group description (max 5000 chars)
type	string	No	manual (default) or automatic
conditions	object[]	No	Conditions for automatic groups (max 20). Ignored for manual groups
conditions[].field	string	Yes	Condition field (see condition fields table)
conditions[].operator	string	Yes	Comparison operator (see condition operators table)
conditions[].value	string | number	Yes	Comparison value
condition_match	string	No	all (default, AND logic) or any (OR logic)
active_price_key	string | null	No	Pricing tier slug assigned to group members (max 50 chars)
metadata	object	No	Arbitrary key-value pairs (max 50 keys)

Request

curl -X POST https://api.hydrajs.dev/v1/customer-groups \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wholesale",
    "description": "B2B wholesale customers",
    "active_price_key": "wholesale"
  }'

Response 201

{
	"data": {
		"id": "cg_abc123",
		"name": "Wholesale",
		"handle": "wholesale",
		"description": "B2B wholesale customers",
		"type": "manual",
		"conditions": [],
		"condition_match": "all",
		"active_price_key": "wholesale",
		"member_count": 0,
		"metadata": {},
		"created_at": "2026-08-17T12:00:00Z",
		"updated_at": "2026-08-17T12:00:00Z"
	}
}

---

Get a customer group

GET /v1/customer-groups/{id}

Returns a single customer group by ID. Use ?expand=members to include the member list inline.

Query parameters

Parameter	Type	Description
expand	string	Comma-separated: members
fields	string	Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/customer-groups/cg_abc123?expand=members \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": {
		"id": "cg_abc123",
		"name": "Wholesale",
		"handle": "wholesale",
		"description": "B2B wholesale customers",
		"type": "manual",
		"conditions": [],
		"condition_match": "all",
		"active_price_key": "wholesale",
		"member_count": 2,
		"metadata": {},
		"members": [
			{
				"id": "cus_abc123",
				"email": "jane@example.com",
				"first_name": "Jane",
				"last_name": "Smith"
			},
			{
				"id": "cus_def456",
				"email": "bob@example.com",
				"first_name": "Bob",
				"last_name": "Jones"
			}
		],
		"created_at": "2026-06-01T10:00:00Z",
		"updated_at": "2026-06-01T10:00:00Z"
	}
}

---

Update a customer group

PATCH /v1/customer-groups/{id}

Partially updates a customer group. Send only the fields you want to change. Returns the updated group.

Request body

All fields are optional:

Field	Type	Description
name	string	Group name (1–255 chars)
handle	string	URL-friendly slug (max 255 chars)
description	string | null	Group description (max 5000 chars). Set null to clear
conditions	object[]	Conditions for automatic groups (max 20, replaces all)
condition_match	string	all or any
active_price_key	string | null	Pricing tier slug. Set null to clear
metadata	object	Key-value pairs (merge semantics: set key to "" to remove)

Request

curl -X PATCH https://api.hydrajs.dev/v1/customer-groups/cg_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Premium wholesale partners", "active_price_key": "wholesale-premium"}'

Response 200

{
	"data": {
		"id": "cg_abc123",
		"name": "Wholesale",
		"handle": "wholesale",
		"description": "Premium wholesale partners",
		"type": "manual",
		"conditions": [],
		"condition_match": "all",
		"active_price_key": "wholesale-premium",
		"member_count": 2,
		"metadata": {},
		"created_at": "2026-06-01T10:00:00Z",
		"updated_at": "2026-08-17T14:00:00Z"
	}
}

---

Delete a customer group

DELETE /v1/customer-groups/{id}

Soft-deletes a customer group. Members are removed from the group but not deleted. The handle is freed for reuse.

Request

curl -X DELETE https://api.hydrajs.dev/v1/customer-groups/cg_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

Empty body.

---

Add customers to a group

POST /v1/customer-groups/{id}/members

Adds one or more customers to a manual group. Existing memberships are silently skipped. Returns the group with expanded members.

Request body

Field	Type	Required	Description
customer_ids	string[]	Yes	Array of customer IDs to add (1–100 per request)

Request

curl -X POST https://api.hydrajs.dev/v1/customer-groups/cg_abc123/members \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_ids": ["cus_abc123", "cus_def456"]}'

Response 200

{
	"data": {
		"id": "cg_abc123",
		"name": "Wholesale",
		"handle": "wholesale",
		"description": "B2B wholesale customers",
		"type": "manual",
		"conditions": [],
		"condition_match": "all",
		"active_price_key": "wholesale",
		"member_count": 2,
		"metadata": {},
		"members": [
			{
				"id": "cus_abc123",
				"email": "jane@example.com",
				"first_name": "Jane",
				"last_name": "Smith"
			},
			{
				"id": "cus_def456",
				"email": "bob@example.com",
				"first_name": "Bob",
				"last_name": "Jones"
			}
		],
		"created_at": "2026-06-01T10:00:00Z",
		"updated_at": "2026-08-17T14:30:00Z"
	}
}

---

Remove a customer from a group

DELETE /v1/customer-groups/{id}/members/{customer_id}

Removes a single customer from the group. The customer is not deleted.

Request

curl -X DELETE https://api.hydrajs.dev/v1/customer-groups/cg_abc123/members/cus_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

Empty body.

---

Condition fields

Automatic groups compute membership based on conditions. Each condition has a field, operator, and value.

Field	Type	Valid operators	Value format
tag	text	is_same_as, is_not	Tag string
status	text	is_same_as, is_not	active or inactive
company	text	is_same_as, is_not	Company name
city	text	is_same_as, is_not	City name
country	text	is_same_as, is_not	ISO 3166-1 alpha-2 code
total_spent	numeric	more_than, less_than	Amount in cents
order_count	numeric	more_than, less_than	Number of orders
first_order_date	date	is_before, is_after	ISO 8601 date
last_order_date	date	is_before, is_after	ISO 8601 date
customer_added_date	date	is_before, is_after	ISO 8601 date

---

The customer group object

Field	Type	Description
id	string	Unique ID (prefix: cg_)
name	string	Group name
handle	string	URL-friendly slug (unique per project)
description	string | null	Group description
type	string	manual or automatic
conditions	object[]	Conditions for automatic membership
conditions[].field	string	Condition field
conditions[].operator	string	Comparison operator
conditions[].value	string | number	Comparison value
condition_match	string	all (AND) or any (OR)
active_price_key	string | null	Pricing tier slug assigned to members
member_count	integer	Number of members in the group
metadata	object	Arbitrary key-value pairs
members	object[]	Expanded with ?expand=members
members[].id	string	Customer ID
members[].email	string	Customer email
members[].first_name	string	Customer first name
members[].last_name	string	Customer last name
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp