# Cause Marketing for WooCommerce — User Guide

This guide walks you through everything from first-time setup to advanced
configuration. It assumes you have already installed and activated the plugin.

---

## Table of Contents

1. [First-Time Setup](#first-time-setup)
2. [Setting Donation Amounts](#setting-donation-amounts)
3. [Understanding the Donation Ledger](#understanding-the-donation-ledger)
4. [Admin Reports](#admin-reports)
5. [Front-End Messages](#front-end-messages)
6. [Display Settings — Colors and Fonts](#display-settings--colors-and-fonts)
7. [Shortcodes](#shortcodes)
8. [Charities (Pro)](#charities-pro)
9. [Campaigns and Progress Bars (Pro)](#campaigns-and-progress-bars-pro)
10. [Payouts (Pro)](#payouts-pro)
11. [Monthly Email Report (Pro)](#monthly-email-report-pro)
12. [Configuration Reference](#configuration-reference)
13. [Common Questions and Troubleshooting](#common-questions-and-troubleshooting)

---

## First-Time Setup

After activating the plugin, nothing will appear on your store front end until
you complete these steps. The plugin is entirely opt-in.

**Step 1 — Set your cause name and start date**

Go to **WooCommerce → Cause Marketing → Configuration**.

- **Cause name** — the name that appears in all donation messages, e.g.
  "cancer research" or "the Ocean Cleanup Fund". If left blank, messages will
  say "our cause".
- **Donation tracking start date** — the date from which donations are counted.
  Set this to your go-live date, or to a historical date if you want to include
  past orders in reports (note: past orders will only appear in reports if they
  were recorded by the plugin — see [Understanding the Donation Ledger](#understanding-the-donation-ledger)).
- **Starting amount** — an optional seed value added to all totals. Use this
  if you want to include donations raised before the plugin was installed.

Click **Save Configuration**.

**Step 2 — Add donation amounts to your products**

Open any product in **Products → All Products → Edit**. In the right sidebar,
find the **Donation** meta box.

- Choose **Flat ($)** to donate a fixed amount per unit sold, e.g. $2.00.
- Choose **Percentage (%)** to donate a percentage of the line item total,
  e.g. 5%.
- Enter the amount and click **Update** to save the product.

You can also set donation rules at the category level — see
[Setting Donation Amounts](#setting-donation-amounts).

**Step 3 — Enable front-end placements**

Go to **WooCommerce → Cause Marketing → Display → Messages**.

In the **Inline Placements** section, tick the locations where you want a
donation message to appear on product pages (short description, long
description, product tab, or after the Add to Cart button).

In the **Transaction Messages** section, enable any of the order-flow locations
you want (cart, checkout, thank you page, order email).

Click **Save Message Settings**.

**Step 4 — Check your store**

Visit a product page that has a donation amount set. You should see an italic
message in the locations you enabled. Add the product to your cart and proceed
through checkout — the donation message should appear in the cart total area
and at checkout.

**Step 5 — Display a public total (optional)**

Add the `[cause_message]` shortcode to any page — your homepage, a dedicated
"Our Cause" page, or a sidebar widget — to show a live running donation total
to visitors.

---

## Setting Donation Amounts

### Per product

Open any product in **Products → All Products → Edit**. The **Donation** meta
box appears in the right sidebar.

- **Flat ($)** — a fixed dollar amount donated per unit. A customer buying
  3 units at $2.00 generates a $6.00 donation.
- **Percentage (%)** — a percentage of the line item subtotal. A customer
  spending $50.00 on a product set to 5% generates a $2.50 donation.
- **None** — explicitly disables donations for this product, even if its
  category has a donation rule.

### Per category

Open any product category in **Products → Categories → Edit**. Scroll to the
**Donation Rule** section at the bottom of the edit form.

Set a flat dollar or percentage amount the same way as per-product rules.

### Rule priority

When a product has both a category rule and a product-level rule, the
**product-level rule always wins**. This lets you set a category default and
override it on individual products.

If a product belongs to multiple categories and each has a different donation
rule, the rule from the most deeply nested category is used.

Setting a product to **None** overrides any category rule and means that
product generates no donation.

### Variable products

Set the donation rule on the parent product. The same rule applies to all
variations. Variation-level rules are not supported in this version.

---

## Understanding the Donation Ledger

The plugin maintains a private database table (`wp_cause_donations`) that
records every donation generated by an eligible order. Understanding how it
works explains some behaviours you may notice.

### When a donation is recorded

A donation is recorded when an order reaches one of the eligible statuses you
have configured (default: Completed and Processing). One row is written per
line item per order.

### Pending vs confirmed

Every recorded donation starts as **pending**. It becomes **confirmed** after
the number of days set in the **Donation confirmation delay** field in
Configuration (default: 45 days).

- **Admin reports** always show both pending and confirmed donations in real
  time — your reports are never delayed.
- **Front-end totals** (shortcodes and messages) show only confirmed donations.
  This means a customer who just placed an order will not see their donation
  reflected in the public total until the delay period passes.

This is intentional. It prevents your public-facing total from including orders
that may still be returned or refunded.

If you set the delay to 0, all donations confirm immediately and appear in
front-end totals straight away.

### Why an order might not appear in reports

- The order status is not in your list of eligible statuses.
- The order was placed before the plugin was installed and has not been
  re-saved since installation.
- The product had no donation amount set at the time of the order.

### Re-recording an order

If you need to force an existing order into the ledger (e.g. after adding a
donation amount to a product retroactively), open the order in WooCommerce,
change its status, and save — this triggers the ledger recording logic.

---

## Admin Reports

Go to **WooCommerce → Cause Marketing → Report** to access the report suite.
All views support date range filtering at the top of the page.

### Summary

Shows three overview cards:

- **Confirmed donations** — total confirmed in the selected date range.
- **Pending donations** — total pending (within the delay window) in the range.
- **Products donating** — number of distinct products that generated donations.

Below the cards, the **Donation Breakdown** table shows confirmed and pending
totals split by charity (or General Fund if no charities are configured).

### By Product

Shows one row per product that generated donations in the selected date range.

- **Details** column — click the cart icon to open an order drawer showing
  all orders containing that product. Click the arrow icon (on variable
  products) to expand variation-level rows.
- **Donation/Unit** — for flat-dollar products, the fixed per-unit amount.
  For percentage products, the percentage rate with an average dollar amount
  shown below.
- **Total Donated** — the total donation generated by this product in the
  date range.

### By Order

Shows one row per order. Click the products icon in the **Details** column
to open a drawer showing every donating product in that order with its
individual donation amount.

### By Charity (Pro)

Shows confirmed and pending totals split by charity. The General Fund (for
donations not attributed to a named charity) always appears first.

Each charity row has two drawer icons:

- **Cart icon** — shows all orders that contributed to this charity in the
  date range.
- **Products icon** — shows all products that contributed to this charity.

The **Download CSV** button exports the full By Charity report, including
charity totals and payout history, as a spreadsheet.

---

## Front-End Messages

The plugin can display donation messages in several locations. Each location
is enabled or disabled independently in **Display → Messages**.

### Inline placements (product pages)

These appear as italic text that blends with the surrounding content —
no background color or border. They inherit the font and size of the
surrounding section.

| Placement | Where it appears |
|---|---|
| Short description | Below the product title, before Add to Cart |
| Long description | At the end of the main product description tab |
| Product tab | In a separate "Donations" tab (label configurable) |
| After Add to Cart | Below the Add to Cart button |

All four share the same message text, which you set in the **Inline Placements**
section of the Display tab.

### Styled placements (order flow)

These appear as styled message boxes with the colors and fonts you set in
Display settings.

| Placement | Where it appears |
|---|---|
| Cart total | Below the order total on the cart page |
| Checkout summary | Below the order total in the checkout sidebar |
| Thank you page | On the order confirmation page after checkout |
| Order email | In the customer's order confirmation email |

Each styled placement has its own message text field, which you edit directly
in the placement card on the Display tab. Leave the field blank to use the
default message.

### Message tokens

All message text fields support two tokens:

- `{amount}` — replaced with the formatted donation amount, e.g. `$5.00`
- `{cause}` — replaced with your cause name from Configuration

Example: `With this order, we will donate {amount} to {cause}.`

---

## Display Settings — Colors and Fonts

Go to **WooCommerce → Cause Marketing → Display** to control how messages
and progress bars look.

### Messages subtab

**Global colors** — set the background, text, and border colors for all
styled placement message boxes. Changes here affect cart, checkout, thank you,
and email messages simultaneously.

**Global typography** — set the font family, size, and weight for all styled
placements.

A **live preview** updates as you change settings so you can see exactly how
your message will look before saving.

**Admin Report Table Colors** — by default, the admin report table header uses
the same colors as your front-end messages. Uncheck **Sync with global
front-end colors** to set independent colors for the admin table.

**Per-placement overrides (Pro)** — enable this toggle to customise colors
and fonts independently for each order-flow placement. Each placement gets
its own accordion with color pickers and font controls. Placements that have
been customised show a "(customised)" label.

When per-placement overrides are disabled, global settings apply everywhere.
When enabled, any placement with no override values set still falls back to
the global settings.

**PDF Invoice Message** — the text that appears on PDF invoices. Limited to
200 characters. Supports `{amount}` and `{cause}` tokens.

### Progress Bars subtab (Pro)

Controls the appearance of `[cause_progress]` shortcode output.

- **Fill color** — the color of the filled portion of the bar.
- **Track color** — the background color of the unfilled portion.
- **Label text** — the color used for the charity name, amounts, and
  percentage label.
- **Border radius** — controls how rounded the bar ends are. Use `0` for
  square ends, `9999px` for a fully rounded pill shape.
- **Typography** — font family, size, and weight for the labels.

A **live preview** updates as you make changes.

---

## Shortcodes

### `[cause_message]`

Displays the running donation total. Place this shortcode on any page, post,
or widget area.

```
[cause_message]
```

By default it shows the total of all confirmed donations since your configured
start date, plus any seed amount. The total respects the delay window — orders
within the delay period are not included.

**Optional attributes:**

| Attribute | Description | Example |
|---|---|---|
| `start_date` | Override the start date for this instance only | `start_date="2024-01-01"` |
| `starting_amount` | Override the seed amount for this instance only | `starting_amount="1000"` |
| `test_mode` | Set to `yes` to include pending donations (bypasses delay) | `test_mode="yes"` |

### `[cause_progress]` (Pro)

Displays a campaign progress bar. See [Campaigns and Progress Bars](#campaigns-and-progress-bars-pro)
for full details.

---

## Charities (Pro)

Named charities let you route product donations to specific causes and track
them separately in reports.

Go to **WooCommerce → Cause Marketing → Charities**.

### Adding a charity

Click **Add Charity** and enter:
- **Name** — the charity's display name, used in reports and messages.
- **Website** — optional URL shown in the Charities tab.
- **Active** — only active charities accept donations. You can have up to
  3 active charities at a time. Inactive charities are kept for historical
  reporting but do not accept new donations.

### Setting a default charity

One charity can be marked as the default. The default charity receives
donations from products that have no specific charity assignment. If no
default is set, unassigned donations go to the General Fund.

### Assigning a charity to a product

Open a product in **Products → All Products → Edit**. In the **Donation**
meta box, use the **Charity assignment** dropdown to select:

- **General fund** — donations go to the unassigned pool.
- A named charity — donations go directly to that charity.
- **None** — this product generates no donation.

### Assigning a charity to a category

Open a category in **Products → Categories → Edit**. The Donation Rule
section includes a charity assignment dropdown.

---

## Campaigns and Progress Bars (Pro)

Campaigns let you run time-limited fundraising drives with goal tracking.
A campaign is attached to a charity and runs between a start and end date.

Go to **WooCommerce → Cause Marketing → Campaigns**.

### Setting up a campaign

1. Go to the **Charities** tab and click **Edit** on a charity.
2. Set a **Campaign start date**, **Campaign end date**, and **Campaign goal**.
3. Save the charity.

The campaign immediately appears in the Campaigns tab overview with its
progress bar, amounts raised, and status (Scheduled, Active, or Ended).

### Campaign status

| Status | Meaning |
|---|---|
| Scheduled | Start date is in the future |
| Active | Today falls between start and end dates |
| Ended | End date has passed |

### The `[cause_progress]` shortcode

Add a progress bar to any page:

```
[cause_progress]
```

To show a specific charity's campaign:

```
[cause_progress charity="123"]
```

Find charity IDs in the Campaigns tab — they are shown in the ID column.

**Full attribute reference:**

| Attribute | Default | Description |
|---|---|---|
| `charity` | Default charity | Charity post ID |
| `show_charity` | `yes` | Show charity name above the bar |
| `show_amounts` | `yes` | Show raised / goal amounts |
| `show_percent` | `yes` | Show percentage complete |
| `include_pending` | Config setting | Include pending donations in the raised total |
| `test_mode` | `no` | Show bar regardless of campaign status |

### Campaign history

When a campaign ends, you can reset it to start a new run. The previous run's
data (dates, goal, raised amount) is saved to the campaign history accordion
in the Campaigns tab. History is kept indefinitely.

### Retroactive reassignment

If you extend a campaign's date range after it has been running — either by
moving the start date earlier or the end date later — the plugin will detect
that some existing General Fund donations now fall within the expanded window.

A prompt will appear in the **Charities** tab asking whether you want to
reassign those donations to the campaign. The prompt shows:

- How many donations are affected
- The total amount
- The date range in question

You can accept the reassignment or dismiss it. The plugin will **never**
automatically reassign donations — it always asks first.

**Important:** Reassignment only works in the "expanding" direction — if you
shrink a campaign's date range, no donations are moved back to the General Fund.
This protects the integrity of previously confirmed reports.

---

## Payouts (Pro)

The Payouts tab tracks money you have actually paid to your charities, so you
can reconcile what has been donated against what has been disbursed.

Go to **WooCommerce → Cause Marketing → Payouts**.

### Recording a payout

1. Scroll to the charity you are paying.
2. Fill in the **Amount**, **Payment method** (e.g. bank transfer, cheque),
   optional **Note**, and **Date paid**.
3. Click **Record Payout**.

The payout is added to that charity's history and the reconciliation table
updates to show the remaining balance (confirmed donations minus total payouts).

### Reconciliation table

The table shows, for each charity:

- **Confirmed** — total confirmed donations in the current date range.
- **Paid out** — total payouts recorded.
- **Balance** — confirmed minus paid out. A positive balance means you owe
  the charity money. A negative balance (shown in red) means you have paid
  out more than has been confirmed — this can happen if you pay in advance
  of the delay window closing.

The **General Fund** always appears as the first row.

---

## Monthly Email Report (Pro)

The plugin can automatically email a donation summary to your team on the
1st of each month, covering the previous calendar month's activity.

Go to **WooCommerce → Cause Marketing → Configuration → Monthly Email Report**.

### Configuration

- **From name** — the sender name shown in the email. Defaults to your site name.
- **From address** — the sender email address. Defaults to your WordPress admin email.
- **Recipients** — comma-separated list of email addresses to receive the report.

### What the email contains

- Confirmed and pending donation totals for the previous calendar month.
- A breakdown by charity / General Fund.
- A note of any campaigns that started or ended during the month.
- A link to the full report in your WordPress admin.

### Testing

Click **Send Test Email** to send a report immediately using last month's data.
If no donation activity exists for last month, you will receive a delivery
confirmation email explaining this — which is useful for verifying your email
configuration is working correctly.

**Note:** Reliable email delivery requires an SMTP plugin. If you are not
already using one, install **WP Mail SMTP**, **Post SMTP**, or **Fluent SMTP**
and configure it with your mail provider credentials. Standard PHP mail is
often blocked or filtered as spam by mail servers.

---

## Configuration Reference

All settings are in **WooCommerce → Cause Marketing → Configuration**.

| Setting | Description | Default |
|---|---|---|
| Cause name | Name used in all front-end donation messages | "our cause" |
| Donation tracking start date | Orders before this date are excluded from totals | (none — required) |
| Starting (seed) amount | Added to all public totals — useful for pre-plugin history | 0 |
| Count guest donations | Whether guest checkout orders generate donations | Yes |
| Hide donation messages from | Roles that do not see messages and whose orders are excluded | (none) |
| Donation confirmation delay | Days before a pending donation is confirmed and shown publicly | 45 |
| Eligible order statuses | Which WooCommerce order statuses trigger donation recording | Completed, Processing |
| Who can view reports | Admin roles that can access the report and campaign tabs | Administrator, Shop Manager |
| Who can edit settings | Admin roles that can change configuration | Administrator |

---

## Common Questions and Troubleshooting

### Messages are not appearing on my product pages

1. Check that the product has a donation amount set in the **Donation** meta box.
2. Check that the placement is enabled in **Display → Messages → Inline Placements**.
3. If using Elementor, try enabling the **After Add to Cart** or **Long description**
   placement instead — some Elementor configurations intercept the short description hook.

### The `[cause_message]` shortcode shows $0.00

This usually means either:
- No products have donation amounts set yet, or
- Orders exist but all donations are still within the delay window (pending).

To verify, go to **Report → Summary** and check whether confirmed donations
appear in the date range. If you see confirmed donations in the admin but $0
in the shortcode, check your start date in Configuration.

To preview the total including pending donations, use `[cause_message test_mode="yes"]`.

### I can see donations in the admin report but not in the front-end total

This is expected behaviour. The front-end total only includes **confirmed**
donations (past the delay window). Admin reports always show real-time data
including pending donations. See [Understanding the Donation Ledger](#understanding-the-donation-ledger).

### An old order is not appearing in reports

Orders placed before the plugin was installed are not automatically added to
the ledger. To add an old order, open it in **WooCommerce → Orders**, change
its status (e.g. to On Hold then back to Completed), and save. This triggers
the recording logic.

### The campaign progress bar is not updating

Check that:
1. The campaign is **Active** (today falls between start and end dates).
2. The product generating donations is assigned to the campaign's charity.
3. Orders are in an eligible status (Completed or Processing by default).

### The retroactive reassignment prompt appeared — should I accept it?

The prompt appears when you expand a campaign's date range and existing General
Fund donations fall within the new window. Accepting reassigns those donations
to the campaign, which increases the campaign's raised total and reduces the
General Fund total by the same amount.

Accept if: you want those orders to count toward the campaign's goal.
Decline if: you want to keep those donations in the General Fund regardless.

This action cannot be undone automatically — if you accept and then change
your mind, you would need to contact support for assistance.

### The test email says it was sent but I did not receive it

Check your spam folder first. If it is not there:
1. Verify your SMTP plugin is configured correctly — send a test from the SMTP
   plugin itself to confirm delivery works independently.
2. On Kinsta staging environments, outbound email may be blocked at the server
   level. Install **WP Mail Catcher** on staging to inspect outbound mail
   without needing real delivery.

### I accidentally set the delay to 0 and all pending donations were confirmed — can I reverse this?

Setting the delay to 0 triggers a one-time bulk confirmation of all existing
pending rows. This cannot be automatically reversed. To restore specific
donations to pending status you would need direct database access. Contact
support if this happens in a production environment.

---

*For additional help, use the support forum on WordPress.org.*
