POS Extensions / Calculation behavior change

POS 11.5: Custom fixed-amount line discounts move
from "whole-line" to "per-unit" calculation

Fixed-amount (FixedAmount) line-item discounts are now calculated internally per-unit. With the current API (2026-04 and earlier) you can still pass the total amount and POS converts it automatically. However, when the amount doesn't divide evenly, the total can differ by up to 1 cent.

On this page
  1. What's actually changing (understand it in 30 seconds)
  2. Diagram: How a total turns into a per-unit conversion
  3. What is and isn't affected
  4. A concrete rounding-error example ($5.00 ÷ 3 units)
  5. Handling it by API version
  6. What developers should do now (3 steps)
  7. 5 key points for engineers
  8. 3 use cases you can apply in your work
  9. A one-line summary you can use in a pitch

1What's actually changing

Starting with POS version 11.5,custom fixed-amount (fixed-amount) line-item discountschange how they're calculated internally.
Until now the discount was applied to the "whole line," but going forward it is per-unit divided and applied.
This change affects fixed-amount discounts only. Percentage discounts are unchanged.
−$5.00

Before: Applied to the whole line

No matter the quantity, the fixed amount was deducted in a lump sum from the line item's total.

Divide per unit

POS 11.5 onward: Applied per unit

The discount is divided by the quantity and applied per unit. The total is nearly the same, with a discrepancy only when it doesn't divide evenly.

2Diagram: How a total turns into a per-unit conversion

What the app passes Total $5.00 setLineItemDiscount POS 11.5 converts automatically $5.00 ÷ 3 units = $1.67 / unit Distribute to per-unit Apply per unit $1.67 + $1.67 + $1.67 = $5.01 Re-total up to +1¢ currency's smallest unit
You don't need to change your app's code.setLineItemDiscount / bulkSetLineItemDiscounts to FixedAmount type pass the line item's total discount amount as before, and the POS system handles the conversion to per-unit automatically.

3What is and isn't affected

Affected

Fixed-amount (FixedAmount) line discounts

Custom fixed-amount line item discounts move to per-unit calculation. Amounts that don't divide evenly can change the total.

Not affected

Percentage discounts

Percentage-based discounts have no change in how they're calculated. This update applies only to fixed amounts.

Affected Cart API methods

setLineItemDiscount

Fixed-amount discount on a single line item. Pass the total and POS converts it to per-unit.

bulkSetLineItemDiscounts

Fixed-amount discount across multiple line items at once. Here too, you can keep specifying the total the same way.

In most cases the total discount amount doesn't change.When the discount amount divides evenly by the quantity, there's no difference and the total stays the same as before.

4Rounding-error example ($5.00 ÷ 3 units)

Discount amount passed (total)QuantityPer unit (per-unit)Actual totalDifference
$5.00 3 units $5.00 ÷ 3 = $1.67(fraction rounded) $5.01 +$0.01
$6.00 3 units $6.00 ÷ 3 = $2.00 (divides evenly) $6.00 ±0

* The first row is the example given in the article. The second row is a contrast added to illustrate the article's note that there's no difference when it divides evenly.

When the amount doesn't divide evenly by the quantity, re-summing the per-unit rounded values can offset the total by up to 1 cent (the currency's smallest unit). Example: applying a $5.00 discount to 3 units makes each one $1.67, so the total comes to not $5.00 but $5.01.

5Handling by API version

API 2026-04 or earlier No action needed Pass the total amount → POS converts it automatically Future API versions Must pass per-unit amounts directly Timing and version not specified (details to follow)
Now

API version 2026-04 or earlier

No changes needed on the extension side. Just pass the line item's total discount amount as before, and POS handles the per-unit conversion for you.

Future

Upcoming API versions

The extension will need to pass the per-unit discount amountdirectly. Specific target versions and timing will be announced as the release approaches (not specified at this time).

6What developers should do now (3 steps)

1
API ver

Check your API version

Audit the Cart API version your extension uses for fixed-amount line discounts.

2

If 2026-04 or earlier, leave it as is

If so, no changes are needed. You can keep your current implementation that passes the total amount.

3

Prepare for per-unit

Prepare tests with amounts that don't divide evenly, to be ready for direct per-unit specification in future versions.

For the detailed spec, see the Cart API reference. Details for future versions will reportedly be added as the release approaches.

75 points engineers should know

Fixed %

1. Applies to fixed-amount discounts only

Only fixed-amount line discounts are converted to per-unit. Percentage discount calculations stay the same and are unaffected.

2. The current API is backward-compatible

No action needed for 2026-04 or earlier. Keep your implementation that passes the total discount amount, and POS automatically converts it to per-unit.

1¢

3. Rounding differences are at most one unit

Only when the discount amount doesn't divide evenly by the quantity can the total be off by up to 1 cent (the smallest unit of the local currency). If it divides evenly, there's no difference.

4. Future: direct per-unit specification

In upcoming API versions, the direction is for extensions to pass per-unit discount amounts directly. The target versions and timing are not specified at this time.

5. Know the affected methods and types

This affects implementations that use the Cart API's setLineItemDiscount / bulkSetLineItemDiscounts with the FixedAmount type. Build your tests on the assumption that a 1-cent difference can occur in receipts and accounting reconciliation. See the Cart API reference for details.

83 use cases for your business

USE CASE 1

Minimize risk by keeping your existing POS discount app as is

Challenge
We heard the fixed-amount discount calculation is changing in POS 11.5, and we're worried it might break our in-house POS extension app.
Action
Check the Cart API version you're using; if it's 2026-04 or earlier, leave the current code (which passes the total amount) as is.
Result
Zero emergency fixes. Since POS handles the per-unit conversion for you, the existing discount behavior is preserved.
Technical note
setLineItemDiscount / bulkSetLineItemDiscounts used with FixedAmount stays the same. When you upgrade to a future version, build per-unit support into your plan.
¥500 ÷ 3 Watch out for rounding
USE CASE 2

Testing rounding differences on "¥X off when you buy multiple items" coupons

Challenge
We make heavy use of fixed-amount discounts that don't divide evenly by quantity, like "¥500 off for 3 items." We're worried the total could be off by one unit and create discrepancies with receipts or accounting.
Action
Write tests for cases where discount ÷ quantity doesn't divide evenly (e.g., ¥500 ÷ 3), and verify the totals on a real POS 11.5 device / sandbox.
Result
Catch the up-to-one-unit difference in advance, so you can set up rules for price display and accounting reconciliation ahead of time.
Technical note
The smallest unit is currency-dependent (USD = 1¢, JPY = ¥1). Also include in your regression tests the case where the amount divides evenly (e.g., $6.00 ÷ 3) and no difference appears.
Current Future Going per-unit
USE CASE 3

Preparing to migrate to a future API version (native per-unit support)

Challenge
Future APIs will require passing the per-unit discount amount directly, but the current code is written on the assumption of a total amount.
Action
Extract and abstract the discount calculation logic from "total → unit price" so you can swap it out once the release details are announced.
Result
Minimize the rework cost at the next major update, and make it possible to control rounding responsibility explicitly on the app side.
Technical note
No target API version number or timing has been stated. Keep watching the Cart API reference and release announcements.

9A one-line summary you can use in a pitch

"From POS 11.5, fixed-amount line discounts move from a "whole line" to a "per item" calculation.
With the current API (2026-04 or earlier), POS converts automatically if you pass the total, so no changes are needed.
You just need to factor in now that amounts which don't divide evenly can produce a total difference of up to one cent, and that future APIs will require specifying the per-unit amount directly."