Promotions and Discount Codes

Promotions let the office create a code that applies a controlled percentage or flat discount to an eligible customer proposal. Open Marketing, then select Promotions.

Release status: W37 is deployed in production. Authenticated production setup, customer-code entry, and provider campaign proof still require an approved synthetic QA organization and safe recipients.

Access and permissions

Promotions are a web-office feature:

• Manage pricing is required to open the workspace and to create, edit,

activate, deactivate, or archive a promotion. Promotion terms affect the customer-facing price, so this does not borrow automation permissions.

• A teammate can work only with locations allowed by their saved membership

scope. Organization and location checks are also enforced by the service; hiding a control in the browser is not the security boundary.

The native mobile app does not add or change any promotion layout, navigation, label, or interaction in this release.

Promotions workspace

The header summarizes the currently selected office scope:

• Active promotions includes active codes and codes whose start time is

still in the future.

• Scheduled counts active codes that have not reached their start time.
• Redemptions is the number of successfully recorded promotion

redemptions. It is not a booking, payment, or revenue count.

Use Office location to view all authorized offices or one office. An all-office promotion appears when any authorized office is selected.

Each card shows the saved code and discount, location scope, validity window, customer and estimate-age rules, total and per-client usage, unique clients, total recorded discount, portal state, and service restrictions. When a total usage cap exists, the card also shows a used/max fraction and progress bar.

Statuses

Scheduled, expired, and exhausted are derived display states. The office can deactivate an enabled promotion without changing its saved terms or evidence.

Create or edit a promotion

Select New promotion and configure these fields:

The editor labels the effective time zone, and promotion cards show its zone abbreviation. A local time skipped by the spring-forward clock change is rejected; when the fall-back clock repeats a time, the earlier occurrence is used.

Leaving service restrictions empty means all services are eligible. The builder uses the organization's authoritative active service catalog instead of a hard-coded residential list.

The office may edit terms and location scope until the first redemption. After that point, the pricing and eligibility terms are locked. Deactivate or archive the promotion if it should stop; create a new promotion to offer different terms. This preserves the exact meaning of every prior redemption.

Concurrent edits use a saved version check. If another teammate changes the same promotion first, the stale save, status change, or archive request fails instead of overwriting the newer record.

Activate, deactivate, and archive

Creating a promotion saves it as Draft. Select Activate to make it eligible, subject to its dates, location, customer, age, service, portal, and usage rules. Select Deactivate to stop future redemptions without losing history.

Archive requires confirmation. Archiving does not delete the promotion or its redemption journal; it prevents future use and retains the record for audit and reporting.

Activation and redemption recheck the authoritative location scope. Usage caps are checked while the promotion is locked, so concurrent customers cannot both consume the same final available use.

Customer proposal entry

When at least one active, portal-enabled promotion is available for the proposal's office, an unsigned sent proposal can show Promotion code above Review and accept. The customer enters a code and selects Apply.

The server then rechecks the current proposal and promotion together:

1. The secure proposal link still resolves to the same current estimate.
2. The proposal is sent, unsigned, not withdrawn, not declined, and not

expired.

1. The promotion is active and enabled for customer entry.
2. The current time is inside the inclusive validity window.
3. Location, customer type, minimum estimate age, and service rules pass.
4. Total and per-client caps still have capacity.
5. Every resulting proposal option remains above its safe pricing floor.

Unknown, inactive, ineligible, exhausted, and otherwise unavailable codes use the same customer-facing unavailable result. The endpoint is rate-limited and private/no-store so it does not expose the organization's offer catalog or leave proposal data in shared caches.

One code and no stacking

An estimate can record one promotion redemption. Replaying the same successful code against its current promoted revision is idempotent. A different second code, or an attempt to replace the first promotion, is rejected. Promotions do not stack with each other.

Multi-option proposal behavior

Applying a code creates a new immutable proposal revision while keeping the customer's secure proposal link stable. The promotion is quoted across every proposal option, not only the option currently visible or eventually accepted. Each result option records its own prior total, eligible subtotal, discount, and discounted total.

W37 intentionally uses any-service eligibility with whole-option pricing:

• Service eligibility is evaluated against the union of authoritative service

slugs found across the proposal's options.

• If any restricted service matches, the promotion is eligible on the service

dimension.

• The percentage or flat amount is then calculated from each option's whole

total. It is not limited to matching line items.

This is the locked W37 contract. Do not describe a service-restricted code as a line-item-only discount.

Pricing-floor and maintenance-plan safety

For ordinary one-time options, the new option total must remain at or above the retained service floor. If any option would fall below its floor, the whole promotion attempt fails; the proposal is not partially rewritten.

Maintenance-tier snapshots do not yet retain a promotion-aware floor envelope. W37 therefore fails closed: a customer-entered promotion cannot reduce a proposal that contains a maintenance-tier option. The office can issue a separately reviewed plan revision instead. This restriction must remain until the pricing model can prove a safe promotion floor for the complete maintenance cadence.

Immutable evidence and analytics

A successful apply creates a new proposal revision and one promotion redemption record in the same transaction. The evidence retains:

• organization, location, promotion, client, and estimate identity;
• source and result proposal revision identity;
• the normalized code and exact promotion-terms snapshot;
• every source/result option mapping and prior/eligible/discounted totals;
• primary-option evidence, exact discount cents, and idempotency identity.

The proposal shows Promotion applied, the saved code, and the exact discount for the option being viewed. Payment schedules for allowed options are recalculated only when the full promoted revision passes its safety checks. Maintenance-tier options remain blocked as described above.

The office card reports:

• Redemptions — successful immutable promotion revisions;
• Unique clients — distinct clients represented by those redemptions;
• Discount delivered — the sum of primary-option discount evidence

recorded at redemption. It is not the customer's eventual accepted-option discount unless that option is the primary option.

These counters do not claim campaign attribution, accepted revenue, collected payments, profit, or ROI. Later deactivation, archive, proposal decline, withdrawal, cancellation, or refund does not erase the original redemption or restore a usage-cap slot.

Why Auto-Apply is not included

The V1 form displayed an Auto-Apply switch, but it did not have a complete, authoritative runtime that could safely choose an offer, prove eligibility, serialize caps, and preserve a proposal revision. W37 deliberately omits the switch and requires a customer-entered code. This is an intentional safety deviation from the V1 control, not a hidden automatic-discount feature.

Use a promotion in a marketing campaign

A campaign does not accept a typed or invented promotion value. Staff select one real promotion that is visible in their authorized organization and location scope. Campaign content can then include {{promotion.code}}, which renders the selected promotion's normalized saved code.

Campaign approval freezes both the promotion code and promotion version with the approved campaign revision. Delivery fails closed if the promotion is changed, archived, deleted, outside the campaign's authorized scope, or otherwise unavailable before a message is sent. The worker does not substitute another offer, continue with an old code, or fabricate a discount that is not backed by the selected promotion record.

Changing promotion terms after a campaign preview therefore requires a fresh campaign review and approval. After a promotion has a redemption, its terms are already locked; deactivate or archive it to stop future use, then select a new promotion and reapprove the campaign if a different offer is needed.

Practical checks before activation

• Verify the exact code, discount value, and inclusive dates.
• Confirm whether the offer is residential, commercial, or available to both.
• Review all selected offices and services.
• Keep the per-client cap at one unless repeat use is intentional.
• Preview the proposal's full option set. A maintenance-tier option blocks

customer code application in W37.

• Remember that a service match enables whole-option pricing across all

options.

• Distribute the code through an appropriate campaign or direct message; the

promotion service does not send marketing by itself.

• When using a campaign, select the real promotion and insert

{{promotion.code}}; do not type an unbound code into campaign copy.