Upgrade and permissions

1. Back up the database, plugin files, and relevant encryption keys. Review the release's duplicate-record preflight before upgrading.
2. Resolve duplicate conflicts rather than deleting financial history.
3. Stop all application instances, deploy the complete matching plugin package, restart, and complete migrations/update steps.
4. Review store access, earning eligibility, approval policy, and separate payout permissions.
5. Check commission reconciliation and payout-worker scheduled tasks. Test representative access with a non-admin account.

Sales reps should use the frontend portal without broad nopCommerce administrator permissions. Existing assignments and paid records must remain intact.

Original terms, eligibility, and refunds

New commissions retain the original assignment, rate, earning-base policy, store, and accounting currency. Later rep/settings changes or replayed order events do not replace those terms. Eligibility can require payment received, or payment received plus order completion. Pending/authorized payments are not eligible earnings.

Reconciliation updates unpaid balances against persisted order/refund state. Paid originals retain their payment evidence; post-payment refunds create linked signed adjustments. Repeated reconciliation does not create duplicate deductions. External refunds/chargebacks must reach nopCommerce order state to be recognized.

Confirm historical accounting metadata

Older records may lack a verified currency or store. Review them against historical evidence and use Confirm currency for historical commissions before settlement. The system does not infer old currency from current store settings. Unconfirmed legacy records can block new settlement for that rep/store.

Use explicit approved corrections for fractional legacy balances. Reports group amounts by store/currency/precision; do not combine currencies into one monetary total.

Record a manual payment

1. Reconcile the selected reps and review balances.
2. Approve eligible commissions and necessary adjustments.
3. Select one store/currency, including every approved negative adjustment for each selected rep.
4. Confirm each rep's net amount is positive and representable in that currency.
5. After making the payment outside the plugin, enter its reference and choose Record manual payment.

This records payment evidence; it sends no money. Changed eligibility/amounts, omitted debt, mixed currencies/stores, or previously settled rows stop the operation for review.

Use the sandbox payout ledger

1. Open Payout Ledger and load the intended accounting store's sandbox settings. New installations start disabled and paused.
2. Configure synthetic sandbox recipient accounts and review their currency and scenario.
3. Create a sandbox draft from approved eligible rows; keep one store/currency and include approved negative adjustments.
4. Review recipients/allocations, request approval, and approve the batch.
5. Inspect simulated outcomes and audit history, including uncertain/returned cases.

Sandbox results do not mark real commissions Paid, change live balances, or send real money. PayPal and Stripe live payout adapters are not included. Never treat a simulated success as evidence of an actual transfer.

Reports and troubleshooting

Detail exports carry accounting currency/store context and respect access filters. Payout search returns complete matching batches. Review selected reps when refunds or missed lifecycle events affect balances. Do not alter uncertain payout reservations directly in the database.

Confirm the installed release and staging behavior before introducing these controls into a live accounting process. Read Sales Reps FAQs