Enable the loyalty area

This guide explains how to enable the customer loyalty area, which displays the loyalty program a customer is enrolled in, their points balance and their latest movements.

Overview

The loyalty area is a read-only page available to logged-in customers under /user/loyalty, listed in the account navigation as Your loyalty area. It displays, for the loyalty program the customer is enrolled in:

• the program name, card number and subscription date;
• the points balance, the next expiration date and the minimum balance required to spend points;
• the rules used to earn points;
• the 10 most recent movements (points earned and spent).

Points cannot be spent from this page, nor from the cart page: they are redeemed at the payment step of the checkout.

On the cart page, the same flag adds a loyalty block next to the store credit one, showing the balance, the conversion rule, the minimum balance required to spend points and the points the order would earn. That block is informative only.

Points are spent at the payment step of the checkout, above the payment methods: LMB records them as a payment on the cart (not as a discount), so "pay with my points" belongs where the customer chooses how to pay. It covers part of the amount due, and the remainder is paid with the selected method.

Enable the feature

The loyalty area follows your Gezy instance: it is enabled when the FID_gestion_fidelite flag of /v2/ecommerce/config is on (Configuration > Site e-commerce > Gestion de la fidélité). There is nothing to set in your .env.

That flag grants the loyalty permission, which gates both the /user/loyalty route (404 when disabled) and the Customer.loyaltyAccount GraphQL field.

What customers see

A customer enrolled in no loyalty program still sees the page, with an empty state instead of the program details.

Querying the loyalty account

query {
  me {
    loyaltyAccount {
      programName
      pointsBalance
      pointsLabel
      history {
        date
        earnedPoints
        spentPoints
      }
    }
  }
}

loyaltyAccount is null when the customer is enrolled in no program.

The cart exposes the same program through Cart.loyaltyBalance, and payCartWithLoyaltyPoints / cancelCartLoyaltyPointsPayment apply and cancel a points payment.

Spending points is all or nothing: the customer does not pick an amount, and the storefront submits the whole balance. LMB decides how much of it the cart can actually take — it excludes the shipping fees and rounds down to the conversion step — then answers a success carrying the settled amount. A balance larger than the cart is not an error, it is simply capped.

availableDiscount and usableSteps describe the account balance, not that capacity: /fidelite/panier/solde is keyed by contact and knows nothing of the cart, so the amount to spend cannot be computed upfront. For that reason the default theme displays neither of them; they are exposed for integrators who want to render the balance in their own terms.

caution

Applying points creates a payment (ReglementTypePointsFideliteEntrant) on the cart document. The cart payload reports the settled amount as montant_remise_points, which Cart.loyaltyBalance.appliedDiscount exposes and which is subtracted from the cart total, so what remains to be paid is what the storefront displays.

That field is only added when the loyalty module is enabled in the LMB configuration, which gezy.loyalty therefore requires.