Skip to content
P4 Software P4 Software / cifraHQ

Add these docs to Claude

Ask Claude questions about these docs. Claude reads the published pages and links you back to them. Copy this address:

https://p4-software.opendocs.page/mcp

In claude.ai or Claude Desktop: open Settings, then Connectors, choose Add custom connector and paste the address.

In Claude Code, run:

claude mcp add --transport http docs https://p4-software.opendocs.page/mcp

Bonus Rules

Bonus Rules

The Panama custom of "sell 12, deliver 13" (or "sell 24, deliver 26") is everywhere in wholesale, and until now it meant fudging lines by hand. Bonus Rules encode that free-goods logic once so CifraHQ adds the free units automatically on every quote, sales order, and invoice. The customer pays only for what they bought, the tax is charged only on the paid units, and the free line flows all the way through delivery and invoicing without a single manual step.

Where to find it

Go to Master Data > Sales > Bonus Rules.

How to create a Bonus Rule

  1. Click New. The code is assigned automatically when you save, so there is no Code field.
  2. Type a Description, for example "Sell 12, deliver 13". The code is only a number, so the description is how you recognise the rule in the list.
  3. What does the customer get? Type Customer buys (units) and And gets free (units). Both are whole numbers of 1 or more, in single units (not boxes or cases). Below the two boxes CifraHQ writes an example, for instance "Every 12 units bought earns 1 free unit, in whole multiples only. Buy 11: none free. Buy 12: 1 free. Buy 24: 2 free. Buy 25: 2 free." Type "1,200" and it is read as 1200; a number with decimals or letters is refused with a message under the box.
  4. Which Products? Choose All Products, One product or A product group. Only the dropdown for your choice is shown. If you choose one product and it comes in a box whose size divides "Customer buys" evenly, CifraHQ adds a hint such as "This product comes in a box of 12. So this rule means: order 1 box, pay for 12, receive 13."
  5. Who gets it? Choose Everyone, One customer or A customer group. Again only the matching dropdown is shown.
  6. Optionally set Starts and Ends to make it a time-limited promotion (leave both empty for an always-active rule; both are dates in your company's time zone and both days are included, so a rule that Ends on 31 December still applies through the whole of 31 December), and use the Status button to keep the rule Active or set it to Paused (a paused rule is never applied). The End date cannot be before the Start date (the same day for both is fine): if it is, Save stays off and the reason is written next to it.
  7. Read the This rule says box: it repeats the rule in plain words, for example "For every customer: buy 12 units of any product and get 1 free unit, for every 12 units bought." Then click Save.

Save stays off until the rule is complete, and the reason is written next to the button (for example "Enter how many free units the customer gets before you can save.").

A rule can name a product or a product group, and a customer or a customer group, never both: the dialog only lets you choose one of each, and the server refuses a rule that names both. If several rules fit a sale line, only the most specific one is used: product first, then customer, then product group, then customer group.

Rules saved before this dialog

An older rule may name both a product and a product group, or both a customer and a customer group. When you open it, an amber message says it "needs one change" (or "needs changes") before it can be saved, that question opens with nothing chosen, and a line shows what is currently saved, for example "Currently saved with the customer Distribuidora Norte S.A. and the customer group Wholesale. Nothing is lost until you choose and save." Nothing changes until you choose one option and save; the rest of the rule opens exactly as it was saved. If you choose Everyone or All Products instead, the line says "Saving removes both." The rule keeps working in the meantime.

A rule saved for a customer that was later merged into another customer still shows that customer in its Customer box, labelled "(merged)", so editing the description, dates or status never widens the rule to every customer. A merged customer is not offered when you pick a customer for a new rule.

Rules saved before 15 November 2026 under the old convention (End = the day after the last selling day) now also apply on that End day: review them and move the End date back one day if needed.

An existing rule whose End date is before its Start date still appears in the list and still opens, but no change can be saved until one of the dates is fixed: the dialog shows the reason next to Save, and the API refuses the rule too. This does not open the amber message, which is only for a question that names both sides.

Quantities are always units

The two quantities are stored and shown as single units. A rule that used to be entered as "1 Caja x18" now opens as 18 units; the rule itself did not change. The dialog no longer converts boxes or cases for you, so type the number of single units (the box hint under the example tells you what that means in boxes).

How rules are applied

When a matching product is added to a quote, sales order, or invoice, CifraHQ adds a second line marked Bonus for the free units, calculated automatically:

  • Free units = the whole number of buy multiples times the free quantity. Buy 12 get 1: order 12 gives 1 free, order 24 gives 2 free, order 25 still gives 2.
  • The bonus line stays in sync: change the ordered quantity and the free quantity updates with it. Drop below the threshold and the bonus line disappears.
  • Delete the ordered line and its bonus line is removed automatically. The bonus line cannot be hand-edited; if you do not want it, delete it.
  • When several rules match, the most specific one wins - a rule tied to a specific product and customer beats a group-wide or catch-all rule.
  • For Products sold by the pack, the free units are given as a matching pack when the reward divides evenly into one (buy a case, get a free case); when the reward is smaller than a full pack, CifraHQ gives it as loose units instead of rounding it away to zero - so the customer always gets the free unit the rule promises, no matter what size case they ordered in.

Catching a near-miss

When a product with an active Bonus Rule is added to a quote, sales order, or invoice but the quantity entered hasn't yet reached the next buy multiple, a small amber icon appears next to the line's Quantity field. Hover over it and CifraHQ tells you exactly how many more units would earn a free one - for example, "Add 1 more unit for 1 free unit (Buy 12, Get 1)". A customer never quietly misses out on a bonus just because nobody noticed they were short.

The hint is calculated live from the quantity on the line - there's nothing to save to see it, and it disappears on its own the moment the quantity reaches the threshold.

On the invoice and taxes

The free units appear as their own line at 100% discount, so the line total is 0.00. The customer is billed only for the units they bought, and ITBMS is charged only on the paid units - the free unit is left out of the tax base, which is the treatment the DGI expects for a bonificacion. The free line carries through the whole chain: the warehouse picks all 13 units, the invoice bills 12 and shows 13, and electronic Invoices are accepted by the DGI with the free unit at zero.

Tips

  • Use Product Group or Customer Group scope for broad promotions ("any wholesale customer, any product in this line"), and specific Product + Customer rules for a single negotiated deal.
  • Time-limited rules are ideal for seasonal pushes: set the Start and End dates and the rule activates and expires on its own (the End day is the last day it applies).
  • The reward is the same product as the one bought. Different-product rewards ("buy 24 sodas, get a free cup") are coming in a later release.
  • If you create or change rules through the API, send Start and End as plain dates (yyyy-MM-dd, for example 2026-12-31). A value with a time zone offset is converted to the server's time before it is stored and can land on the next day.

Before you start

Bonus Rules is off until an administrator enables it for your company. An administrator needs to turn on the Bonus Rules setting and make sure the Sales Discount Expense account is configured, so the free line posts correctly. Once that is done, any rule you create takes effect immediately.


Related: Products · Customers · Price Rules · Product Bundles · Quotes · Sales Orders · Invoices

Was this page helpful?