Module: Trade Promotion Management v1.4.0
Trade promotion planning, execution and tracking for BIXCRM
Screen-by-screen guides (each tab explained)
Click a menu item below for step-by-step instructions on that Trade Promotion Management screen:
- TPM Dashboard
- Promotions
- Promotion Types
- Accruals
- Claims
- Deduction Codes
- Sell-Out Data
- Execution Checklists
- Uplift Analysis
- Reports
- Integrations
- Settings
How to use in BIXCRM (daily operations)
- Sign in to the admin area with a role that includes Trade Promotion Management permissions.
- Open Trade Promotion Management (sidebar) or search for Trade Promotion Management in the admin menu.
- Start on the Dashboard (if available) to see open tasks, pending approvals, and KPIs.
- Review Settings after upgrades — new options may need defaults for your company.
- Create or import master data first; most modules block transactions until masters exist.
- Run the main business flow (create → submit → approve → post/complete) using the screens listed in Admin menu below.
- Use Reports / Analytics screens to reconcile stock, finance, compliance, or SLA metrics.
- For integrations (API, EDI, gateways, tax), confirm credentials in Settings and monitor logs or webhook delivery screens.
- Train staff with role-based access — give approvers approve permissions only, operators create/edit on their area.
- If something fails overnight, check BIXCRM cron ran and open the module log / failed queue screen if present.
Admin menu — where to work
Open the Trade Promotion Management section in the admin sidebar. Screens your staff may use (depending on role):
- Accruals
- API Keys
- Claims
- Deduction Codes
- Execution Checklists
- Integrations
- Promotions
- Promotion Types
- Reports
- Sell-Out Data
- Settings
- TPM Dashboard
- Tpm Webhooks
- Trade Promo
- Uplift Analysis
Detailed guide — features, workflows, API & FAQ
Phase 5 Features (Current)
| Feature | Status |
|---|---|
| --------- | -------- |
| REST API (promotions, claims, accruals, sell-out) | Done |
| API key management with scopes & rate limiting | Done |
| Webhooks (promotion.approved, claim.settled) | Done |
| Distributor sell-out sync | Done |
| Accounting Pro GL posting (accruals & settlements) | Done |
| Promotions & claims CSV/Excel export | Done |
All Phases
- Phase 1: Promotions, types, product lines, client targeting, approval workflow
- Phase 2: Accruals, claims, deduction codes, invoice matching
- Phase 3: Sell-out data, CSV import, uplift analysis, execution checklists
- Phase 4: ROI dashboard, budget vs actual, scorecard, deduction aging, PDF export
- Phase 5: REST API, webhooks, Distributors & Accounting Pro integration
Quick Start (Phase 5)
- Integrations → API Keys — Create a scoped API key
- Integrations → Webhooks — Subscribe to promotion/claim events
- Integrations → Distributor Sync — Pull sell-out from distributor orders
- Settings — Enable GL posting and map Accounting Pro accounts
- API:
GET /trade_promotion_management/trade_promotion_management_api/promotions
API Authentication
Authorization: Bearer tpm_xxxxxxxx
Permissions
| Feature | Capabilities |
|---|---|
| --------- | ------------- |
tpm_integrations | view |
tpm_api_keys | view, create, edit, delete |
tpm_webhooks | view, create, edit, delete |
DB Version
Check option tpm_db_version — expected 104 after Phase 5 upgrade.
See [docs/ROADMAP.md](docs/ROADMAP.md) for full history.
Features
Trade promotion planning, execution and tracking for BIXCRM
- **Phase 1:** Promotions, types, product lines, client targeting, approval workflow
- **Phase 2:** Accruals, claims, deduction codes, invoice matching
- **Phase 3:** Sell-out data, CSV import, uplift analysis, execution checklists
- **Phase 4:** ROI dashboard, budget vs actual, scorecard, deduction aging, PDF export
- **Phase 5:** REST API, webhooks, Distributors & Accounting Pro integration
Permissions
Granular staff capabilities are registered on activation. Assign them under Setup → Staff → Roles for the Trade Promotion Management capability group.
Typical capabilities include view, create, edit, delete, plus module-specific actions (approve, export, settings, API access).
Cron Jobs
Background tasks (if enabled) run through BIXCRM's main cron. Example crontab (every 5 minutes):
* * * * * php /path/to/bixcrm/index.php cron/index > /dev/null 2>&1
Check module settings for scheduled jobs (alerts, sync, reports, retention).
After activation — configuration checklist
- Go to Setup → Modules and activate Trade Promotion Management.
- If prompted, click Upgrade Database or reload admin — migrations run automatically.
- Assign permissions under Setup → Staff → Roles.
- Open the module menu and configure settings.
- BIXCRM 3.0+
- PHP 7.4+ (8.1+ recommended)
- MySQL 5.7+ / MariaDB 10.3+ (InnoDB)
- PHP extensions: mysqli, json, mbstring, curl, fileinfo
One-time setup (first time only)
- Setup → Modules → activate Trade Promotion Management.
- Setup → Staff → Roles → assign Trade Promotion Management permissions (view, create, edit, delete, approve, export, settings as needed).
- Open Trade Promotion Management → Settings and complete company defaults, prefixes, integrations, and notification options.
- Create master data (warehouses, products, templates, accounts, routes, etc.) before processing live transactions.
- Enable BIXCRM cron (
php /path/to/bixcrm/index.php cron/index) for sync, retries, alerts, and scheduled jobs. - Optionally enable REST API / webhooks in module settings if you integrate external systems.
BIXCRM Knowledge Base — usage guide generated from module README and documentation.