Customer groups and pricing

Learn when customer-group work belongs to customer-group records, customer-group variant prices, customer-facing reads, organisations, users, variants, or events.

Start here when you need a buyer, organisation, or market to see pricing or access that differs from the default catalog price.

The short model

A customer group is the named access bucket. It has a slug, belongs to a store group, and can carry discount fields.

A group price is the override for one product variant in one market.

A customer-facing read tells an authenticated account flow which groups and overrides apply to a user or organisation.

Choose the surface that matches the caller:

Use Management Customer Groups operations when trusted back-office code creates, updates, lists, reads, or deletes groups.
Use Management price operations when a variant needs a group-specific override.
Use Auth Customer Groups operations when the caller needs account-scoped access or price reads.
Use Variants when the base variant price changes outside group-specific pricing.
Use Organisations or Users when the relationship to the buyer account is the thing being changed.
Use Events when another system needs to react after customer-group records or customer-group variant prices change.

Choose the right surface

Customer-group work is split across two reference hubs because administrative writes and account reads use different credentials and runtime placement.

Job	Use	Why
Create a customer group	Create a customer group	Management API owns trusted customer-group administration.
Inspect customer groups for administration	List all customer groups with pagination or Get a customer group	Use these before changing group details or group prices.
Update or remove a customer group	Update a customer group or Delete a customer group	These operations change the customer-group record itself.
Add or replace customer-group variant prices	Bulk upsert customer group product variant prices	Use this when prices differ for a customer group and market context.
Inspect customer-group variant prices	List customer group product variant prices or Get a customer group product variant price	These routes read the customer-group-specific price records.
Remove customer-group variant prices	Bulk delete customer group product variant prices	Use this when the override should stop applying.
Let an authenticated flow read a customer group by slug	Get customer group by slug	Auth API owns customer/account-context reads.
Let an authenticated flow read applicable group prices	Get customer groups with paginated prices for a user or organisation	This Auth API route resolves direct and organisation-derived access in store-group and market context.

For exact methods, paths, request bodies, response fields, enum values, and status codes, use Management Customer Groups reference and Customer Groups reference.

Contract facts to keep in mind

Use these facts to choose the right reference. Use operation pages for exact fields, auth, limits, status codes, and response shapes.

Auth Customer Groups routes are account-context reads. They require the app service token in api-key and the signed-in customer's access token in Authorization: Bearer.
Management customer-group records include the group name, slug, type, store-group link, and optional discount percentage fields.
When a discount percentage is present, its decimal scale is required too.
Management list supports search by name, exact type filtering, store_group_id filtering, and sorting by created_at, updated_at, or name.
Customer-group detail includes attached merchant-user and organisation summaries with separate totals.
Group price records are specific to one customer group, one market, and one product variant. Management bulk upsert uses integer price_amount in minor units and returns separate successful and failed collections.
The customer-facing price read requires exactly one of user_id or organisation_id, is scoped by store group and market, and caps per_page at 100.
The Auth read model exposes price_amount as a decimal number. Its pagination totals count matching price rows, not accessible customer-group records.
User-context reads include direct merchant-user customer groups plus groups attached to the user's organisations and their parent organisations. Organisation-context reads include the organisation and its parent organisations.

Pricing boundaries

Group prices do not replace the base variant price model.

Use Variants when the default purchasable variant price changes for a store group or market.
Use Customer Groups when the price differs because the buyer belongs to a customer group.
Use Store Groups and Markets when the selling or regional context itself changes.
Use Organisations or Users when account membership, hierarchy, or buyer identity changes.

Events

Use Events after customer-group data changes. The Event catalog exposes customer-group upsert/delete events and customer-group product variant price upsert events.

Use the Event catalog for exact event type strings, schema IDs, required fields, and payload fields. Use Events latest for delivery and retry behavior.

Where to go next

Need trusted customer-group administration? Use Management Customer Groups reference.
Need customer-facing customer-group reads? Use Customer Groups reference.
Need default variant pricing? Use Variants reference.
Need selling context? Read Store groups and markets.
Need account and organisation context? Read Auth API latest.