Promo Code Management

---

Part 1: The Promo Codes Page

1.1 Accessing the Promo Codes Page

Go to Dashboard → Marketing → Promo Codes (/dashboard/promos) from your dashboard navigation. This is your promo code catalog — the central list of every discount code you have created.

1.2 What You See

• A search bar at the top to find promo codes by code, title, or description.
• A status filter to narrow down by active, inactive, or expired.
• A discount type filter to see percentage, fixed, or free delivery codes.
• A "Create Promo Code" button (with a plus icon) to add a new code.
• A promo codes table showing: a checkbox column for bulk actions, the promo code text, title or description, discount type and value, status (active/inactive/expired), usage count, start date, end date, and action buttons (edit / toggle / delete).

1.3 Code Statuses

Each promo code shows one of three statuses:

1.4 Search and Filters

• Search: Type any keyword — it searches the code text, title, and description.
• Status filter: Active, Inactive, or Expired.
• Discount type filter: Percentage, Fixed Amount, or Free Delivery.
• Sort: By date created (default), code text, discount value, or start date. Ascending or descending.
• Pagination: 20 promo codes per page by default.

1.5 Bulk Actions

Select one or more codes by ticking the checkbox next to each row. A bulk actions bar appears at the bottom showing how many codes you selected:

• Activate Selected: Turns on all selected codes.
• Deactivate Selected: Turns off all selected codes.
• Delete Selected: Permanently removes all selected codes (with a confirmation dialog).

---

Part 2: Creating a New Promo Code

2.1 Opening the Create Page

Click "Create Promo Code" or go to /dashboard/promos. The page opens with a form split into sections.

2.2 Page Layout

• Header: Back arrow, breadcrumb (Marketing / Promo Codes / Create), page title "Create Promo Code", and Save / Cancel buttons.
• Form sections: 5 sections — Basics, Conditions, Limits, Schedule, and Target Audience.

2.3 Section 1: Basics

Code (required): The text customers type in at checkout. Use uppercase letters and numbers for best results. Examples: SUMMER25, FREESHIP, WELCOME10. Codes are case-insensitive at checkout — summer25 and SUMMER25 work the same way.

Title (required): An internal label to help you identify this code in the list. Example: "Summer Sale 2026" or "New Customer Welcome".

Description (optional): Internal notes about what this code is for. Not visible to customers.

Discount Type: Choose one of three:

Discount Value (required): The actual discount amount.

• For Percentage: Enter a number between 1 and 100.
• For Fixed Amount: Enter a currency amount greater than 0.
• For Free Delivery: No value needed — delivery is automatically set to zero.

2.4 Section 2: Conditions

Minimum Order Amount: The smallest order subtotal (before discount) that must be met for the code to apply. Leave at 0 for no minimum.

Maximum Discount Amount: The most discount the code can give. Use this to cap a percentage discount on very large orders. Example: A 20% discount with a max of ৳500 means a ৳10,000 order only gets ৳500 off, not ৳2,000.

Usage Limit: The total number of times this code can be used across all customers. Leave blank for unlimited.

Per-Customer Limit: How many times a single customer can use this code. Set to 1 for one-time-use codes.

2.5 Section 3: Schedule

Start Date (required): The date and time the code becomes active. Can be set in the future to schedule a campaign.

End Date (required for all codes): The date and time the code expires. After this time, the code shows as Expired and cannot be used.

Both fields use a date-time picker with timezone support based on your store's configured timezone.

2.6 Section 4: Target Audience

Specific Categories: Optionally restrict the code to only products in certain categories. Select one or more categories from a multi-select dropdown. If no categories are selected, the code applies to all products.

Specific Products: Optionally restrict the code to only specific products. Search and select products from a multi-select dropdown. If no products are selected, the code applies to all products.

Specific Customers: Optionally restrict the code to only specific customers. Search and select customer accounts from a multi-select dropdown. The code will only work when those specific customers are logged in.

These three fields can be combined. When more than one is set, the customer's order must match all of the conditions for the code to apply.

2.7 Saving the Promo Code

Click Save. The system validates:

• The code text is unique (no duplicates).
• The start date is before the end date.
• The discount value is valid for the selected type.
• Minimum order is not higher than maximum discount (if both are set).

On success: A toast notification confirms "Promo code created successfully". You are redirected back to the promo codes list.

---

Part 3: Using a Promo Code at Checkout

3.1 Customer Flow

1. The customer adds items to their cart.
2. On the checkout or cart page, they see a "Have a promo code?" field.
3. They type the code and click Apply.
4. The system checks the code against all conditions:
   • Is the code active?
   • Is the current time between the start and end dates?
   • Is the minimum order amount met?
   • Is the usage limit still available?
   • Is the per-customer limit still available?
   • Does the customer match the target audience (specific customers / categories / products)?
5. If all checks pass, the discount is applied.
6. The cart total updates instantly — the discount line appears on the order summary.
7. The customer completes the checkout with the discounted total.

3.2 What the Customer Sees

When a code is applied successfully, the cart page shows:

• Original subtotal — the full price before discount.
• Discount — the promo code label and the deducted amount.
• Discounted subtotal — the remaining total after the discount.
• Delivery charge (if the code is not a free-delivery code) or "Free Delivery" (if it is).
• Grand total — the final amount to pay.

3.3 Applying in the Admin

From Order Management (/dashboard/orders), staff can also apply promo codes to orders on behalf of customers:

• Click "Add Discount" on an order.
• Select "Promo Code" from the discount type dropdown.
• Enter the code or pick one from the list.
• The code is validated the same way as the customer checkout.

---

Part 4: What Happens When a Promo Code Doesn't Work

4.1 Error Messages at Checkout

When a promo code fails, the customer sees a clear error message. Here is every error case:

4.2 Admin-Side Errors

When a staff member applies a code in the admin panel, the same errors apply. Additionally:

All errors appear as inline notifications, not modal dialogs, so the customer can correct the issue and retry without leaving the page.

---

Part 5: Editing a Promo Code

5.1 Opening the Editor

Go to /dashboard/promos or click the three-dot menu on a promo code row and choose Edit. The editor looks identical to the Create page, with all fields pre-filled.

5.2 What You Can Change

• Code: The promo code text. Changing this breaks all existing links to the old code — the system warns you if the code has been used before.
• Title: The internal label.
• Description: Internal notes.
• Discount Type: Can be changed only if the code has zero usage. If the code has been used, the type is locked.
• Discount Value: Updated freely.
• All conditions: Minimum order, maximum discount, usage limit, per-customer limit, start/end dates, specific categories, specific products, specific customers.
• Active status: Toggle on/off.

5.3 What You Cannot Change

• The usage count — this is read-only, tracked automatically by the system.
• The created date — this is set once and never updated.

5.4 Saving Changes

Click Save. The system re-validates all conditions (including any new ones). On success, a toast confirms "Promo code updated". On failure, the form stays open with inline errors.

---

Part 6: Activating / Deactivating a Promo Code

6.1 Toggle from the List

From the promo codes table, each row has a toggle switch (or eye icon). Click it to toggle the code's active state:

• Active → Inactive: The code is immediately disabled. Any customer who types this code at that moment will see "This promo code is currently not active."
• Inactive → Active: The code is re-enabled. It works again immediately, provided the start/end dates allow it.

6.2 Toggle from the Edit Page

On the edit page, there is a "Active" toggle switch in the sidebar. Same behavior as the list toggle.

6.3 Scheduled Activation

If a code's Start Date is in the future, the code shows as Inactive with a label "Scheduled for [date]". It automatically activates when the start date passes. You do not need to manually toggle it on.

6.4 Expired Codes

A code whose End Date has passed shows as Expired in the status column. You can:

• Re-activate it by editing the end date to a future date and toggling the active state.
• Delete it permanently.
• Leave it as-is for reporting purposes.

---

Part 7: Deleting a Promo Code

7.1 Deleting a Single Code

From the promo codes list, click the three-dot menu on a code and choose Delete. A confirmation dialog appears:

"Are you sure you want to delete this promo code? Orders that used this code will retain their discount details, but the code will no longer be usable."

Click Confirm to delete. The code is removed from the list and cannot be applied again.

7.2 Bulk Delete

From the promo codes list, tick multiple codes and click Delete in the bulk actions bar. The same confirmation appears with the count of codes to delete. Confirm once to delete all selected codes.

7.3 What Happens to Existing Orders

When a promo code is deleted, existing orders that used the code are not affected. The discount is already locked into those orders. The deletion only prevents new uses. Order records preserve:

• The promo code text (stored as a string, not a foreign key).
• The discount amount.
• The discount type.

This means deleted codes are still visible in order history and reports.

---

Part 8: Promo Code Performance Tracking

8.1 Usage Metrics

From the promo codes list, each row shows live metrics:

8.2 Per-Code Report

Click any promo code row to open a detailed report showing:

• Usage over time: A line chart of uses per day, week, or month.
• Top products in orders that used this code.
• Top customers who used this code (with email and order count).
• Total revenue and total discount given.

8.3 Export

Click "Export Report" on any promo code to download a CSV file with:

• Order ID, date, customer, subtotal, discount, total, and the promo code text applied.

Use this for accounting, campaign analysis, or tax reconciliation.

---

Part 9: Quick Reference

Pages

Required Fields for a Promo Code

Promo Code Statuses

Discount Types

Common Actions

Error Messages Quick Reference

---

End of Guide

Your promo code system is ready. You can create targeted campaigns with any combination of conditions, monitor their performance, and give your customers a clear, reliable discount experience at checkout.