- An employee benefit is an entitlement tied to a person, not a coupon attached to a basket.
- Medusa remains responsible for cart pricing while a dedicated module owns codes, eligibility and annual usage.
- The programme must remain visible from account activation through checkout, order, support and ERP export.
- Public promotions and employee pricing need an explicit, explainable stacking policy.
- The strongest programmes carry one clear business meaning from the storefront to support, finance and ERP.
The client needed a programme that followed the employee through the whole commerce system
The visible request sounded simple: give eligible employees 20% off their purchases. The operational requirement was much larger. A code had to belong to one customer, the benefit had to respect an annual allowance, the cart had to show the right adjustment, public campaigns needed a stacking rule, each order had to consume the correct amount and support had to explain the remaining balance.
Medusa already provided customers, carts, orders, line adjustments, promotions, workflows and Admin extension points. It did not know who this client considered an employee or how its annual benefit worked. We built a dedicated employee-programme module around those primitives while keeping Medusa as the commerce and pricing engine. That is the architecture value: extend the business domain without rebuilding checkout.
What we actually built, from the first code to the ERP order
The implemented journey crossed far more than one discount field. Operators could import and inspect employee codes. A customer could activate a code from the account area and later detach it. The backend exposed the current programme status: eligibility, percentage, annual cap, used amount, pending amount, remaining amount and reset date. The cart route projected the benefit onto individual lines and recorded why a competing promotion won or lost.
When an employee order was placed, a subscriber identified the dedicated employee adjustments and recorded order-linked usage. The order summary and transactional email could show employee discount separately from public promotions. The order export carried employee status and discount details. The Odoo workflow created a separate negative employee-discount line and marked the customer as an employee. Admin pages then gave the commerce team a view over codes, employees, balances and associated orders.
The code represented identity and eligibility
The company needed controlled codes, not a reusable campaign string. Imported values were normalised and validated before becoming available. Activation linked one available code to the authenticated customer and stored activation context. Detachment released the code for the programme’s defined reuse policy. Invalidation stopped future eligibility while retaining the relationship and timestamps needed to understand the past.
The storefront made that lifecycle visible. An employee could enter a code in the account area, see the active programme state, view the percentage and remove the code. The interface did not ask the cart to rediscover identity on every visit. It asked the programme service for the current entitlement. A small account action now carried a clear business meaning across customer identity, programme access and historical usage.
A percentage formula became an annual account
The project used a 20% benefit and a configurable annual cap, represented in euro cents. The status service grouped usage by customer and calendar year, then derived used, pending, remaining and the next reset date. That allowed the account and Admin experiences to discuss one employee’s position rather than the global budget of a promotion campaign.
The programme consumed eligible merchandise value, not merely the amount saved. A €100 eligible purchase therefore consumed €100 of allowance and produced a €20 reduction. This distinction sounds small but changes every balance, report and support answer. By naming the unit clearly, the programme gave employees, support and finance the same explanation of every euro consumed.
Medusa still priced the cart; our module supplied the employee rule
The cart endpoint retrieved the authenticated customer, current line items, existing adjustments and applied promotions. It calculated the eligible base after relevant public discounts, asked the employee module how much benefit remained, then distributed the employee adjustment across the eligible lines. Dedicated codes and provider identifiers kept that adjustment recognisable later in checkout, email, reporting and ERP export.
This separation mattered. The employee module did not become a second cart engine, and the storefront did not invent a client-side discount. Medusa remained responsible for the commercial basket. The project-specific module supplied eligibility and allowance; the cart route translated that decision into standard line adjustments. The storefront could then show the employee reduction and explain when another promotion prevented it.
Public promotions and the employee benefit could not compete by accident
A public campaign may be compatible with employee pricing or deliberately exclusive. The project added metadata and an Admin widget for that policy. When an exclusive promotion and the employee benefit competed, the cart logic compared their amounts. It kept the larger benefit; a tie remained with the public promotion. Metadata recorded whether the employee discount was blocked or whether the public offer was ignored.
That produced useful customer language instead of a mysterious total. It also prevented calculation order from becoming an unofficial commercial policy. Marketing could create campaigns, the cart could arbitrate them consistently and support could understand the result without reconstructing the order in a spreadsheet.
Placing the order created an auditable usage record
After order placement, a subscriber examined the order lines for the dedicated employee adjustment. It reconstructed the eligible purchase base after public discounts and asked the programme service to create or update a usage entry linked to the order, customer and year. Sequential replay looked for an existing order-linked entry before creating another one.
The current right and the financial history therefore lived separately. Invalidating a code changed eligibility; it did not delete the usage generated by previous orders. That is the core of the ledger: the company can change who is eligible today while keeping a stable explanation of what happened yesterday.
The programme included tools for the people who had to operate it
Medusa Admin contained dedicated employee and code surfaces rather than hiding the feature inside raw customer metadata. Operators could inspect code totals by state, search assignments, import or export code lists and invalidate a code. The customer widget assembled eligibility, annual cap, used, pending, remaining, reset information and order-linked usage for support.
This was not cosmetic administration. A programme that grants a financial benefit creates everyday questions: why is this code unavailable, why did this promotion win, why is this amount remaining and which order consumed it? The Admin surfaces were designed to answer those questions from programme data. A controlled reset used a compensating usage entry instead of deleting the historical rows that explained the previous balance.
Employee pricing remained identifiable after checkout
The programme did not stop when the confirmation page appeared. Order rendering separated the employee reduction from ordinary promotional discounts. Transactional-email totals could display the same distinction. CSV order export included whether the buyer was an employee, the employee code, whether the benefit applied and its amount.
The Odoo order workflow aggregated employee adjustments into a separate negative line labelled as an employee discount, with metadata distinguishing it from commercial promotions. Customer synchronisation could also pass the employee flag. This is the kind of detail that makes a custom commerce feature usable by finance and operations: downstream systems receive the business meaning, not an unexplained lower order total.
One feature became a complete operating capability
What began as ‘give employees 20% off’ became a coherent programme spanning code lifecycle, customer activation, annual status, cart pricing, promotion policy, order-linked usage, Admin visibility, email, export and Odoo. Each surface used the same business vocabulary instead of inventing its own interpretation of the benefit.
That is the advantage of choosing Medusa as an extensible foundation. We did not have to replace the commerce engine to introduce a client-specific business model. We added the missing domain, connected it to the existing customer, cart and order journeys, and carried its meaning all the way to the teams operating the business.
The programme checklist we would take into the next project
Start with the business promise: who is eligible, what percentage applies, what the annual cap measures, when it resets, which products count and how public promotions interact. Then trace that promise through code import, account activation, cart calculation, payment, order placement, email, support, export and ERP.
Design the programme as one customer and operating journey, not as a checkout trick. Give every balance movement an order context, make promotion choices explainable and keep the employee meaning visible downstream. The result should feel simple to the employee precisely because the platform carries the complexity for them.
Common questions
Medusa promotions remain useful for pricing, but they do not own the client-specific identity lifecycle, annual customer allowance, order ledger, support history and ERP meaning. Those responsibilities belong in a dedicated module.
Code import and lifecycle, customer activation, annual status, line-level cart adjustments, promotion arbitration, order-linked usage, Medusa Admin views, email and export breakdowns, and a separate Odoo employee-discount line.
Medusa supplied the stable customer, cart, promotion and order foundations. Souk added the organisation’s employee-programme rules as a dedicated capability and carried them through every operational surface that needed to understand them.