Skip to main content
Version: Next

Customer Groups

Added in Thelia 3.4.

A customer group is a class of customers that a shop prices, serves and restricts as one. Wholesale buyers pay 15% less and see prices without tax. A trade partner has its own price on a range and can pay by bank transfer only. Members of a closed club browse a few categories that nobody else sees.

Every customer belongs to exactly one group. A visitor who is not signed in, a console command and a guest account (checkout without an account) are all treated as members of the default group.

What a group holds​

SettingEffect
CodeA stable machine name, unique. Letters, digits, dots, dashes and underscores, starting with a letter or a digit, 64 characters at most. A deployment or an API client may refer to the group by this code.
Title, descriptionFree text, translatable.
Discount (%)Between 0 and 100. Taken off the prices the members pay.
Show prices with taxesWhether the members see prices with or without tax.
Default groupExactly one group is the default. Ticking this on another group releases the previous one.
Payment modulesThe payment methods the members may use. Empty means all of them.
CategoriesThe categories the members may browse. Empty means the whole catalog.
Registration linkA secret link that signs new customers up into the group.

The update to 3.4 creates a group with the code default and puts every existing customer in it.

Managing groups in the back office​

Open Configuration > Customer groups. The screen needs the admin.customer.group right. The update gives it to no existing profile, so only super administrators reach the screen until you grant it.

Create a group by typing its code and title, then fill in the other settings on its edit page.

The default group​

New accounts join the default group unless an administrator picks another one or the customer signs up through a registration link. The default group can be neither deleted nor stop being the default. To change the default, tick Default group on another group.

Moving a customer to another group​

On the customer's edit page, change the Customer group field. A new account created from the back office joins the default group when the field is left on Default group.

A customer cannot change their own group. An administrator restricted to a sale unit can read groups and the group of a customer, but cannot change them.

Deleting a group​

Deleting a group moves its customers to the default group. The orders already placed keep the group they were placed under: the group, its discount rate and its display mode are frozen on the order, so an invoice does not change when the group does.

Prices for a group​

A group can pay less in three ways. They combine as described in How the price is decided.

  • A discount. The percentage of the group applies to the catalog price. It never applies on top of a catalog promotional price. The customer pays the lower of the discounted catalog price and the promotional price.
  • A price of its own. On the product page of the back office, the Prices per customer group panel lists each combination. Type a price, a sale price, or both, for a group and a currency. Prices are without tax. An empty field means the group has no price of its own, and the catalog price applies. A price missing in the browsed currency is converted from the one in the default currency.
  • A price list. See Price Lists.

A catalog price rule or a reserved sale can also target customer groups.

How the price is decided​

For one combination, one currency and one customer, the core goes through these steps. Each step starts from the result of the previous one.

  1. Price list. If an active price list assigned to the customer or their group has a line for the combination and the quantity, that price is final. No group price, group discount, rule, sale or customer discount applies on top of it.
  2. Group or catalog price.
    • If a sale unit prices the combination, that price is used, less the group discount.
    • Otherwise, if the group has a price of its own, it replaces the catalog price and the catalog promotional price.
    • Otherwise the group discount applies to the catalog price. The catalog promotional price is kept as it is, and the lower of the two wins.
  3. Rules and sales. A catalog price rule or a reserved sale competes with the price from step 2. The lower price wins. When the group changes nothing for this combination (no price of its own, no discount), the rule replaces the promotional price whatever it was.
  4. Discount of the customer. The discount set on the customer record applies last, to whatever won. It multiplies with the discount of the group.

Coupons and automatic promotions are computed on the cart afterwards, from these line prices.

Nothing is rounded along the way. The price is rounded to 6 decimals when a cart line is written, and to the cent when it is displayed or added up in an order.

Example: a catalog price of 100.00, a group discount of 15% and a customer discount of 10%.

Catalog promotional priceCustomer paysWhy
None76.50100 less 15% is 85, less 10% is 76.50.
8072.00The promotional price beats 85, then the customer discount applies.
9076.50The discounted price, 85, beats 90. The line is no longer shown as a promotion.

A bundle priced by its components is priced as the sum of its components less the discount of the bundle. The group discount and the customer discount apply to that. A price the group has of its own, a price list or a rule does not reach it.

The product loops, the front API, the product page, the price facet, the quick order and the cart all read this one calculation, so a product card, its page and the cart line show the same price. The min_price and max_price orders of the product loop stay on the public catalog price.

When a group, a group price, a price list, a rule or a sale moves the price of a line after it was added to the cart, the payment prices the lines again and stops. Through the checkout API this is a 409. The same request, posted again, is placed on the new prices.

Prices with or without tax​

A group shows its members prices with tax (the default) or without. The core publishes both figures wherever a theme prints a price, so a theme does not compute anything.

  • The front API ProductPrice has taxedPrice and taxedPromoPrice. They are taxed for the delivery country of the visitor.
  • Every delivery option has postageUntaxed.
  • The cart lines of attr() have offered_discount, offered_effective_taxed, offered_effective_untaxed, line_total_taxed, line_total_untaxed, line_total_after_discount_taxed and line_total_after_discount_untaxed.
  • An order publishes its group and the figures a recap without tax needs. Each one is to the cent and they add up. See Orders.

Restricting the catalog and the payment methods​

A group can be limited to a list of categories, a list of payment modules, or both.

A group that has a list of categories sees only those categories and their subcategories. The parent categories of a listed category stay open as a way through, so the customer can reach it, but the products filed only in a parent are not shown. Every other category is closed. A product is visible when at least one of its categories is open, or when it has no category at all.

What a group cannot see is left out of the category, product and image loops, of the front API collections and items, of the listing facets and of the search. The page of a closed category answers 404. The back office and the admin API are never narrowed.

A group that has a list of payment modules can pay only with the listed ones. The other methods are left out of the payment loop and of the payment options of the API, and the order is refused if they are used anyway. The list of one group never changes what another group sees or pays with.

For example, a group pro that lists the Cheque module and the category Sofas (under Living Room) sees only Sofas and its subcategories, with Living Room shown as a way through, and pays by cheque only. The default group, which has no list, sees everything and pays with every module.

The restriction flag​

A list only counts while the group is flagged as restricted. The flag follows the list when you save the group in the back office or through the API: a non-empty list sets it and an empty list clears it.

A restricted group sees and pays with what its list holds, an empty list included. If you delete the only category or payment module a group lists, the group stays restricted with an empty list. It then sees no category (a product filed in no category stays visible) or cannot pay with any method, until an administrator edits the list. On the group page, Lift the restriction clears the flag of one list. Unticking every entry of a list does the same.

The flags are read-only in the API: restrictsCategories and restrictsPaymentModules.

Assortments add per-customer and per-brand rules on top of the category list. A product is visible when both open it.

The cart​

The cart holds only what the catalog shows its visitor.

  • Adding a product the customer's group hides is refused, whatever the path: the cart API, a live component or a module dispatching CART_ADDITEM. The error is a ProductNotAvailableException, which the front API answers with a 422.
  • When a customer signs in, or when a cart is restored from its cookie, the lines they can no longer see are removed and a notice is left in the session. The remaining lines are priced again for the customer, then the promotions are computed again.
  • A line the customer can no longer see cannot grow. Reducing it or removing it stays allowed.
  • A payment module the group does not list is refused when it is chosen (payment-invalid, 422) and again at the validation.

A group other than the default one can open a secret registration link. Whoever signs up through it joins the group instead of the default one.

On the group page:

  • Open a registration link generates the link, https://<shop>/register/<token>. Share it only with the people it is meant for. Nobody validates the accounts that sign up through it.
  • Regenerate gives a new token. The links already handed out answer 404.
  • Close removes the token.

The default group has no link: its members sign up on the standard registration page. The Flexy theme serves the standard registration form at /register/<token>. The token is read from the URL only, and the group is looked up on the server: it is never a field of the form.

Registration is limited to 5 attempts per e-mail address and 20 per client and per hour. Behind a proxy or a CDN, declare it in framework.trusted_proxies (TRUSTED_PROXIES). Without it every visitor shares the address of the proxy.

Orders​

The order freezes the group, its discount rate and whether it shows taxed prices: customer_group_id, customer_group_discount_rate and customer_group_display_taxed_price. The group id goes to NULL if the group is deleted later, and the other two values stay.

The order loop outputs CUSTOMER_GROUP_ID, CUSTOMER_GROUP_CODE, CUSTOMER_GROUP_DISCOUNT_RATE and CUSTOMER_GROUP_DISPLAY_TAXED_PRICE, with TOTAL_GOODS_AMOUNT, TOTAL_TAXED_GOODS_AMOUNT, TOTAL_AMOUNT_AFTER_DISCOUNT and TOTAL_TAXED_AMOUNT_AFTER_DISCOUNT.

The customer loop takes a customer_group argument and outputs CUSTOMER_GROUP_ID, CUSTOMER_GROUP_CODE and CUSTOMER_GROUP_TITLE. The customer export has customer_group and customer_group_title. The personal data export of a customer names their group. Anonymizing a customer puts the account back in the default group.

For developers​

The admin API​

All of these need the admin.customer.group right. An administrator restricted to a sale unit can read but gets a 403 on any write.

RouteUse
/api/admin/customer_groupsCollection, item, creation, PUT, PATCH and deletion.
/api/admin/customer_group_product_pricesThe group prices: a group, a combination, a currency, price and promoPrice.
POST /api/admin/customer_groups/{id}/registration_linkOpens the link and returns the existing token if one is open.
POST /api/admin/customer_groups/{id}/registration_link/regenerateReplaces the token.
DELETE /api/admin/customer_groups/{id}/registration_linkCloses the link.

A group has code, position, isDefault, discount, displayTaxedPrice and translated i18ns. paymentModules and categories are lists of IRIs (/api/admin/modules/{id}, /api/admin/categories/{id}). A list left out of a write keeps its links, and an empty list clears them. restrictsCategories and restrictsPaymentModules are read-only. registrationToken is readable on a single item by an unrestricted administrator and is never written with the group.

An invalid code or a discount outside 0 to 100 is refused with a 422. Deleting the default group, or setting isDefault to false on it, answers 409. The registration link routes also answer 409 for the default group.

On a group price, a POST with neither a price nor a promotional price answers 422. A PUT or a PATCH that empties both deletes the row and answers 204.

An administrator moves a customer with customerGroup on /api/admin/customers (PUT, PATCH). customerGroup.id is an exact filter of the collection.

The customer reads their own group (id, code and title) through customerGroup on /api/front/account/customers/{id} and through GET /api/front/customer_groups/{id}. The second route refuses any group other than the one of the signed-in customer. The customer can never write the group.

POST /api/front/customers takes a write-only registrationToken. A token that opens no group (unknown, closed, regenerated or malformed) answers 422 on registrationToken with one message for every case, and creates nothing.

The order API publishes customerGroupId, customerGroupCode, customerGroupDiscountRate and customerGroupDisplayTaxedPrice, with totalGoodsWithoutTaxes, totalGoodsWithTaxes, amountDiscountWithoutTaxes, totalAmountWithoutTaxesAfterDiscount, totalShippingWithoutTaxes, totalAmountWithoutTaxesWithShipping and totalTaxAmount. An order line has unitTaxedPriceBeforePromotion, taxedPromoPrice, lineTotalWithoutTaxes and lineTotalWithTaxes.

On /api/front/products, untaxed_price_order sorts on the untaxed price the visitor pays, group and price list included, in the currency browsed.

Services​

NeedUse
Read what a customer paysThelia\Domain\Pricing\CustomerPrice\CustomerPriceContextInterface::resolve() for a batch of combinations. customerGroupOf() and displaysTaxedPrices() give the group and the display. A module that builds a feed or an export prices through it and does not read customer.discount or the catalog price itself.
Know the group of a customerThelia\Domain\Customer\Service\CustomerGroupResolver::groupIdOf() and groupOf(). A signed-in customer is read back from the database once per request.
Move a customerThelia\Domain\Customer\Service\CustomerGroupAssignment::assign($customer, $customerGroupId) returns whether the group changed.
Create an account in a groupCustomerCreateOrUpdateEvent and Customer::createOrUpdate() take an optional last customerGroupId. A group the shop does not have throws UnknownCustomerGroupException before anything is written.
Write the lists of a groupThelia\Domain\Customer\Service\CustomerGroupLinks::replace(), the only writer of the category and payment module lists.
Check a payment moduleThelia\Domain\Customer\Service\CustomerGroupPaymentPolicy. The check is an explicit call, so a module that stops MODULE_PAYMENT_IS_VALID cannot skip it.
Open or close a registration linkThelia\Domain\Customer\Service\CustomerGroupRegistration (open, regenerate, close, groupForToken). CustomerFacade::register() takes an optional ?string $registrationToken.

Events​

ConstantWhen
TheliaEvents::CUSTOMER_GROUP_CHANGEDAn administrator moves a customer, through the API, the back office or CustomerGroupAssignment::assign(). The CustomerGroupChangedEvent carries the previous and the new group ids. A customer created in a group raises nothing.
TheliaEvents::CART_LINES_REPRICEDThe payment priced the lines again because a price moved. The coupon action computes the discount of the automatic promotions again.
TheliaEvents::CART_LINES_REMOVEDA cart restored from its cookie lost lines the customer cannot see. The discount and the postage are computed again.

Targeting groups from a promotion​

The coupon condition Thelia\Condition\Implementation\ForSomeCustomerGroups (service thelia.condition.for_some_customer_groups, field customer_groups, operators in and out) restricts a promotion to some groups, or excludes them.

A catalog price rule and a reserved sale take audience mode 2 (AUDIENCE_MODE_CUSTOMER_GROUPS). See Catalog Price Rules and Reserved Sales.

Constraints to know​

  • customer.customer_group_id is required and has no default in the database. A customer created through the model gets the default group. A module or an import that inserts into customer with SQL must set the column.
  • A discount rate outside 0 to 100 is refused at write: a 422 on the admin API, an InvalidCustomerDiscountException on the account events. A rate already stored outside the range counts for nothing.
  • The discount of a customer is read from the database once per request, not from the copy the session keeps since sign-in. A discount an administrator withdraws applies at once.
  • The data access cache is keyed by the group of the one asking where the answer depends on it. A customer with a discount of their own is not served from it. Writing a group, its prices, its categories or its payment modules flushes it. The shared cache (proxy) keeps the pages of anonymous visitors, who all belong to the default group.

The full technical reference, with the data model, is docs/customer-groups.md in the thelia/thelia repository.