=== PartiCOD - Collect Advance Shipping Cost or Fixed, Percentage Payments ===
Contributors: wpmethods, ajharrashed
Tags: woocommerce, shipping, shipping cost, advance payment, partial payment
Requires at least: 5.6
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: woocommerce
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Collect shipping cost, fixed or percentage advance payments and record the remaining balance collected on delivery.

== Description ==

PartiCOD – Advance Payments for WooCommerce adds flexible payment plans to classic WooCommerce checkout for selected shipping methods.

**💰 Flexible Delivery Charge Collection** – Collect delivery charges as a fixed amount, percentage, or a combination of multiple sources.

**💳 Full Payment Option** – Allow customers to pay the full order amount upfront with no remaining delivery balance.

**⚙️ Multiple Payment Options** – Enable multiple payment choices, set a default option, and customize checkout labels, including translated text.

**📊 Flexible Percentage Calculation** – Calculate advance payment percentages from the discounted order total, with options to exclude shipping costs and shipping taxes.

**🏦 Gateway-Based Advance Payments** – Restrict advance payments to selected enabled gateways, including mobile banking and manual payment methods.

**🚚 Advance Payment with COD** – Optionally offer full-payment Cash on Delivery alongside advance payment options.

**🧾 Checkout Payment Summary** – Display order value, payable amount, and remaining delivery balance in a clear checkout summary.

**📍 Flexible Summary Positioning** – Place the payment summary above order total, below subtotal, above payment methods, below the payment title, or below payment methods.

**🎨 Live Style Customization** – Customize colors, borders, border radius, padding, and margins with a real-time admin preview.

**✉️ Customizable Messages & Emails** – Edit checkout, order, and email messages using dynamic amount placeholders.

**📦 Delivery Collection Management** – Record full or installment delivery collections with payment method, reference, staff member, and timestamp.

**🔄 Collection Reversal History** – Correct collection records with a complete append-only reversal history for transparent tracking.

**🏷️ Outstanding Balance Badges** – Display outstanding delivery balances immediately after order status in both Classic and HPOS order lists.

**📈 Native WooCommerce Analytics** – Maintain accurate full order values in WooCommerce Analytics without counting delivery collections as additional sales.
The plugin does not process or verify mobile-money transactions itself. It uses your existing WooCommerce gateways. Manual payments remain awaiting verification while on hold. Verify the advance through the gateway or move the order to processing after checking the transfer.


== Screenshots ==
1. Classic checkout payment plans with shipping-cost, percentage and full-payment choices, plus a clear payable-now and due-on-delivery summary.
2. Payment settings with shipping-cost, fixed, percentage, combined and full-payment options, a default plan, and customizable checkout messages and labels.
3. Advance percentage and calculation settings, checkout summary positioning, and the optional full-payment Cash on Delivery setting.
4. Gateway-based payment plans and allowed advance payment gateways. Payment gateway plugins are installed and configured separately.
5. Shipping-method selection for advance payment plans and the optional delete-plugin-data-on-uninstall setting.
6. Order Payments panel showing the full order total, advance payment, collected amount and outstanding delivery balance, with fields to record money received, collection method and an optional receipt or reference.

= Checkout compatibility =

Requires classic checkout using the [woocommerce_checkout] shortcode. Checkout Blocks are not supported and are declared incompatible. Compatible CartFlows and theme checkout templates must retain standard WooCommerce hooks. HPOS order storage is supported.

Gateways that read WooCommerce numeric cart totals in payment fields, including legacy cart->total access, receive the selected advance while fields render. Order payment totals remain the agreed payment amount through verification callbacks and retries. Gateways that rebuild totals from product lines or reject partial amounts may require a specific adapter. Verify your gateway in its sandbox before accepting live payments.

= Payment calculations =

Shipping includes shipping tax. Percentages use the total after discounts, including tax and WooCommerce fees, with an option to exclude shipping and shipping tax. Combined sources are added and capped at the full order total. Currency precision follows WooCommerce settings. A zero-advance option requires an available COD gateway. Full Payment includes shipping, tax and fees and leaves no delivery balance.

= Due collection and accounting =

The compact Payments panel appears below Customer in the order General section. Expand Record collection to enter money already received, a collection method and an optional reference. Partial collection reduces the remaining balance. Reverse entry records a correction and restores that amount to the balance; it does not initiate a refund.

Advance verification is required before delivery collections can be recorded. New collections are disabled for cancelled, failed or refunded orders. Duplicate request IDs and a per-order database advisory lock protect collection writes. Users need WooCommerce management and order-edit permission.

Completing an order does not collect its balance. Recording a collection does not charge a customer, complete delivery, change a gateway transaction ID or create another sale.

The stored order payment total represents the agreed gateway payment. Full product, shipping and tax lines are retained, and the full sale value is stored separately. Native WooCommerce Analytics use the full sale value less shipping and tax for net revenue, following WooCommerce's normal status exclusions. Cash receipts and sales revenue are different measures; review receipts in the collection ledger.

Legacy reports, exports and third-party dashboards that read the stored payment total directly may still show only the advance. This plugin does not allocate tax between installments or initiate collection/refund transactions. Refunds need manual reconciliation against gateway payments and offline receipts. Do not automatically refund full product lines through a gateway that collected only an advance.

= Privacy and external services =

The plugin does not send data to an external service, add tracking or load remote assets. Support links open only when clicked. Payment gateways are separate plugins with their own services and privacy practices.

Collection references, amounts, methods, recording times and staff IDs are stored in WooCommerce order metadata for bookkeeping. Access is controlled by WooCommerce order permissions. Removing the plugin retains its data by default. If Delete plugin data on uninstall is enabled, uninstall permanently removes plugin settings and payment/collection metadata, including the original full-value metadata and receipt history. WooCommerce orders, order notes, stored order totals and shared database tables are retained. Review order retention under your store's privacy policy.

= Gateway-based payment options =

Enable Payment gateway plans > Show payment options and payable cost with allowed gateways to activate plans by the selected payment method instead of shipping methods. Shipping selection is not required. The summary follows your configured checkout position and appears when an allowed online gateway is selected. Gateway names display the payable amount. Other online gateways remain available and collect the full order total. Leave the allowed gateway selection empty to support all online gateways. Turn the option off to restore shipping-based activation.

== Installation ==

1. Install and activate WooCommerce.
2. Upload the particod folder to wp-content/plugins, or upload its ZIP through Plugins > Add New.
3. Activate PartiCOD – Advance Payments for WooCommerce.
4. Configure shipping zones and payment gateways in WooCommerce.
5. Open WooCommerce > PartiCOD > Payment Settings.
6. Select shipping methods, enable payment choices, choose a default, and enter fixed or percentage values.
7. Optionally rename choices using Checkout label. Leave blank for the original label; {percentage}% inserts the configured percentage.
8. Select advance gateways, checkout position and the optional full-payment COD setting. Save Settings.
9. Customize messages in the sidebar. Use {advance_amount}, {shipping_amount} and {due_amount} where indicated.
10. Use Checkout Design for color pickers, border, radius and spacing. The plugin generates checkout styles from these validated settings.

== Frequently Asked Questions ==

= Does this plugin include bKash or Nagad gateways? =

No. Install and configure a compatible WooCommerce gateway separately. Advance calculations can be used with enabled online or manual gateways; provider verification remains the gateway's responsibility.

= Can customers choose Full Payment or COD? =

Enable Full Payment in Payment options. Enable Allow full payment on delivery to offer COD alongside advance gateways. COD must also be enabled and available in WooCommerce.

= Does an on-hold order mean its advance was received? =

No. The advance remains awaiting confirmation. Verify the payment before marking the order processing or completed.

= How do I record money received on delivery? =

Open the order, expand Record collection under Payments, and enter the amount, method and optional receipt/reference. The history records the entry, and the due balance updates. Use Reverse entry for a correction.

The order-item summary shows the full Order Total, confirmed advance, delivery collections, total Paid and outstanding balance. Recording or reversing a collection updates these figures immediately. Gateway charges and refund limits continue to use the original advance; Paid shows receipts before refunds.

= How do I repair historical Analytics totals? =

Use Refresh order analytics in the order's Analytics & help section. For multiple historical orders, reimport affected orders through WooCommerce Analytics > Settings > Import historical data.

= Does uninstall remove financial records? =

Data is retained by default. Enable Database cleanup > Delete plugin data on uninstall and save settings to permanently remove plugin settings and payment/collection metadata when deleting the plugin. Deactivation never deletes data. There are no separate plugin tables to drop. This is destructive: collection history and the stored full order value are removed; WooCommerce orders, order notes and stored order totals remain unchanged.

== Changelog ==

= 1.0.0 =
* Initial PartiCOD release.

== Upgrade Notice ==

= 1.0.0 =
Initial release of PartiCOD - Advance Payments for WooCommerce.
