Perfex Product Hub documentation

Perfex Product Hub adds a product catalog, multi-warehouse inventory, fulfillment, purchasing, a customer catalog and WooCommerce/Shopify stock publishing to Perfex CRM. Perfex items stay the source of truth: Product Hub links to them by their real IDs and adds its own tables, never columns on Perfex's tables. Every stock movement is a row in an append-only journal; corrections are counter-entries.

Installation

Requirements

• Perfex CRM 3.4 or newer. Tested with Perfex 3.4.1.
• PHP 8.1 or newer with BCMath, cURL, JSON, OpenSSL, DOM/SimpleXML, fileinfo, GD and ZipArchive; MySQL or MariaDB with InnoDB tables.
• Perfex's cron job at least every five minutes. Store calls, imports, e-mails and refills run in the background, never inside a page request.
• HTTPS for customer downloads, webhooks, the Shopify OAuth install and camera scanning.
• For WooCommerce: the included companion plugin (PHP 7.4+, WordPress 6.2+, WooCommerce).

Install

1. Back up the database, files and Perfex's encryption key (store credentials and private files depend on it).
2. Extract the download perfex-product-hub-1.0.2.zip. Inside are the installable perfex_product_hub-1.0.2.zip, the WooCommerce plugin perfex-product-hub-woo-stock-1.0.2.zip, this documentation, the changelog and the licences.
3. In Perfex open Setup › Modules, upload perfex_product_hub-1.0.2.zip and activate Perfex Product Hub.
4. Check that the cron job runs. Product Hub appears in the left menu.

Upgrade

Upload the new zip through Setup › Modules; versioned migrations only add tables and columns. Existing Shopify connections keep their authentication mode and active stock pools stay in place. After the upgrade open Integrity and Background Jobs to check that everything is clean. Never uninstall as a way to upgrade.

First steps

1. Setup: choose the valuation currency and the costing method — weighted average (default) or FIFO. Both lock after the first stock posting.
2. Create a physical warehouse.
3. Products › Adopt Existing Item links your Perfex items, or New Product creates one. Adoption keeps the item ID and imports no stock.
4. Sales Links › Enable Sales SKU Field adds a visible SKU custom field to Perfex items, so invoice and estimate lines identify the exact product. Old invoice lines are not guessed or rewritten. The SKU is printed on customer documents — do not put secrets in it.
5. Receive opening stock (Inventory › Receive Stock) or import it.
6. Set an automation actor and default warehouse. Reservations start switched off and deliveries manual: test with a few invoices before turning automation on.

Permissions

Perfex's own rights on items, customers, invoices and estimates still apply on top.

Products and prices

Products are physical goods, services, variants, kits or digital products. A product moves through draft → review → selling → discontinued → archived; with approval switched on an approver activates it. Tracking (none, lot or serial) can change only before the product has stock history. Variant matrices create exact child Perfex items; a kit holds a versioned recipe that can mix services and physical components, and its availability follows its physical components.

Price lists set a price or discount by currency, customer group, minimum quantity, dates and priority. On Perfex's invoice and estimate forms Product Hub searches by SKU, barcode or name, shows stock and price, and Apply Product Hub Price fills the rate — a rate you typed yourself is kept.

Imports and labels

Import Center accepts UTF-8 CSV or the first sheet of an XLSX (up to 500 rows, 40 columns, 2 MB) for products, variants, prices and opening stock. Map the columns or reuse a saved profile, read the dry-run errors, fix rows, then approve. Formulas, macros, external links and entities are refused. Undo uses archives and counter-entries and refuses rows whose stock was already used. Variants need variant_options JSON such as {"Colour":"Blue","Size":"M"}. Read-only imports from earlier warehouse, Omni Sales and Product Lifecycle data are schema-checked; pause the old system during cutover.

Print Code 128, EAN-13 or QR labels on A4 or 58×40 / 80×50 mm rolls. Camera scanning uses the browser's barcode detector over HTTPS; a keyboard scanner or typing works everywhere. Scanning selects a product — receiving, picking and counting still need the confirmed form.

Warehouses and stock

Receive into a physical warehouse with quantity, cost and — when tracked — lot, serial and expiry. Expiring lots are reserved first (FEFO). Bins label locations inside a warehouse; moving a bin label posts no stock. Transfers reserve units into transit; the receiving side records what arrived, and any loss or damage. Open transfers are never returned automatically.

Costing

Weighted average recalculates the unit cost on each receipt; FIFO consumes the oldest layers first. Late landed costs (freight, duty) are allocated to an original receipt or purchase order receipts: the part still in stock is capitalised, the part already sold is expensed separately. Delivered cost of goods is never silently rewritten.

Counts and adjustments

Stock Control › Start Stock Count freezes a warehouse against conflicting movements. Enter counted quantities, review differences, approve and post once. Adjustments always need a reason and approval. Integrity compares balances with the journal and reports differences without changing anything.

Fulfillment

Perfex invoices and accepted estimates are reconciled in the background by the exact SKU on each line. Choose whether stock is reserved on invoice creation or on an accepted estimate, and whether delivery is manual or follows a policy (for example only when the invoice is fully paid; a store's status alone is not proof of payment). Sales Fulfillment handles partial deliveries, carrier and tracking, delivery PDFs and grouped delivery notes. Editing an invoice after delivery goes to review; cancelling releases only what was not shipped. Returns are received at original cost after inspection — a credit note alone does not prove a physical return.

Margins

Each delivered line freezes its net revenue and cost of goods. Margin reports use those snapshots; deliveries made before revenue snapshots existed show the margin as unavailable. Currencies are never added together.

Purchasing

Create a supplier and a purchase order draft, approve it, send the supplier PDF by e-mail from the queue, then receive full or partial quantities against the exact order lines. Min/max levels, lead time and 30/90-day demand produce reorder suggestions; choosing a supplier and warehouse creates a draft, never an order sent by itself. A compatible installed Purchase module can be adopted read-only after you confirm that Product Hub does the receiving.

Customer catalog and downloads

Switch on the catalog and publish selling products. Signed-in contacts see their account prices, send quote requests, reorder from past purchases and download paid digital products. A quote request reserves nothing; staff can reprice it and prepare one unsent Perfex estimate. Paid digital invoices create entitlements per unit: upload the files or an encrypted licence-key pool first. Downloads use short-lived one-use links from the customer's Downloads page; changing or cancelling the invoice withdraws access.

Store connections

Store connections live under Commerce. Credentials are encrypted with Perfex's key and never shown again: leave a secret field empty to keep the saved value. Saving changes the connection revision, which blocks work queued for the old settings. Check Connection runs in the background and shows the result and, for Shopify, the granted scopes.

Shopify setup (Dev Dashboard app — recommended for your own store)

New Shopify custom apps are created in the Dev Dashboard. They do not show a fixed access token: Product Hub exchanges the app's Client ID and Client secret for a token that lasts about 24 hours, and refreshes it itself. This works when the app and the store belong to the same Shopify organization.

1. In Shopify Partners create a development store (or use your live store).
2. Open dev.shopify.com › Apps › Create app. The App URL can stay at its default (or point to your Product Hub page). Untick Embed app in Shopify admin, leave the redirect URLs empty and do not tick Use legacy install flow.
3. Scopes (comma separated): read_products,write_products,read_inventory,write_inventory,read_locations,read_orders,write_orders. Orders older than 60 days also need read_all_orders, which Shopify must approve — optional.
4. Webhooks API version: 2026-10 (the version Product Hub uses).
5. Release the version, then open Distribution › Custom distribution and enter your store domain (name.myshopify.com). This choice is permanent. Without it the install screen says "This app can't be installed yet".
6. Open the generated install link and press Install. Shopify then redirects to the App URL (example.com by default) — that is expected; the app is installed (check Settings › Apps in the store admin).
7. In the app's Settings copy the Client ID and Client secret. In Product Hub › Commerce › Save Connection choose Shopify, mode Dev Dashboard App (Client ID and Secret), enter https://name.myshopify.com, the Client ID and the Client secret, save, then Check Connection. The granted scopes appear on the connection.
8. For test orders, switch on Shopify's Bogus Gateway in the development store.

The Client secret also verifies Shopify webhooks for this mode. Never put secrets in URLs, tickets or screenshots.

Shopify OAuth install (a client's store in another organization)

Client credentials only work inside one organization. To connect a store owned by someone else, use the mode OAuth Install (Authorization Code). It needs Perfex on a public HTTPS address.

1. In the Dev Dashboard app add the redirect URL shown on Product Hub's Commerce page (https://your-crm/admin/perfex_product_hub/shopify_callback) and set the same scopes. Make sure the app's distribution lets it be installed on that store.
2. Save the connection in mode OAuth Install with the store domain, Client ID and Client secret.
3. Press Authorize Shopify Installation. Shopify asks the store owner to approve; you return to Product Hub, which stores an expiring offline token and its refresh token, both encrypted, and queues a connection check.

The authorization link is single-use, bound to your Perfex session and valid for ten minutes. If a refresh fails or the store revokes the app, Product Hub asks you to authorize again; existing stock holds stay in place.

Legacy admin token

A store that already has an admin-created app with a shpat_ token can use mode Legacy Admin Token with that token and a separate webhook secret. Product Hub does not renew static tokens. Connections created before 1.0.1 stay in this mode after the upgrade.

WooCommerce and the companion plugin

1. In WooCommerce create REST API keys with read/write access and enter the store URL, consumer key and consumer secret in a WooCommerce connection.
2. On the WordPress site upload perfex-product-hub-woo-stock-1.0.2.zip under Plugins › Add New › Upload Plugin and activate Perfex Product Hub Stock Bridge.
3. Open WooCommerce › Product Hub Stock Bridge and save a random shared secret of 32–128 characters. Enter the same value as the stock bridge secret in the Product Hub connection.
4. Back up the WordPress authentication salt and the plugin's two command tables with the site; they protect against changing stock twice. Uninstalling the plugin removes only the saved secret.

The plugin supports managed, whole-unit simple products and variations with backorders off. It never writes an absolute stock total: it adds or removes a pool with WooCommerce's atomic stock functions, and a removal fails without effect if a checkout changed the stock in between. It ships a translation template (languages/pph-stock.pot).

Publishing stock pools

1. Map the exact store product or variant, SKU, inventory item and location to a Product Hub product; start from zero available stock in the store.
2. Give a responsible staff member View, Receive/reserve/dispatch, Configure and Publish Store Inventory.
3. In Store Stock Publishing accept the exclusive stock ownership note and enable the policy. Keep one stock writer per SKU and location: no other sync plugin, no backorders.
4. Allocate a pool by hand, or set a target pool size for automatic refill (capped by free, non-expired stock).

Every store change has a durable command key stored before the request. A timeout never becomes a new change: Retry the Same Store Command resends the original. Withdraw a Published Stock Pool removes the remaining pool with the observed store quantity as a guard and releases local units only after the store confirms. Cron also withdraws pools with lots expiring within a day and of discontinued products. Pausing a policy does not remove stock already published.

Store orders and payments

Signed order webhooks are verified and recorded under Commerce › Webhook Events. An order is read again from the store, mapped to an existing customer and imported as an unsent Perfex invoice draft; its units move from the store pool to the invoice. Complex, edited, refunded or tax-inclusive orders fail closed for manual handling. Payments are recorded only from reviewed evidence under Store Payments; Product Hub never charges a gateway. Webhooks need the public endpoint shown on each connection; without a public URL keep webhooks off and use the background checks only.

Price and description sync

Store Stock Publishing can preview a single field (name, description or price) in either direction. An approver accepts ownership of the field; the background worker checks both sides again before one write. WooCommerce simple products support name, description and price; variations description and price; Shopify variants price export. Promotions, other currencies and tax-inclusive prices are refused.

Assets and equipment

Version 1.1 adds an equipment register under Assets (its own menu entry and a section in Product Hub). Give staff the new permission group Product Hub Assets: View Assets, Manage Assets, Check Out and In, Maintenance and Audits; any of them includes reading the register. Customer and project holder names follow Perfex visibility.

• Tags: Asset Settings › Tag Pattern, for example AST-{SEQ:5} or IT-{YY}-{SEQ:4} ({YYYY}, {YY}, {MM} and one {SEQ:n}). Leave the tag empty to get the next number.
• Check-out and check-in to a staff member, customer, project or location with due date, condition and note. Receipt is confirmed without a signature: type who confirmed at hand-over, or the staff member clicks I Received This under My Equipment.
• Maintenance: plans every N days or months or once on a date create the work order ahead of time (Asset Settings › Maintenance Reminder) and notify the chosen people who have the Maintenance capability. Completing a work order records cost, vendor and downtime and moves the plan from the completion date. The Perfex cron job also sends due-back, overdue and warranty reminders.
• Depreciation: straight line ((cost − salvage) ÷ months, rounding in the last month) or declining balance (book value × factor ÷ months, switching to straight line when larger). It stops after the month an asset is retired, disposed or lost. Depreciation › As of shows book values for any month, with CSV export.
• Audits and labels: print labels (QR + Code 128, A4 3 × 7, page or PDF), start an audit for a location or warehouse and scan with a USB/Bluetooth scanner, by typing, or with the camera (HTTPS and a browser with BarcodeDetector). Closing marks unscanned assets missing; managers can mark them lost and move assets found elsewhere.
• Import: CSV columns tag, name, category, model, serial, purchase_date, cost, currency, warranty_end, location, status, method, life_months, salvage_value, notes (only name is required); Check File first, then Import File; undo by batch.
• Switching from another asset module: the Import screen detects the tables of the Fixed Equipment, Assets and AssetCentral modules and reads them without changing them. Check First shows what would be created, left out or renamed; Import creates one batch; a second run skips rows already imported; Undo removes a batch but keeps assets changed since. Quantity-based assets become one entry per unit.
• Family: AI Staff (Find Assets, Assets Due Back, Asset Maintenance Due), Brain Pro asset widgets, Flow Studio triggers (asset checked out, overdue, maintenance due) and a read-only Connect resource pph_assets.
• Accounting modules can read monthly depreciation with the filter pph_asset_depreciation_entries (argument ['period' => 'YYYY-MM']) and record a posting with the action pph_asset_depreciation_posted (asset_id, period, amount, reference); the record is idempotent per asset and month.

Ask AI Staff

With Perfex AI Staff 1.1 or newer active, the assistant gets four read tools from Product Hub. Ask in plain words, for example:

• The numbers are those of Reports › Margin, Stock and Dead Stock: delivered invoice lines, revenue net of discounts and without tax, cost of goods fixed at delivery; amounts stay in the invoice currency.
• Any period (today, yesterday, this or last week, month, quarter, year, or your own dates) in the company time zone, compared with the previous period.
• Rights: "view own" staff see only their own products; sales and profit need invoice and customer view; costs, profit and stock value need Receive, reserve and dispatch stock, otherwise the answer gives quantities and revenue and says costs are hidden.
• The chat offers "Top 5 products this month" and "Profit this month by category" to people who may use them.

Integrations

• Perfex Brain Pro: catalog, stock and stock-value widgets.
• Perfex Cash & Capacity: product costs next to project costs, kept separate.
• Perfex Sales Growth: product and category scopes and profit commission from real delivered cost.
• Perfex AI Staff: sales, profit, stock value and stock movers answers (see Ask AI Staff), scoped product reads; quote drafts need an approval card.
• Perfex Flow Studio: product snapshot, catalog preview and stock triggers.
• Perfex Connect: read-only products, stock and price lists, and a stock event.
• Perfex Document Studio: product sheet, purchase order and grouped delivery note document types.
• Perfex Inbox: products picked in a customer conversation become an internal quote request.
• Perfex Client Hub and Perfex Deliverables: a catalog card for the signed-in contact; paid digital files handed over with a project.

Cron and background jobs

Run Perfex cron at least every five minutes. Workers use small batches, database locks, back-off and visible errors. Check Background Jobs, Sales Fulfillment, Stock Control, Import Center, Digital Delivery and Store Stock Publishing for anything waiting.

Deactivate and uninstall

Deactivating keeps all data. Uninstalling removes the module folder and keeps the data unless Setup has delete-on-uninstall switched on, which requires typing DELETE PRODUCT HUB DATA. Perfex items and their SKU field always stay. Withdraw published store pools first.

Troubleshooting

• "This app can't be installed yet" in Shopify. Set Distribution › Custom distribution with your store domain (Shopify setup step 5).
• Missing Shopify scopes. Edit the scopes, release a new version and approve it again in the store, then Check Connection.
• Shopify OAuth asks for HTTPS. Perfex must run on a public HTTPS address and the redirect URL must match exactly.
• A store command stays uncertain. Retry the same command; never create a new one. Check the store's stock history before deciding.
• Stock does not reserve on invoices. The line needs the product's SKU (Sales Links), reservations must be on, and cron must run.
• Integrity reports a difference. Nothing is changed automatically; review the listed movements and post an approved adjustment if needed.

Changelog

Current version 1.1.0 (25 Oct 2026). Release notes of every version, newest first: perfexcrm.app/product-hub/changelog/.

1.1.0

• Assets and equipment: register with numbered tags, check-out and check-in with receipt confirmation, maintenance plans and work orders, depreciation and book values, audits with printable labels, CSV import/export and read-only switch-over imports. See Assets and equipment.
• New permission group Product Hub Assets. Upgrade: replace the files, then Upgrade Database; new tables only.

1.0.5

• Fix: the Catalog step and the Stock changed trigger show their choices and fields with labels in the Flow Studio builder (registered in the format Flow Studio documents); existing flows keep working.

1.0.4

• Fix: setting up the SKU field for invoices and estimates now works on a fresh install (the field was created hidden from the items table); existing installs are repaired on upgrade.

1.0.3

• Perfex AI Staff answers sales, profit, stock value and slow-mover questions from Product Hub's own figures, within each person's rights.

1.0.2

• Shopify OAuth install (authorization code) for stores in another organization, with expiring offline tokens, refresh and re-authorization.
• Nine languages; the WooCommerce companion plugin is translatable and ships a template.
• Same look as our other modules, light and dark in step with them, phone layouts.

1.0.1

• Shopify Dev Dashboard apps (Client ID and secret) with encrypted 24-hour tokens refreshed automatically; legacy tokens kept.
• Tested against real WooCommerce stores (HPOS on and off) and a Shopify development store.

1.0.0

• First release: catalog, warehouses, lots and serials, average or FIFO cost, reservations and deliveries, purchasing, customer catalog, WooCommerce and Shopify stock pools and order import.

The full list is in changelog.txt in the download.