Price Calculator v1

The Price Calculator is a centralized service that handles all pricing calculations for SCAYLE orders, including taxes, discounts, and unit pricing. It standardizes calculations across invoices, API responses, webhooks, and the entire customer order journey.

Why This Matters

Price Calculator v1 improves invoice accuracy and rounding consistency:

Invoice accuracy: Taxes are rounded per product line, then summed, ensuring invoices reflect expected calculations
Consistency: The same calculation method is used throughout an order's lifecycle (creation through fulfillment)
Transparency: Clear separation between product-line and unit-level pricing supports complex promotions

These improvements may result in 1–2 cent differences in tax and net amounts compared to the previous calculation method, but gross prices remain unchanged.

Key Terms

Product line: A single order line item that may have a quantity greater than 1
Tax summary: The total tax amount shown on invoices, calculated by summing rounded taxes from each product line
Absolute voucher: An order-level discount applied to a single item after confirmation
Tenant Configuration: The per-shop setting that enables or disables Price Calculator v1

What Changed: Rounding Logic

The main difference between the deprecated calculator and Price Calculator v1 is how taxes are rounded:

Method	Deprecated Calculator	Price Calculator v1
Step 1	Calculate tax per product line	Calculate tax per product line
Step 2	Sum unrounded taxes	Round each tax to 2 decimals
Step 3	Round final sum	Sum rounded taxes

Example:

An order has 3 products with the following tax amounts:

Price Calculator v1 (round then sum):

Deprecated Calculator (sum then round):

This example shows a 1-cent difference due to the improved rounding methodology.

How It Works: Core Principles

1. Product Line-Based Tax Calculation

Taxes are calculated on the product line level, not per individual item. This ensures consistent tax calculations throughout the order lifecycle.

Example: If you order 3 shirts at €10.00 each with 20% tax:

Quantity: 3
Line total: €30.00
Tax rate: 20%
Tax for the line: €6.00 (not calculated separately for each shirt)

2. Tax Summary on Invoices

The tax summary on invoices is calculated by:

Calculating tax per product line using the product's tax rate
Rounding each tax amount to two decimal places
Summing the rounded tax values

This follows the "round per product line, then sum" methodology described above.

3. Absolute Voucher Handling

Absolute vouchers (order-level discounts):

In Checkout UI: Applied at the order level
On invoices and refunds: Applied to a single item (typically the most expensive eligible item)
Before order confirmation: Product prices don't reflect the voucher
After order confirmation: Invoices show the discount as part of the item price

This creates a seamless checkout experience while maintaining invoice clarity.

4. Unit-Level Item Pricing

Unit-level prices are now exposed for individual items, enabling promotions like "buy 5, get 1 free" or custom pricing models.

Important: Tax is still calculated at the line level, but unit prices are displayed separately. Small rounding differences (1–2 cents) between unit-level and total pricing are expected and accepted by Payment Service Providers (PSPs).

Example: Buy 5, get 1 free promotion:

Configuration

Price Calculator v1 can be enabled or disabled at the shop level via Tenant Configuration. Once enabled for an order, the same calculator is used consistently for all subsequent order steps.

How to configure: Contact your SCAYLE Account Manager to enable or disable Price Calculator v1 for your shop.

What's Affected

The following areas may show 1–2 cent differences in net values and tax amounts compared to the previous calculator. Gross prices remain unchanged.

Invoices

Affected fields on invoices:

totals.undiscounted
totals.before
totals.after
totals.difference
totals.before.taxSummary
totals.bruttoDiscount
totals.bruttoWithServiceCosts
totals.netto
totals.nettoWithServiceCosts
totals.tax
totals.taxWithServiceCosts

GET Order API

Small differences may occur in order totals:

totals.costWithoutTaxWithoutAbsoluteVouchersWithServiceCosts
totals.costWithoutTaxWithVouchersWithServiceCosts
totals.costWithoutTaxWithVouchersWithShipping

Item-level fields:

items.available.total.taxAmount
items.available.unit.costWithoutTaxWithMembershipDiscount
items.available.unit.costWithoutTaxWithVoucher
items.available.unit.costWithoutTaxWithoutVoucher
items.available.unit.taxWithVoucher
items.available.unit.taxWithoutVoucher

Webhooks & Cloud API

Fields that may show value differences:

cost.withoutTax
cost.withoutTaxwithMembershipDiscount
cost.vat.amount.amount

CCI (Customer Care Interface)

Affected fields in the Customer Care Interface:

item.withoutTaxWithMembershipDiscount
items.cost.withoutTaxWithMembershipDiscount

Important Notes

Consistent behavior: Once an order is created using a specific calculator (deprecated or v1), the same calculator is used for all subsequent calculations throughout the order lifecycle
API integration: When integrating with the API, account for minor tax and net price differences (1–2 cents) due to the improved rounding methodology
Gross prices: No changes to gross (brutto) prices are expected
Backward compatibility: Orders created with the deprecated calculator continue to use it, ensuring no disruption to existing orders