How can we help?

Important: VitalHub requires the VitalHub Core companion plugin. Both the theme and plugin are included in your download package.

Step 1 — Install the Plugin

1
Go to WordPress Admin → Plugins → Add New → Upload Plugin

2
Upload vitalhub-core.zip and click Install Now

3
Click Activate Plugin

Step 2 — Install the Theme

1
Go to Appearance → Themes → Add New → Upload Theme

2
Upload vitalhub-theme.zip and click Install Now

3
Click Activate

Step 3 — Configure

1
Go to VitalHub → Settings in your WordPress admin menu

2
Enter your app name, Anthropic API key, and digest email address

3
Optionally click Import Demo Data to populate the dashboard with sample records

After activating the theme and plugin, visit your site’s homepage. You will see the Family Health Hub dashboard. The first time you open it:

• Two default family members (Alex and Sam) are pre-configured — rename them in the app by clicking their name
• All sections are empty until you add data or import demo records
• AI features require an Anthropic API key (see below)

VitalHub supports four AI providers. You choose which one to use in Appearance → Customize → AI Settings → AI Provider. All API keys are stored server-side only — never sent to the browser.

Supported Providers

Setup Steps

1
Create an account with your chosen AI provider and generate an API key

2
In WordPress admin, go to Appearance → Customize → AI Settings

3
Select your AI Provider from the dropdown

4
Paste your API key in the corresponding field and click Publish

Cost estimate: A typical family using the AI advisor a few times per week costs approximately $1–5/month in API usage, depending on the provider and usage volume. Groq offers a generous free tier suitable for light use.

The dashboard is the home screen. It shows:

• Health Alerts — automatic warnings for abnormal lab values (D-Dimer, HDL, SpO2, etc.)
• Medication banner — today’s medications with adherence percentage and Log Doses button
• Appointment reminders — upcoming and unmarked past appointments
• Lifestyle widgets — water intake, sleep hours, and BMI at a glance
• Recent activity — latest log entries and health events

The central feature of VitalHub. Track test results for 14 organ systems:

❤️

Heart & Circulation

Blood pressure, cholesterol, heart rate, ECG notes

🩸

Blood & Clotting

CBC, D-Dimer, ESR, coagulation tests

🫁

Lungs

SpO2, peak flow, pulmonary function

🧠

Brain & Nervous System

Neurological assessments and cognitive notes

🫘

Kidneys

Creatinine, GFR, urea, electrolytes

🫀

Liver

ALT, AST, bilirubin, albumin

Each organ page lets you log test results with date, value, reference range, and status (Good / Watch / Concern). Results build a timeline you can review in the Trends tab.

The dedicated Medications tab provides:

• Daily log — mark each medication as Taken or Skipped for any date (date picker for past days)
• 30-day adherence calendar — colour-coded grid showing your medication consistency
• Active / Inactive status — deactivate medications you’ve stopped without losing history
• Add medications — with dose, frequency, related organ, start date, and notes
• Medication history — all past medications with start and stop dates

The AI Advisor uses your actual health data to generate personalized insights. It works with any of the four supported AI providers — configure your provider in Customizer. Available prompts:

All responses can be saved to your Saved Responses panel or printed directly from the interface.

Upload any health document — the AI automatically identifies the content type and extracts structured data:

• Lab reports (photo or PDF) → logged to Organ Health
• Meal plans → saved to Meal Plans
• Prescriptions → added to Medications
• Appointment letters → added to Appointments
• Grocery lists → added to Grocery List
• Symptom notes → saved to Symptoms journal

You can also paste text directly — useful for copying meal plans, workout routines, or doctor notes.

Each family member can have their own meal plan. Generate one using the Nutrition Plan chip in the AI Advisor, or create meals manually. The Grocery List is shared across family members and includes category organization and checkbox completion tracking.

Log workouts using built-in templates or generate a personalized plan via AI. Track sets, reps, weights, and duration. Weekly workout count and total minutes display on the Fitness page.

• Water — 8-glass daily goal (250ml each = 2L). Log for any past date. 7-day history chart.
• Sleep — hours and quality rating. 14-day bar chart with 7-day average.
• Weight & BMI — log in kg or lbs. Height stored for automatic BMI calculation. 30-day trend chart.

Each family member has a digital emergency medical card containing blood type, organ donor status, known conditions, current medications, allergies, emergency contacts, and primary doctor. Download as a printable HTML file that renders as PDF via the browser print dialog.

Go to VitalHub → Settings in WordPress admin:

Visual customization (colors, logo) is available via Appearance → Customize.

Click any member’s avatar in the sidebar to switch the active member. All tabs — Organ Health, Medications, Meals, Fitness, etc. — show data for the currently selected member. Click + Add member to add more family members.

VitalHub automatically sends a weekly health summary every Sunday at 8am to your configured digest email. The email includes:

• 7-day medication adherence percentage for each member
• Active health concerns (flagged lab results)
• Upcoming appointments

Configure the recipient email in VitalHub → Settings → Weekly Digest Email.

Go to Appearance → Customize to change:

• Logo image
• App name and tagline
• Primary and accent colors
• Show/hide tagline

VitalHub is fully translation-ready. A .pot template file is included at languages/vitalhub.pot.

To translate VitalHub:

1. Open the .pot file in Poedit
2. Translate all strings
3. Save as vitalhub-fr_FR.po (replace fr_FR with your locale)
4. Upload both .po and .mo files to the languages/ folder in the theme
5. Set your WordPress language in Settings → General → Site Language

Note: The app interface labels (dashboard text, tab names, form labels) are managed via the Labels system in inc/labels.php and support the WordPress translation API.

For support, bug reports, and feature requests, please use the Envato comments section on the item page or contact us via our support portal.

Before submitting a support request, please:

• Check that both the theme and VitalHub Core plugin are active
• Verify your Anthropic API key is correct (for AI feature issues)
• Check the browser console for JavaScript errors
• Try deactivating other plugins to rule out conflicts

VitalHub v1.0.0 — Documentation
© 2025 VitalHub. Released under GPL-2.0+

TeamHub turns your WordPress site into a complete, private operations workspace for a small team — projects & tasks, team timesheets with approvals, expense approvals, a client CRM, scheduling, leave management, a team password vault, invoicing, contracts, and an AI assistant. Everyone works in one place that you own and control, and each person sees exactly what their role allows.

No monthly per-seat SaaS fees. No data sold to anyone. Everything lives in your own WordPress database. Each team member logs in with their own account and gets a role-appropriate view of the workspace.

TeamHub is the multi-user, team edition of FreelanceHub. Where FreelanceHub is built for one freelancer, TeamHub is built for an owner who runs a team: it adds roles, invitations, and approval workflows on top of the same clean, fast interface.

1

Upload the theme

In WordPress admin go to Appearance → Themes → Add New → Upload Theme. Choose teamhub-theme.zip and click Install Now.

2

Activate

Click Activate. On activation, TeamHub automatically creates the database tables it needs. The WordPress administrator who activates the theme becomes the workspace Owner.

3

Visit your site

Open your site’s home page. You’ll land on your TeamHub dashboard. From there you can set business details, invite your team, and (optionally) add an AI key.

After installing any update, do a hard refresh — Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac) — so your browser loads the newest files instead of a cached copy. If you use a caching plugin, clear its cache too.

TeamHub has three roles. Your WordPress administrator is always the Owner. The role controls how much of each module a person can see and do — not which buttons exist, but the scope behind them.

One rule is absolute: nobody can approve their own submission, regardless of role. A manager who logs their own time still needs an owner (or another manager) to approve it.

Employees and managers share the same sidebar; Invoicing and Contracts are simply hidden from anyone who isn’t the Owner. This keeps the interface consistent while quietly enforcing what each person is allowed to touch.

TeamHub is private by design. Anyone who isn’t logged in is sent to the login screen, so your data is never publicly visible. Log in with your WordPress account and you’ll land on a dashboard tailored to your role.

Each person’s workspace is tied to their WordPress account, so they can log in from a laptop, phone, or tablet and see the same data. Non-owner members are kept out of wp-admin and the admin toolbar is hidden for them — they only ever see the clean TeamHub interface. The Owner keeps full WordPress admin access.

As the Owner, open Team and click Add team member. Enter their name, email, and role. TeamHub creates a WordPress user for them and sends an invitation email containing a secure, tokenized link where they set their own password and complete their profile.

Invitation emails need working email on your site. WordPress’s built-in mail is unreliable on many hosts. Install an SMTP plugin (for example WP Mail SMTP) and connect it to a real mailbox so invitations actually arrive. If an email doesn’t reach someone, you can copy the invite link from the Team screen and send it to them directly.

You can change a member’s role at any time from the Team module, and remove members who leave.

Before sending invoices, set your company details once. Go to Invoicing and click Business details. These details are company-wide — TeamHub uses a single business identity for the whole workspace, not per-person. Fill in:

• Business name — appears as the sender on every invoice
• Email, phone, address
• Default payment details — bank/transfer info that appears on any invoice without its own notes

The payment-details field accepts simple HTML. Use <br> for line breaks and <strong>…</strong> for bold labels.

Your invoice logo is pulled automatically from your WordPress site logo or site icon (set under Appearance → Customize → Site Identity).

The AI Assistant is optional and workspace-wide. The Owner supplies an API key from a supported provider; that one key powers the assistant for the whole team. Keys are stored server-side, encrypted, and are never exposed to the browser.

1

Get a key

Create an API key from Anthropic (for Claude) or OpenAI (for ChatGPT).

2

Add it (Owner only)

Open AI Assistant, go to its settings, and paste your key. Once saved, everyone on the team can use the assistant.

The dashboard adapts to your role. An Owner sees company-wide figures (revenue, outstanding invoices, team hours, active team). A Manager sees team hours, open tasks, and pending approvals. An Employee sees their own hours, tasks, and what’s due today. A Needs your attention panel surfaces what requires action — approvals waiting, overdue invoices, tasks due today — and Quick actions link to the modules each role uses most.

Organize work into projects, each holding tasks with assignees, priorities, due dates, and status. Employees see the tasks assigned to them; managers and owners see and assign everything across the team. Progress on each project reflects its completed tasks.

Time is measured, not typed. Click Log time to reveal a built-in stopwatch: write what you’re working on, optionally tag a project and client, and press play. When you stop, the session is logged automatically as a draft. There is no manual duration field — this keeps recorded time honest.

How the stopwatch behaves: press play only when you actually start working; if you stop to do something else, press stop, then play again when you resume — the system sums your sessions. It is a live-tab timer, so it runs while the Timesheets tab is open; very short sessions (under a few seconds) are discarded.

Draft entries can be deleted while still drafts. Once you submit an entry for approval, it’s locked — no editing and no deleting — so the measured time stands as the record. Owners don’t log time; they approve it.

Log business expenses with an amount, category, date, and optional client. Employees submit expenses for approval; managers and owners review and approve or reject them. Like timesheets, a submitted expense is locked pending a decision.

Keep client records with contacts, industry, status (active, lead, proposal, inactive), and revenue. Employees see only the clients assigned to them; managers and owners see all clients and can assign them. Filter chips and search make a large client list easy to navigate, and a pipeline view groups clients by stage.

Book meetings in a calendar or list view. Employees see their own meetings; managers and owners see the whole team’s schedule, which makes coordination straightforward.

Members request time off (vacation, sick, personal) with dates and a note. Managers and owners approve or decline. The dashboard flags pending leave requests so they don’t get lost.

A secure place for credentials, protected by a 4-digit PIN you set on first use and enter once per session. Stored values are encrypted in the database.

Personal items are truly private. A vault item saved with personal scope is visible only to the person who created it — not to managers, not to the Owner, not even to the WordPress administrator. Only items explicitly marked shared are visible to the team (and manageable by their creator or a manager). This lets anyone safely keep personal logins alongside shared team credentials.

Forgot your PIN? Because you’re already logged in, you can reset it from the vault and set a new one — your saved passwords are not affected.

Everyone can view the team roster. Only the Owner manages members and sets pay rates — and pay rate is stripped from the data entirely for anyone who isn’t the Owner, so it can’t be seen even by inspecting the page. Owners aren’t assignable to work (they oversee rather than execute).

TeamHub includes built-in internal communication so your team can talk without leaving the workspace. The Messages module has two tabs:

• Direct — private one-to-one conversations between any two team members. A thread is visible only to its two participants; nobody else can read it, not even the owner (the same absolute privacy as personal vault items). Conversations show an unread count, and the sidebar shows a badge when you have unread messages.
• Announcements — a team-wide notice board. Managers and owners post announcements; everyone reads them. Good for reminders, updates, and anything the whole team should see.

Messages refresh automatically every few seconds while you’re viewing the module, and the refresh pauses when the browser tab is hidden to keep things light. This uses simple polling rather than websockets, which is reliable on ordinary WordPress hosting.

Owner only. Create and send invoices with line items, track their status (draft, pending, paid, overdue), and print or save them as PDF. Invoicing is company-wide and uses your one business identity. Pending and overdue totals feed the Owner dashboard.

Owner only. Draft contracts and proposals, track their status, and keep them alongside the rest of the business in one place.

Everyone can use the AI Assistant; the quick-prompts are tuned to each role. Switch between Claude and ChatGPT (whichever keys the Owner has added). Only the Owner can change the integration and keys.

Timesheets, expenses, and leave all share the same flow:

1. A member creates an entry (a draft) — they can still edit or delete it.
2. They submit it for approval — it locks.
3. A manager or owner approves or rejects it. A rejected entry can carry a reason and be reworked.

No one can approve their own submission. The check is enforced on the server, not just hidden in the interface.

On Timesheets and Expenses, owners and managers get a filter bar to review any individual’s totals. Pick a member and a period — This week, This month, This year, All time, or a custom date range — and the list narrows while the stat cards re-total to match. When a single member is selected, a summary banner shows exactly whose numbers you’re viewing (for example, “Showing — Jane Doe · this month — 34h 20m across 12 entries”). Employees don’t see the filter; they only ever have their own data.

Each person picks their own color theme — like WordPress’s admin color schemes. Open your profile (click your avatar at the bottom of the sidebar) and choose from nine curated palettes under Appearance: Default, Dark, Midnight, Ocean, Forest, Slate, Rose, Sunset, and Grape. The choice applies instantly, saves to your account, and follows you across devices. Themes are curated rather than freeform, so every combination stays readable.

TeamHub is translation-ready. The interface follows your WordPress Site Language (Settings → General → Site Language), and a per-user language under each profile is also respected.

French (fr_FR) and Spanish (es_ES) translations are included. For any other language, a translation template (teamhub.pot) ships in the theme’s /languages folder — translate it with a tool like Loco Translate or any PO editor, save the resulting .mo file as teamhub-{locale}.mo in that folder, and set your Site Language to match.

Coverage note: the translations cover the interface you work in day to day — navigation, dashboard, labels, buttons, and notifications. A small number of less-common, module-specific strings remain in English; they appear in English within an otherwise translated interface. The included .pot lists every translatable string, and coverage can be extended at any time by translating more of it.

TeamHub gives WordPress’s login screen a clean, branded look: your site favicon appears in a round badge in place of the WordPress logo, the extra links are removed, and a note reminds members that if they forget their password they should ask the workspace Owner to send a reset link (since members don’t manage their own accounts through wp-admin). Set your favicon under Appearance → Customize → Site Identity → Site Icon — the same icon also appears as the brand mark in the TeamHub sidebar.

• Private by default — the whole workspace requires login; nothing is public.
• Role-scoped data — what each person can read and change is enforced on the server, not just hidden in the UI.
• Personal vault items are visible only to their creator — never to managers, owners, or the admin.
• Pay rates are removed from data for everyone but the Owner.
• AI and vault secrets are stored encrypted, server-side, and never sent to the browser.
• You own the data — it all lives in your WordPress database.

Something won’t save, or a list won’t load

Do a hard refresh (Ctrl/Cmd+Shift+R) and clear any caching plugin. Most “it didn’t update” issues are a browser serving old cached files.

A change to colors or layout doesn’t appear

Same cause — cached CSS. Hard-refresh; the theme version changes on each update specifically to bust the cache.

Invitation emails aren’t arriving

Your site needs working email. Install and configure an SMTP plugin. In the meantime, copy the invite link from the Team screen and send it directly.

The interface is still in English after changing language

Make sure you changed Site Language under Settings → General (the front-end follows this), not only your admin profile language. Confirm a matching teamhub-{locale}.mo file exists in /languages.

The AI Assistant returns an error

Check that the Owner has added a valid API key in the AI Assistant settings and that the chosen provider matches the key.

Is there a per-seat fee?

No. TeamHub runs on your own WordPress site. You can add as many team members as your hosting supports, with no per-seat charge from the theme.

Can a manager approve their own timesheet?

No. No one can approve their own submission — it always needs a different approver.

Can the Owner see an employee’s personal vault passwords?

No. Personal vault items are private to their creator, full stop. Only shared items are visible to the team.

Do I need an AI key?

Only if you want the AI Assistant. Everything else works without one.

What’s the difference between TeamHub and FreelanceHub?

FreelanceHub is built for a single freelancer. TeamHub is the team edition — it adds roles, invitations, and approval workflows so an owner can run a team in the same workspace.

FreelanceHub turns your WordPress site into a complete, private workspace for running a freelance business — invoicing, expenses, time tracking, contracts, a password vault, CRM, projects, scheduling, and an AI assistant, all in one place that you own and control.

No monthly SaaS fees. No data sold to anyone. Everything lives in your own WordPress database, accessible from any device after you log in.

1

Upload the theme

In WordPress admin go to Appearance → Themes → Add New → Upload Theme. Choose freelancehub-theme.zip and click Install Now.

2

Activate

Click Activate. On activation, FreelanceHub automatically creates the database tables it needs to store your data.

3

Visit your site

Open your site’s home page. You’ll be taken to your FreelanceHub dashboard. That’s it — no separate plugin or configuration required to start.

After installing any update, do a hard refresh — Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac) — so your browser loads the newest files instead of a cached copy. If you use a caching plugin, clear its cache too.

FreelanceHub is private by design. Anyone who isn’t logged in is redirected to the WordPress login screen, so your data is never publicly visible. Log in with your WordPress account and you’ll land on the dashboard.

Your workspace is tied to your WordPress user account, which means you can access the same data from your laptop, phone, or tablet — just log in.

Before sending invoices, set your business details once. Go to Invoicing and click Business details in the top bar. Fill in:

• Your name / business name — appears as the sender on every invoice
• Email and phone
• Address — shown under your name on the invoice
• Default payment details — bank/transfer info that automatically appears on any invoice that doesn’t have its own notes

The payment-details field accepts simple HTML for formatting. Use <br> for line breaks and <strong>…</strong> for bold labels. Example:

<strong>Bank:</strong> Your Bank Name<br>
<strong>Account:</strong> 0000000000<br>
<strong>IBAN:</strong> XX00 0000 0000 0000

Your business logo on invoices is pulled automatically from your WordPress site logo or site icon (set under Appearance → Customize → Site Identity).

The AI Assistant is optional. To use it, you supply your own API key from a supported provider. Keys are stored server-side only and are never exposed to the browser.

1

Open the AI Assistant module and click the settings (gear) icon.

2

Paste your API key and save. You can switch between Claude and ChatGPT at any time using the toggle at the top of the assistant.

AI usage is billed by your provider, not by FreelanceHub. Typical light use costs a few dollars a month. You stay in full control of your own key and spending.

The home dashboard is your daily command center. It shows quick stats (active clients, pending invoice value, hours logged this week) and a Needs your attention section that surfaces what’s urgent — overdue invoices with totals, meetings today, invoices awaiting payment, and upcoming meetings. Each item links straight to the relevant module. When nothing’s urgent, the section stays hidden to keep things clean.

The module cards below let you jump into any area in one click.

Create professional invoices, track their status, and produce client-ready PDFs.

🧾

Create & edit

Add line items with quantity and rate (decimals supported for fractional hours). Edit any invoice later — it updates in place.

📄

Download PDF

The eye icon opens a clean printable invoice. Use your browser’s “Save as PDF” to download a real PDF — no plugins needed.

📋

Duplicate

Copy any invoice as a new draft — ideal for recurring monthly billing.

⏰

Auto-overdue

Invoices marked “due” automatically flip to “overdue” once the due date passes.

Status labels (Draft, Pending, Overdue, Paid) are for your own tracking and are hidden from the client-facing PDF — except a green PAID stamp, which shows when an invoice is marked paid.

Log business expenses, mark which are tax-deductible, and see a category breakdown. Filter by category, attach each expense to a client or project, and edit any entry. Amounts support decimals. Expenses you flag as deductible feed directly into the Tax module’s profit and deduction calculations.

The Tax module turns the numbers you already record into a year-round tax plan. It estimates what you’ll owe, helps you set money aside, and keeps your filing deadlines in view. Everything here is an estimate to help you plan — it is clearly labelled as such and is not a substitute for advice from a qualified accountant.

How the estimate is built

• Income is the total of your paid invoices for the selected tax year.
• Deductible expenses are the expenses you marked deductible in that year.
• Net taxable profit = income − deductible expenses. This is the figure your tax is estimated on.
• Estimated tax applies your configured rate (or your own tax brackets) to that profit.

The tax savings pot

Rather than just showing a number, the module tracks money you actually set aside. Click Log a transfer to savings whenever you move money to your tax savings, and the progress bar shows how close you are to your target (your set-aside percentage of estimated profit). This turns a passive estimate into an active habit, so the bill is never a surprise.

Deductions by category

Your deductible expenses are grouped by category so you can see where your write-offs come from and spot anything you may have missed.

Deadlines & schedule

By default FreelanceHub assumes annual filing and shows your annual return as the main deadline. If you pay quarterly estimates, switch the filing schedule to Annual + quarterly estimates in settings to reveal a quarterly set-aside plan and quarterly reminders.

Settings — make it fit your country

FreelanceHub doesn’t assume any one country’s tax system. In Tax settings you control:

• Currency symbol shown throughout the module.
• Income tax rate and an optional separate self-employment / social rate — the layer freelancers most often forget.
• Set-aside % — how much of profit to save for tax.
• Filing schedule (annual, annual + quarterly, or custom) and your annual filing date.
• Country / region note — a free-text note that gives the AI assistant context about your situation.
• Tax brackets (advanced) — instead of a flat rate, enable brackets and enter your own bands. FreelanceHub does the maths; you supply the numbers, so it’s always correct for your country and never out of date.

Ask the AI assistant about your taxes

The Ask about my taxes button hands your current snapshot — profit, deductions by category, your rates, set-aside status, and your region note — to the AI Assistant, pre-filled in the chat. It can then explain your estimate in plain language, point out deductions you may be missing, and walk you through preparing to file. It explains and organizes; it does not give formal tax advice. (Requires an AI key — see AI Assistant Setup.)

Track billable time with a live start/stop timer or manual entries. Assign each entry to a project and client, see your week at a glance, and edit entries to fix descriptions or reassign projects. Logged hours can be pulled directly into an invoice (see How Modules Connect).

Draft contracts and proposals with client details, scope, value, and payment terms. Mark documents as signed, edit them anytime, and track totals across all documents.

A secure place to store client and account credentials. Passwords are encrypted (AES-256) before being saved to the database. The vault is protected by a 4-digit PIN.

• Set once, works everywhere — your PIN is stored server-side (hashed), so it follows your account across devices.
• Unlocks per session — enter the PIN once; it stays unlocked as you navigate, until you click Lock or close the browser.
• Forgot PIN? — because you’re already logged into WordPress, you can reset it from the unlock screen. Your saved passwords aren’t affected by a reset.
• Strength meter and a built-in strong-password generator.

The PIN is an on-screen convenience lock to stop passwords being revealed casually. Your real security boundary is your WordPress login — anyone who can log into your WordPress account can reach this data. Always use a strong WordPress password and HTTPS.

Keep a directory of clients and leads with contact details, industry, status, and value. Click any client to open a detail view showing their linked invoices, projects, contracts, meetings, and logged time — plus quick-action buttons to create any of those pre-filled for that client. Edit clients anytime.

Organize work into projects with status, priority, deadline, and budget. The dashboard counts active projects and flags overdue ones. From a project’s detail view you can edit it, change status, or generate an invoice pre-filled with that client and project.

Book meetings and calls with clients, view them in a calendar or list, and edit any entry. The dashboard surfaces meetings happening today and coming up.

A built-in chat assistant powered by your choice of Claude or ChatGPT. Use the one-click shortcuts to draft client emails, write proposals, compose payment reminders, plan a rate increase, brainstorm services, or improve your writing — or just type any question.

FreelanceHub isn’t ten separate tools — the modules share data:

• Client picker everywhere — start typing a client’s name in Invoicing, Contracts, Projects, Scheduling, Time Tracker, or Expenses and it autocompletes from your CRM, pulling in their email automatically.
• Project picker — Time Tracker and Expenses let you pick from your live project list.
• Time → invoice — pull logged hours into an invoice as line items, grouped by project.
• Project → invoice — generate an invoice straight from a project, pre-filled with client and project.
• Client detail hub — one screen shows everything linked to a client, with quick actions to create new records pre-filled for them.
• Invoices & expenses → tax — the Tax module reads your paid invoices as income and your deductible expenses as write-offs, so your tax estimate stays current with no extra data entry.
• Tax → AI assistant — send your tax snapshot to the AI assistant in one click for a plain-language explanation.

Open Backup & Export from the bottom of the sidebar (above your name). Options:

• Full backup (JSON) — downloads everything in one file you can keep safe or re-import later.
• Backup incl. passwords — same, but decrypts passwords into the file (with a warning — keep that file secure).
• Per-module CSV — export Clients, Invoices, Expenses, Time, Contracts, Projects, or Meetings as a spreadsheet for Excel.

Make backups a habit. Your data lives only in your WordPress database, so a regular export is your safety net.

• All data is stored in your own WordPress database — nothing is sent to FreelanceHub or any third party.
• The only external connection is to your chosen AI provider, and only when you explicitly ask the AI Assistant something — and only the text you submit is sent.
• AI API keys and the vault PIN are stored server-side only, never exposed to the browser.
• Stored passwords are encrypted with AES-256.
• Logged-out visitors are redirected to login — your workspace is never public.

Something won’t save, or a list won’t load

This is almost always a stale browser cache or session. First, hard-refresh with Ctrl+Shift+R / Cmd+Shift+R. If you use a caching plugin, clear its cache. Then confirm you’re still logged into WordPress.

Check your connection status

Visit /wp-json/freelancehub/v1/status on your site while logged in. You should see logged_in: true and all tables marked ok. If logged_in is false, log out and back in.

The AI Assistant returns an error

Check that your API key is entered correctly in the AI Assistant settings, that the key is active in your provider’s console, and that your provider account has credit.

Invoice PDF doesn’t open

The PDF opens in a new browser tab. If nothing happens, your browser is blocking pop-ups — allow pop-ups for your site and try again.

Do I need the AI features to use FreelanceHub?

No. Every module works without an AI key. The AI Assistant is an optional extra you enable by adding your own key.

Can I use this on my phone?

Yes. The interface is fully responsive. On mobile, a collapsible sidebar (tap the panel icon top-left) gives you the full navigation.

Where is my data stored?

In your WordPress database, on your own hosting. You can export it any time from Backup & Export.

Is my client data private?

Yes. The workspace requires login and is never shown to public visitors.

Does the Tax module file my taxes or give tax advice?

No. It’s a planning aid that estimates your tax from your own records and the rates you set, helps you set money aside, and tracks deadlines. The figures are estimates and are labelled as such. Always confirm your actual liability and filing requirements with a qualified accountant for your country.

Can I use the Tax module outside the US?

Yes. It’s country-neutral. You set your own currency, tax rate (or your own tax brackets), set-aside percentage, and filing dates, so it works wherever you are. FreelanceHub doesn’t ship any country’s tax tables — you supply the numbers and it does the maths, which keeps it accurate and never out of date.

FreelanceHub is a business-management tool. For legal, tax, or financial decisions, consult a qualified professional.

Creative Intelligence OS ships in three editions. They share an identical codebase and data structure, so upgrading is a simple in-place reinstall that preserves everything.

A workspace is one brand — its own products, voice, angles, integrations, and creative library. A managing user (any WordPress administrator or editor) can change settings and generate creatives; everyone else has full read-only visibility but cannot make changes.

Each edition is a separate download with its tier built in. The folder name is identical across editions, so installing a higher tier over a lower one upgrades in place and keeps all your data, creatives, and settings.

1

Upload the theme

In WordPress admin go to Appearance → Themes → Add New → Upload Theme. Choose your edition’s zip (for example creative-intelligence-os-pro.zip) and click Install Now.

2

Activate the theme

Click Activate. On activation the theme registers its custom content types, creates the rewrite rules for its app screens, and sets up everything it needs — no pages to create.

3

Visit your site

Open your site’s front page. You’ll be taken straight into the app — the license screen first, then the setup wizard.

Zero page setup. Unlike most themes, you never create or assign pages. The dashboard, wizard, library, and every other screen are delivered automatically by the theme’s routing. Your home page becomes the app.

A fresh install shows a clean activation screen before anything else. Enter the license key from your purchase (format CIO-XXXX-XXXX-XXXX-XXXX) and click Activate. The key locks to your domain.

• One key, one domain. Each key activates a set number of domains (usually one). Moving to a new domain? Open Workspace → License on the old site, click Deactivate to free the slot, then activate on the new domain.
• Edition-matched. A Pro key only activates a Pro install. If they don’t match, the screen tells you which edition your key is for.
• Offline-tolerant. The license re-checks weekly in the background. If the license server is briefly unreachable, your install keeps working for 21 days, so an outage never locks you out.

Only a WordPress administrator can activate or deactivate a license. Keep your key somewhere safe; if you lose it, contact the seller with your purchase email.

After activation, if no workspace exists yet, you land on the Setup Wizard. Complete it once to create your first brand. From then on, your front page opens the Dashboard, and the wizard is only used to add additional workspaces (on Pro and Unlimited).

A workspace is a complete, self-contained brand environment. Everything is scoped to the active workspace: its products, brand documents, angles, zones, output recipes, integrations, AI assignments, and creative library. Switch between workspaces using the brand switcher at the top of the sidebar.

Workspace configuration lives under Settings → Workspace, organized into sections: Brand, Products & Services, Angles & Zones, Output, Data & Export, AI Assignments, License, and a Danger zone for deletion. Changes are saved with the Save changes bar, which appears the moment you edit anything.

The wizard walks you through creating a workspace in seven steps. Each step is optional to perfect later — you can change everything afterward in Workspace Settings.

1. Brand — name, website, industry, market, description.
2. Products & Services — what you sell. Add products manually or import them from Shopify in one click. Each carries a name, type, description, and images.
3. Angles & Zones — the emotional entry points and intensity zones your brand uses.
4. Output — choose which creative categories you produce, then configure each one’s types, formats, and output recipe.
5. Brand Documents — upload the materials that teach the AI your voice (avatar, voice audit, guidelines, winning ads, and more).
6. Data Sources & Export — select the platforms you use, to be connected later in Integrations.
7. AI Assignments — choose which AI handles each task.

Shopify import needs no account access. Enter your store’s website in the Brand step, then click Import from Shopify in the Products step. The theme reads your public product feed and brings in names, descriptions, and images automatically.

An output recipe defines exactly what one generation produces for a category. You toggle components on or off and set how many of each. The recipe drives both the AI’s output schema and the tabs you see on a finished creative.

Available components include visual briefs, headlines, short copies, story scripts, video scripts, hooks, CTA variations, and carousel frames. Each category ships with proven defaults you can adjust. For story and video scripts you also choose a structure — for example, independent scripts versus several hooks sharing one body.

Brand Brain is where you upload the documents that teach the AI your brand. The more it has, the sharper its avatars, angles, and copy. Each document type shows whether you’ve uploaded it, with a readiness meter at the top.

Document types include Customer Avatar, Customer Voice Audit, Survey Responses, Product Documentation, Brand Guidelines, Winning Ads, Losing Ads, and Competitor Research. Upload what you have; the AI uses whatever’s present and works fine with a subset.

5
Brand Brain Readiness — Strong
Upload missing documents to sharpen avatars and angle discovery.
5
UPLOADED
3
MISSING

CORE DOCUMENTS

Customer Avatar
Avatar_V8.docx · 124 KB

Customer Voice Audit
Voice_Audit.pdf · 87 KB

PRODUCT & BRAND

Winning Ads
Missing — upload to mirror winners

↑ Upload

Competitor Research
Missing
Brand Brain — a readiness meter and real upload state per document type.

Brand Brain reflects the real documents uploaded for the active workspace. A new workspace starts empty and fills in as you add materials.

Angles are the emotional or strategic entry points of an ad — for example “Wrong Shade / Size / Fit,” “Partner Noticed,” or “Sceptic Proven Wrong.” Choose from the standard set, and add your own custom angles with descriptions.

Zones are emotional intensity quadrants (Z1–Z4, from low-positive to high-negative) that tune how strongly a creative leans into its angle. Together, angle and zone give every creative a precise emotional coordinate.

The Create Creative screen is where a creative is born. You choose a category, optionally a product, an angle (or let the AI pick), formats, and optionally a reference image. Then you click Analyse.

BRIEF
CREATIVE CATEGORY

Native

Static

Video
PRODUCT

Areliaa Signature Lipstick
REFERENCE (optional)

Upload a winning ad to mirror

Analyse

⌕
Ready to analyse
The AI will tell you what it plans
to create before generating.
Choose category, product, and an optional reference, then Analyse.

This is the discipline at the heart of the system. Before any copy or visual is produced, the AI returns its analysis: the type, angle, zone, target avatar, and dominant story moment it intends to use, each with its reasoning. You review it, adjust your inputs if needed, and only then approve. Generation happens after approval — never before.

When you upload a reference image, the system treats it as a winning ad you want to replicate. The analysis includes a forensic blueprint of the reference: its exact layout, composition, text placement, colour direction, and mood. That blueprint is then enforced during generation so every brief mirrors the reference’s design — changing only your brand content (your product, avatar, claims, and offer).

Reference mirroring means you can take an ad that’s already proven to convert and reproduce its winning structure with your own product and message, instead of guessing at a new design.

Each brief is one ad. From its card you generate visuals in the formats you need. The system sends your real product image as a reference so your actual product appears in the visual, not an invented one. Generate a master ratio first, then derive the other ratios from it — they reproduce the same design, recomposed for each aspect ratio.

• Exact ratios. Visuals are produced at true 1:1, 4:5, 9:16, and 16:9 — center-cropped to the exact ratio with a safe margin so nothing important is clipped.
• Real downloads. Download buttons save an actual file to your device with a sensible filename; they never navigate away and lose your work.
• Editable briefs. If a brief needs a small tweak, edit it in place before generating — no need to regenerate the whole creative.

Every creative you generate is saved automatically as a Draft the moment it’s produced — nothing is ever lost to a closed tab or back button. The library lists all creatives for the active workspace with their status, type, angle, zone, and visual thumbnails.

From a creative’s detail view you can rename it, approve a draft (or move an approved one back to draft), duplicate it, delete it, export it, and generate additional visuals per brief. Recipe-driven tabs show exactly the components that creative produced.

All

Static

STATIC · JUN 13

Approved
Before/After · Offer · Z2

STATIC FAMILY · CREATED JUN 13
Before/After · Offer · Z2

Approved
4 ads · 3 headlines · 3 copies

Overview
Design Briefs (4)
Headlines (3)

TYPE
Before/After
The Creative Library — list with status pills and thumbnails, detail with recipe-driven tabs.

You bring your own API keys — Creative Intelligence OS never charges per generation. Keys are stored server-side in your WordPress database and are never exposed to the browser. You assign which provider handles each of the four AI tasks under Workspace → AI Assignments, so you control the speed, quality, and cost trade-off for every task independently.

The four AI tasks

Every supported provider

Mix and match. You might use Claude for copy, Gemini for analysis, Ideogram for images, and Seedance for video — all in the same workspace. Only the providers you assign to a task appear in Integrations for credential entry, keeping that screen focused on what you actually use.

AI Assignments

Script generation
Writes all ad copy — scripts, headlines, briefs.

Anthropic (Claude)

Angle analysis
Reads brand docs to discover angles.

Google Gemini

Image generation
Generates visuals from approved briefs.

Ideogram

Video generation
Generates video from approved scripts.

Seedance

AI Assignments — one provider per task, chosen independently.

Integrations is your single credentials hub. Every provider and platform you’ve enabled — AI providers, data sources, and export tools — appears here as a card you expand to enter its API key or token. Each card includes a direct “Get your API key” link to the exact page on that provider’s site where the key is generated, so you’re never hunting through dashboards.

The screen only shows what you actually use: the AI providers you’ve assigned to tasks, the data sources you selected in the wizard, and the export tools you enabled. Saved keys are stored server-side and never sent to the browser.

Integrations

AI PROVIDERS
DATA SOURCES
EXPORT TOOLS

Anthropic (Claude)

Ideogram

Seedance

Trustpilot

Shopify

Klaviyo

Trello

Notion

Asana

↗ Each card links directly to where you generate that provider’s API key.
Integrations — AI providers, data sources, and export tools, each with a direct key link. Green dot = connected.

Data sources are the platforms Creative Intelligence OS can pull real customer signal from to sharpen angle discovery and avatar accuracy. You select which ones you use in the wizard (or under Workspace → Data & Export), then connect them in Integrations. Connected sources feed the Brand Brain.

Selecting a source is just a selection — no credentials are needed at that point. You enter API keys later in Integrations, and only your selected sources appear there.

Finished creatives don’t have to live only in the library. Export sends a creative — or just the parts you choose — straight into the project-management tool your team already uses, so briefs become actionable cards and tasks.

Choosing what to include

When you export, you pick the destination and toggle exactly which parts of the creative to include — headlines, ad copies, image briefs, the creative ID, and angle metadata. Toggle anything off you don’t want sent; the rest goes across cleanly.

Export creative
×
DESTINATION

T
Trello

N
Notion

A
Asana
INCLUDE IN EXPORT

Headlines

Ad copies

Image briefs

Creative ID

Angle metadata

Export to Trello
The export modal — pick a destination, toggle exactly what to include, and send.

Your products are the subjects of your creatives. Each has a name, a type (physical product or service), a description the AI quotes, and images that become generation inputs so your real product appears in visuals. Manage them in the wizard or under Workspace → Products & Services, including one-click Shopify import.

When you create a creative, you select which product it’s for (single-product brands auto-select). The product’s name, description, and primary image flow into the analysis, the generated copy, and the image generation as a faithful reference.

Permissions follow WordPress roles. Administrators and editors are managing users — they can change settings and generate creatives. All other roles have full read-only access: they see every workspace, creative, and setting but cannot make changes. This lets you give clients or teammates visibility without risk.

Workspace limits are enforced by edition: Basic allows one workspace, Pro three, Unlimited any number. Read-only users are always unlimited.

A light/dark toggle lives in the sidebar footer. Your choice is remembered across sessions and applied instantly with no flash on reload. Dark mode is a full, considered theme — surfaces, text, borders, buttons, inputs, and hover states are all tuned for contrast and legibility.

The app shows the activation screen and won’t let me in

Your license isn’t active for this domain. Enter your key, or if you’ve moved domains, deactivate on the old one first (Workspace → License) to free the slot.

Image generation says a provider isn’t available

Confirm you’ve saved that provider’s API key in Integrations and assigned it to Image generation under Workspace → AI Assignments. For Gemini, ensure your key has access to the image models at aistudio.google.com.

A visual downloads as a page instead of a file

This is handled automatically — download buttons fetch the image and save a real file. If a download ever fails, it opens in a new tab so you never lose your work.

A style change doesn’t appear

Hard-refresh your browser (Ctrl/Cmd+Shift+R) and clear any caching plugin. The theme bumps its asset version each release to bust caches.

I created a new workspace but see old data

Make sure the brand switcher (top of the sidebar) is set to the new workspace. All data is scoped to the active workspace.

Do I need to create any WordPress pages?

No. Every screen is delivered automatically by the theme. Install, activate, and your front page becomes the app.

Does my data leave my server?

Only the text and images needed for a generation are sent to the AI provider you configured. Everything else — brands, products, creatives, documents — stays in your WordPress database.

Can I move my license to a new site?

Yes. Deactivate on the old domain (Workspace → License), then activate on the new one.

What happens if I upgrade from Basic to Pro?

Install the Pro zip over your existing theme. The folder name is identical, so it upgrades in place and keeps all your data; only the workspace limit increases.

Will the AI invent product details?

No — it’s instructed to use your product’s exact name and description, and your real product image is used as a visual reference. Accuracy of your product description matters because the AI quotes it.

Is there a per-creative fee?

Not from the theme. You only pay your AI providers for the API usage of the creatives you generate.

Can it generate video, not just images?

Yes. Assign Seedance to the Video generation task, and approved video scripts can be turned into video.

Can I push creatives into my project tool?

Yes. Export a creative to Trello, Notion, Asana, ClickUp, or Monday — choosing exactly which parts (headlines, copies, briefs, IDs, metadata) to include — or copy them to the clipboard.

Which data sources can feed the AI?

Trustpilot, Loox, Judge.me, Help Scout, Gorgias, Shopify, Klaviyo, and Meta Ads. Select the ones you use and connect them in Integrations.

Beautiful Product Offers for WooCommerce (WooBPO) lets you present a group of products as a single, attractive offer on a product page — pre-built bundles, build-your-own kits, and upsell stacks. Shoppers pick the items they want, see the price update live, and add everything to the cart in one click.

The free plugin handles the offer mechanics and presentation. Pro adds the things that turn a nice-looking offer into a higher-revenue one: discounts that are actually enforced at checkout, multi-variant selection, full styling, trust/persuasion content, analytics, and one-click starter templates.

• WordPress (tested up to 7.0)
• WooCommerce (tested up to 10.9.1)
• PHP 7.2+ (Pro: 7.4+)

If WooCommerce is not active, the plugin shows an admin notice and stays dormant rather than causing errors.

1. In wp-admin go to Plugins → Add New → Upload Plugin.
2. Upload beautiful-product-offers-for-woocommerce.zip and click Install Now, then Activate.
3. A new Woo BPO menu appears in the admin sidebar.

If you already run the version from WordPress.org, upload this zip and choose Replace current with uploaded — it updates in place. Do not keep two copies of the plugin active in different folders.

Pro is unlocked simply by being installed — there is no licence key to enter.

1. Make sure the free plugin is installed and active first.
2. Go to Plugins → Add New → Upload Plugin, upload bpo-woo-pro.zip, Install Now, then Activate.
3. The Pro features switch on automatically. The Styling tab unlocks, and Analytics and Templates appear under the Woo BPO menu.

To move Pro to another site, deactivate it on the first site and activate it on the second. Because the unlock is “the plugin is active,” keep the file only on sites you own.

WooBPO adds a custom WooCommerce product type called Woo BPO. A Woo BPO product is an offer — a wrapper that references other products in your catalogue (the “lines” of the offer).

• The offer product is what the customer lands on. Its page shows the offer box.
• Each line points to a real product you already sell (simple or variable).
• When the customer adds the offer to the cart, WooBPO adds the selected line products to the cart and (by default) removes the wrapper, so the cart contains the real products.

This means your inventory, taxes, and reporting all run on your real products — the offer is just the presentation and the rules around them.

1. Create or identify the products you want to bundle (e.g., three simple products).
2. Go to Products → Add New.
3. Give the offer a name (the page title customers see, e.g. The Starter Set).
4. In the Product data dropdown, choose Woo BPO.
5. Open the Woo BPO tab in the Product data panel and add your products as lines.
6. Set a price on the offer so it is purchasable.
7. Publish, then click View product to see the offer box on the storefront.

The fastest way to see a complete, polished example is Pro → Woo BPO → Templates, which builds a finished offer for you in one click.

Inside the Woo BPO product-data tab you add one line per product. Each line has:

• Product — the catalogue product this line represents (simple or variable).
• Quantity — default quantity added for this line.
• Tag — a short badge shown on the line, e.g. 50% OFF or 2 + 1 Free.
• Offer text — the line’s call to action.
• Below-offer text — a small line under the offer text, e.g. Best Choice or Only 80 left.
• Above-variation text — helper text shown above a variable product’s options, e.g. Choose your colors.

The order of lines is the order shown on the page. A line can point to a variable product; the customer then picks a variation as part of the offer.

Found under Woo BPO → Settings. These apply to every offer unless a specific offer overrides them.

General tab

• Offer Position — show the offer box above or below the Add to Cart button.
• Offer Type — Multiple Selections (checkboxes) or Single Selection (radio). Overridable per offer.
• Product Title On-Click Action — nothing, open in new tab, or same tab.
• Show Thumbnail / Variation Change Image / Show Short Description / Show Price / Price Change — presentation toggles.
• Custom Price Selector — CSS selector for themes that don’t use the default .price.
• Add Main Product in Cart — keep the wrapper in the cart. Leave off for most bundles.
• Trust Badge (Pro) — upload a badge image under the Add to Cart button.

Labels tab

Shop/archive button labels for purchasable and unavailable offers.

Search tab

Controls the admin product search: search limit, by ID/SKU, allow same product, exact/sentence matching.

Styling tab (Pro)

In the free version this tab is visible but locked — you can preview the controls; clicking one takes you to the Pro page.

Each Woo BPO offer can override the global defaults from its own Woo BPO product-data tab — selection type (single/multiple), offer position, the offer’s lines, the discount on each line (Pro), and the offer’s Design and Layout (Pro). Anything not set on the offer falls back to the global Settings.

Free plugin: the tag and offer text you write (e.g. “50% OFF”) are presentation. The cart charges each line product’s normal price. The free plugin does not change what the customer actually pays — if you advertise a discount you must also set that price on the product yourself.

Pro plugin: the Enforced discounts feature closes that gap. The discount you configure on a line is applied to that line’s items in the cart, so the price the customer pays matches the offer you advertised — without you maintaining sale prices by hand.

When the offer is added to the cart, the selected line products are added and (unless Add Main Product in Cart is on) the wrapper is removed, so the cart shows the real products at the enforced prices.

Woo BPO → Settings → Styling. With Pro active, every control here applies to your live shop.

• Design — Basic / Rounded / Rectangle treatments for the offer box.
• Layout — Horizontal or Vertical arrangement of lines.
• Font weight and a full set of colours — background, borders, box shadow, hover/active states, titles, prices, sale prices, variation selectors, tags, offer text, and the Add to Cart button (normal and hover).

Styling is scoped to WooBPO’s own elements and applied with high priority, so it works consistently across themes without leaking into the rest of your shop. Each offer can override the global Design and Layout from its own product-data tab.

Configured per line inside the offer’s Woo BPO tab. Three types:

Percentage

Takes a percent off each unit of the line. Example: 50% off a $40.50 pack → charged $20.25.

Fixed price (per unit)

Sets an exact per-unit price regardless of the product’s normal price.

BOGO / “Buy X get Y free”

Works across all units of the line — including across different variants of a variable line. You set Buy and Get values: Buy 2, Get 1 on a 3-unit line makes the cheapest unit in each cycle free.

Enforced prices are applied when cart totals are calculated and are based on the product’s stored original price, so recalculations stay correct.

For a line that points to a variable product, set the number of units for that line (e.g. 3). On the storefront the customer gets that many variation pickers — Choose Color 1 / 2 / 3 — and all of them are added in a single click.

This powers offers like “Buy 3, mix any colours, get one free.” The picker reuses the product’s own variation options, validates that every pick is in stock, and appends the chosen variations to the offer when the customer adds to cart.

Lines whose variations load over AJAX (very large variable products) are skipped by the multi-unit picker; use it on products whose variations are available on the page.

• Trust badge — upload an image (General tab) shown under the Add to Cart button.
• Custom content under Add to Cart — per-offer HTML/shortcode area for guarantees, urgency, payment icons, secure-checkout rows.
• Title replacement — replace the offer’s plain title with custom HTML/shortcodes: a testimonial quote, a styled product name, a feature line, and a “what’s inside” swatch row.

Together these let a single offer page look like a purpose-built landing page.

Woo BPO → Analytics. A per-offer performance table:

• Impressions — times the offer was shown on a product page (counted once per visit).
• Orders — orders that contained items added through this offer.
• Conv. rate — orders ÷ impressions.
• Units — units sold through the offer.
• Revenue — revenue attributed to the offer.
• AOV — average order value for the offer (revenue ÷ orders).

Items added through an offer are tagged and carried through to the order, so attribution is independent of which discount (if any) was used. A Reset data button clears the figures.

Woo BPO → Templates. A gallery of ready-made offers you can install in one click — the fastest way to see Pro working and a strong starting point for your own offers.

• BOGO — Buy 2 Get 1 Free: a single-selection offer with a half-price single pack vs. a multi-variant “2 + 1 Free” pick-your-colours bundle, plus testimonial, urgency and secure-checkout content.
• Composite — Build a Kit: a multi-select “build your routine” bundle where every item added is discounted.
• Digital — Downloadable Bundle: three virtual, downloadable products at a bundle price, with a working sample download.

Each template creates demo products and a fully configured offer, sets only per-offer options (no global settings are changed), and can be removed again from the same screen.

A simple bundle (buy these 3 together)

1. New product → type Woo BPO, multiple selection.
2. Add three lines, quantity 1 each.
3. (Pro) Give each line a percentage discount and a “Save X%” tag.
4. Turn Add Main Product in Cart off.

A “2 + 1 free” on one product

1. New product → type Woo BPO, single selection.
2. Add one line pointing to the product, with tag 2 + 1 Free.
3. (Pro) Set the line to BOGO Buy 2 Get 1; if it’s variable, set units to 3 for mix-and-match.

A tripwire upsell under the Add to Cart button

1. Set Offer Position to below ATC.
2. Add one or two lines with a strong tag and offer text.
3. (Pro) Add urgency in the custom under-ATC content.

• WooCommerce HPOS (High-Performance Order Storage) and cart/checkout blocks are declared compatible by Pro.
• Themes: styling targets WooBPO’s own classes, so it’s resilient to theme markup. If your theme uses a non-standard price selector, set Custom Price Selector in General settings.
• Translations: the text domain is woo-bpo; translation files load from the plugin’s languages folder.

The plugin caused a fatal error on activation. Make sure you don’t have two copies of the free plugin active in different folders. Two copies declare the same code and collide. Keep one.

Advertised discount doesn’t match the cart. In the free plugin, tags are display-only. Use Pro’s Enforced discounts, or set sale prices on the products yourself.

Styling changes don’t show. Confirm Pro is active (the Styling tab is unlocked). Clear any page/CDN cache.

A template didn’t create products. Confirm WooCommerce is active and you have permission to manage products, then try again from Woo BPO → Templates.

The multi-variant picker doesn’t appear. It only shows when a line’s units is greater than 1 and the variable product’s variations are available on the page (not AJAX-only).

Do I need a licence key for Pro? No. Installing and activating the Pro plugin unlocks everything.

Will updating the free plugin wipe my offers and settings? No. Offers are products and settings live in the database; updating the plugin files doesn’t touch them.

Can one offer use single selection while another uses multiple? Yes — set the Selection type per offer; it overrides the global default.

Does the offer wrapper get charged to the customer? Only if Add Main Product in Cart is on. Otherwise the wrapper is removed and only the real line products are charged.

Where do I get help or report a problem? Visit the product page: gnkwebapps.com/product/woobpo.

Precios turns a WordPress site into a supermarket price-comparison app. Shoppers search a product, see what every store charges, build a list, and find out which supermarket is cheapest for the whole basket.

It is the system running live at precios.com.do, which compares seven Dominican chains nightly. The theme you install is the same codebase — configured for your country instead of the Dominican Republic.

What it is not

Precios does not come with scrapers for your stores. It cannot, honestly: a scraper is written against one specific website’s markup, so Dominican scrapers only fit Dominican stores. Precios gives you the catalog, the comparison engine, the storefront and a secure way to get prices in. Where those prices come from is your decision — by hand, by CSV, or by a scraper you point at the Push Sync endpoint.

Three ways to keep prices current

• By hand or CSV — included in every edition. Fine for a few hundred products updated weekly.
• Push Sync — you run a scraper anywhere, it posts prices to your site. Included in the Push edition.
• Pull Sync — we run the scrapers and your site pulls a hosted feed. Coming soon.

• WordPress 6.0 or newer
• PHP 7.4 or newer (8.x recommended)
• Any normal shared or managed host — no special extensions
• HTTPS, if you plan to use Push Sync (the shared secret travels in a header)

There is no external database and no third-party service. Products live in your own WordPress database as a custom post type. Nothing leaves your server unless you switch on the optional AI search.

1. In wp-admin go to Appearance → Themes → Add New → Upload Theme.
2. Upload the zip you were sent and click Install Now, then Activate.
3. A Precios Settings page appears under Settings.

If you bought a Sync edition

The Theme + Push Sync and Theme + Pull Sync zips carry their plugin inside them. After activating the theme a notice offers to install it in one click. You do not download the plugin separately.

Install one theme only. The three editions are the same theme with different names — activating two would just confuse WordPress about which is live.

The fastest useful setup, in order.

1. Settings → Precios Settings. Set Country, Language, Locale and Currency symbol. Language drives every label on the site; the currency symbol is printed in front of prices exactly as you type it.
2. Still on that page, add your stores under the store repeater — see Setting up your stores. Do this before entering any prices.
3. Optional: click Import Precios.do demo data to load 12 categories and 100+ Dominican products. Useful for seeing a populated site before you build your own catalog. Safe to run more than once.
4. Products → Import / Export → Download CSV. You now have a spreadsheet shaped exactly like your catalog.
5. Fill it in, upload it back, and your site is live.

If you imported the demo, delete the demo products before launch — they are Dominican prices and will look wrong in another country.

Three pieces, and it helps to understand how they fit before you start.

Stores

Defined once in Settings → Precios Settings. Each has a display Name, an ID (slug), a Color, and a Bulk flag. Stores are global — they are not per-product.

Products

A custom post type. One product is one comparable item — Mahatma rice, 5 lb. Not “rice”. If two supermarkets sell different sizes, those are two products, because a shopper cannot compare them directly.

Prices

Stored on the product, one price per store, in the Prices by store box. A product does not need a price at every store; a missing price simply means that store does not carry it, and the comparison accounts for that.

The rule that matters

Everything hangs off the store ID, not the name. Prices are saved under the ID. Rename a store freely — SuperMart to SuperMart Express — and nothing breaks. Change its ID after prices exist and every price saved under the old ID is orphaned. Settle your IDs first.

Settings → Precios Settings, then Add store for each supermarket.

The fields

• Name — what shoppers see. Change any time.
• ID (slug) — lowercase, no spaces (lasirena, nacional). This is the key prices are stored under, and what a CSV column or a Push payload refers to. Decide it once.
• Color — used for the store’s chip in results. Pick something close to the real brand; it makes scanning results much faster.
• Bulk — tick for warehouse clubs. See Bulk stores.

How many?

Enough to be worth the visit, few enough to keep current. Five stores you update nightly beats twelve you update monthly — a stale price is worse than a missing store, because a shopper acts on it and finds out you were wrong.

Categories

Under Products → Categories. Keep them shallow and shopper-shaped — Rice & Grains, Dairy, Cleaning. People browse the way they shop, not the way a supermarket’s internal taxonomy is organised.

Adding a product

Products → Add New. The title is the product name. Two boxes matter:

• Product details — brand, unit (5 lb, 1 L), emoji, and an optional price-drop percentage that feeds the deals page.
• Prices by store — one row per store you configured, with a price and an availability toggle.

Naming, and why it matters more than it looks

Put the size in the unit field, not the title. Mahatma Rice + unit 5 lb, not Mahatma Rice 5 lb. Consistent naming is what makes CSV round-trips and scraper matching work later. It is very cheap to fix now and very annoying to fix at 400 products.

Products → Import / Export. This is the workflow most operators live in.

Export first, always

Click Download CSV. You get one row per product and a price column per store, already shaped correctly. Editing that file is far safer than authoring one from scratch.

The columns

id, name, brand, category, unit, emoji, drop, popularity, price_<store_id> …

• id — leave it alone on existing rows; that is what makes an import an update rather than a duplicate. Leave it blank to create a new product.
• price_<store_id> — one column per store, named after the store ID. price_lasirena, price_nacional.
• Blank a price to mark that product unavailable at that store. Blank is not zero — zero means “free”.

Import

Keep the header row, upload, and Precios reports how many rows were created, updated and skipped. Skipped rows usually mean a missing required column or an id that no longer exists.

Import is safe to re-run. It updates by id rather than duplicating.

This is the feature people come for, so it is worth knowing exactly what it claims.

Per product

The cheapest store for that item is highlighted. Straightforward.

Per basket

Precios totals the whole list at each store and shows which single store is cheapest overall, and what you would save versus the most expensive. It also shows the “cherry-picked” total — buying each item wherever it is cheapest — which is usually lower still, but means several trips.

Partial baskets

If a store does not carry every item on the list, Precios says so — carries 8 of 10 — rather than quietly comparing an 8-item total against a 10-item one. A comparison that ignores missing items is not a comparison; it just flatters whichever store has the smallest catalog.

The Bulk flag on a store exists because warehouse clubs are not directly comparable to a normal supermarket.

The problem it solves

A 12 kg sack at a warehouse club is cheaper per kilo than a 5 lb bag at a regular store — but it is not the same purchase. A shopper who wanted 5 lb of rice cannot act on that price. Presenting it as “cheapest” is technically true and practically misleading.

What the flag does

Bulk stores are marked in the UI so shoppers can see the comparison is not like-for-like.

Membership stores

If a store’s prices are only visible or only purchasable with a paid membership, think hard before including it. Showing a price most of your visitors cannot obtain undermines the one thing your site is for. Fewer honest stores beat more stores where one is misleading.

Settings → Precios Settings → AI search (Anthropic). Off by default.

What it does

When a shopper searches for something not in your catalog, the AI can offer an estimated price rather than an empty result.

What it does not do

The AI never sets the prices in your catalog. Your prices are yours — entered by hand, CSV or Push. AI search is a fallback for the gap, and estimates are presented as estimates.

Setup

1. Get an API key from the Anthropic Console.
2. Paste it into Anthropic API key, pick a Model, tick Enable AI search.

Cost and privacy

You bring your own key and you are billed directly by Anthropic. The key is stored in your database and used only server-side — it is never sent to the browser. Nothing is sent anywhere while the feature is off.

Settings → Precios Ads. Three slots, each a rotating set of images you upload to the media library.

• Home hero — 728×90 desktop, 320×100 mobile
• Product sidebar — 300×250
• List sidebar — 300×600 desktop, 320×100 mobile

Per image

A desktop image, an optional separate mobile image, an optional click URL, and alt text. If you give no mobile image the desktop one is used.

Empty slots

A slot with no images renders nothing at all — no placeholder, no gap. A brand-new install shows no advertising until you add some, so you can launch before you have sold anything.

Ads are plain images you upload and manage. There is no ad network, no tracking script, and no third party watching your visitors.

Settings → Precios Marketing. Both off by default.

Mobile app band

A strip promoting your iOS/Android app, with store links. Leave it off until you actually have an app — an install shouldn’t advertise something that doesn’t exist.

Advertise with us

A band and contact form for businesses wanting to buy ad space. Submissions are emailed to the address you set, with Reply-To pointing at the sender so you can reply directly.

The form has a hidden honeypot field and is rate-limited to one submission per IP per minute. That stops casual bots without putting a captcha in front of a real customer.

Settings → Precios Marketing → Footer credit.

Precios ships with no branding of its own. There is no “powered by” line in the footer, and nothing links back to where you bought it. That is deliberate: you bought a white-label product, so a fresh install is yours.

Adding your own

1. Tick Show a credit line in the footer.
2. Enter your company in Name.
3. Optionally add a Link. Without one the name renders as plain text.

Leave the name blank and no credit appears even when enabled, so the footer can never show a dangling “Made by”.

Included in the Theme + Push Sync edition. It gives your site a secure endpoint that a scraper you run can post prices to, on whatever schedule you like.

The shape of it

Your scraper runs anywhere — a cheap VPS, a laptop, a GitHub Action. It fetches prices however it likes, then POSTs them to your site. WordPress authenticates the request, matches products, and writes the prices.

Setup

1. Activate the plugin (the theme offers to install it for you).
2. Open Settings → Precios Sync Push and copy the generated secret.
3. Point your scraper at https://yoursite.com/wp-json/precios-push/v1/prices, sending the secret in an X-Precios-Secret header.

The page shows the endpoint, the secret, a payload example, and the timestamp and count of the last successful sync — which is the first place to look when something seems stale.

What Push does not include

Scrapers for your stores. The plugin ships a Python skeleton with the HTTP part written; the fetching logic for your particular supermarkets is yours to write.

POST JSON to /wp-json/precios-push/v1/prices with your secret in the X-Precios-Secret header.

{
  "updated_at": "2026-07-14T06:00:00Z",
  "products": [
    {
      "match": { "id": 123 },
      "prices": {
        "lasirena": { "price": 185, "available": true },
        "nacional": { "price": 195, "available": true },
        "bravo":    { "price": 0,   "available": false }
      },
      "drop": 4
    }
  ]
}

Field by field

• match — {"id": 123} is the reliable form: the WordPress product ID, which you can read from the CSV export. {"name": "...", "brand": "..."} also works but depends on exact title matching.
• prices — keyed by store ID, exactly as configured in Settings. Unknown IDs are skipped silently, so a typo fails quietly rather than loudly. Check your IDs.
• drop — optional percentage, feeds the deals page.

The behaviour worth building on

Only the stores present in a product’s prices object are touched. Everything else keeps its existing value. That means you can update one store at a time without wiping the others — and if one store fails to scrape tonight, you can simply leave it out and yesterday’s prices remain.

Responses

• 200 {"updated": 42} — number of products written.
• 401 — missing or wrong X-Precios-Secret.
• 400 — no products array in the body.

The hard part of price comparison is not fetching a page. It is not publishing a wrong number. These are the rules that matter, learned running precios.com.do against seven chains.

1. Stale beats wrong

Your site’s only real promise is that the price is right. A missing price is recoverable — a shopper checks elsewhere. A wrong price sends someone across town. When in doubt, publish nothing and keep yesterday’s number.

2. Hold prices that move implausibly

A 90% overnight drop is far more likely to be your scraper reading the wrong element than a real sale. Compare against yesterday, and hold anything that moves more than ~50% down or ~100% up for a human to look at.

3. Skip a bad store, don’t push it half-empty

If a store returns 12 products when it usually returns 400, its site changed. Leave that store out of the payload entirely — the endpoint only touches stores present in it, so its existing prices survive untouched. Pushing the 12 would silently mark 388 products as unavailable.

4. Abort a broken run

If nothing scraped properly, push nothing. A failed run should change nothing at all.

5. Never guess at units

Some store APIs quote prices in cents. 18500 might be $185.00 — or a real $18,500 appliance. Prove which by checking a known product against the live site, and hard-code the answer per store. Never infer it from how big the number looks; a 100× error looks perfectly plausible in a database.

6. Log which method worked

If you scrape a store three ways — structured data, its private JSON API, then HTML selectors — record which one fired. A store quietly falling back to fragile HTML scraping is your early warning that its site changed, before the prices go wrong.

Theme + Pull Sync is the edition for operators who do not want to run a scraper at all. We run them; your site pulls a hosted feed on a schedule you choose.

Status

Not launched yet. The tier is listed with a waitlist rather than a buy button — we would rather show you it is coming than sell you something that doesn’t exist. Early subscribers lock in a reduced rate.

How it will work

Your site holds a feed key. WP-Cron fetches the feed on your schedule — daily, twice-daily or hourly — and applies prices through the same matching logic Push uses. No scraper on your end, no server to maintain.

Coverage

The Dominican Republic feed launches first, since that is the market we operate in. Other countries follow demand — if you want yours covered, join the waitlist and say so.

Prices show for one store but not another

Almost always a store ID mismatch. Prices are stored under the ID, so if you changed one after entering prices, the old ones are orphaned. Compare the ID in Settings → Precios Settings against your CSV column name or Push payload key.

A CSV import skipped rows

Either a required column is missing from the header, or an id refers to a product that no longer exists. Re-export, edit that file, and re-import.

Push returns 401

The X-Precios-Secret header is missing or does not match. Copy it again from Settings → Precios Sync Push — a trailing space when pasting is the usual culprit.

Push returns 200 but nothing changed

The request authenticated but nothing matched. Check that match.id values are real product IDs, and that the keys in prices are exactly your store IDs. Unknown store IDs are skipped silently by design, so a typo produces exactly this symptom.

The site looks unstyled after updating

A cached stylesheet. Hard-refresh with Ctrl+Shift+R (Cmd+Shift+R on Mac), and clear any caching plugin or CDN.

Demo products still showing

The demo import creates real products. Delete them under Products before launch — Dominican prices in another country will look broken.

Each Precios edition is a one-time purchase (Pull Sync excepted, which is a subscription because it includes a hosted service). You get one year of updates and support from purchase.

After that year the software keeps working exactly as it does today — you simply stop receiving new versions unless you renew. Nothing phones home, nothing expires, and no license check can take your site down.

Updating

Upload the new theme zip over the old one via Appearance → Themes → Add New → Upload Theme and choose to replace. Your settings, products and prices are untouched — they live in the database, not the theme.

Moving to another site

Your license covers one production site. Staging and local copies are fine and don’t count.

Upgrading editions

Bought the Theme and want Push Sync? Get in touch rather than buying again — we’ll sort out the difference.