Ga naar de hoofdinhoud
Versie: 1.x

Technische referentie voor POS-kortingen

Deze pagina beschrijft hoe WCPOS prijsoverschrijvingen voor orderregels behandelt die door kassamedewerkers worden toegepast — hoe ze worden opgeslagen, hoe ze samenwerken met WooCommerce-coupons en welke filters beschikbaar zijn. Zie voor documentatie voor gebruikers Winkelwagenkortingen en Coupons.

Hoe POS-prijsoverschrijvingen worden opgeslagen​

Wanneer een kassamedewerker de prijs van een orderregel instelt of wijzigt in de POS, worden de prijzen per eenheid opgeslagen in de orderregelmeta _woocommerce_pos_data als JSON:

{
  "price": "16.00",
  "regular_price": "18.00",
  "tax_status": "taxable"
}

Voor diverse (aangepaste) producten kan deze meta ook de velden virtual, downloadable en categories bevatten die tijdens couponvalidatie worden gebruikt.

Deze meta is de gezaghebbende bron voor prijzen per eenheid van de regel. De door WooCommerce opgeslagen subtotal voor de orderregel wordt afgeleid van price * qty (met toegepaste belastingextractie en afronding). De opgeslagen total kan lager zijn wanneer couponkortingen worden toegepast, dus lees voor precisie per eenheid altijd _woocommerce_pos_data.price en regular_price.

Nieuwe POS-bestellingen registreren ook de serverpluginversie in de privé-ordermeta _woocommerce_pos_version. Dit biedt een expliciete versiemarkering voor toekomstige compatibiliteitscontroles. Bonberekeningen behandelen de opgeslagen vorm van de orderregel nog steeds als gezaghebbend, omdat een offline bestelling kan worden geaccepteerd door een nieuwere server dan de app die deze heeft aangemaakt.

Subtotaalmodel (v1.9.0+)​

Vanaf v1.9.0 sluit WCPOS aan bij de standaardsemantiek van WooCommerce voor aanbiedingsprijzen:

  • line_item.subtotal = price * qty waarbij price de POS-prijs is (na eventuele overschrijving).
  • line_item.total = subtotal - coupon_discount_for_line.
  • order.discount_total geeft alleen kortingen via kortingsbonnen weer, geen POS-prijsoverschrijvingen.

Dit komt overeen met de manier waarop WooCommerce een product in de aanbieding behandelt: de sale_price wordt het subtotaal en discount_total is gereserveerd voor kortingsbonnen. Er is geen afzonderlijke regel voor "POS-korting" op de bestelling.

Migratie vanaf versies vóór 1.9.0

Eerdere versies verstuurden subtotal = regular_price * qty, waardoor WooCommerce discount_total = subtotal - total berekende en POS-prijsoverschrijvingen als korting opnam. Dit is gewijzigd omdat het conflicteerde met de berekening van kortingsbonnen: recalculate_coupons() gebruikt subtotal als basisprijs, waardoor kortingsbonnen op basis van de oorspronkelijke prijs werden berekend en onjuiste totalen opleverden.

De eerdere tijdelijke oplossing aan de serverzijde — een woocommerce_order_item_get_subtotal-filter dat actief was tijdens recalculate_coupons() — is verwijderd in v1.9.0. Bekijk de ADR voor de volledige geschiedenis.

Gedrag van kortingsbonnen​

Ondersteuning voor kortingsbonnen is een functie van WCPOS Pro. Wanneer een kortingsbon wordt toegepast op een bestelling met artikelen met POS-korting:

  1. De kortingsbon wordt berekend op basis van de POS-kortingsprijs (de waarde in _woocommerce_pos_data.price), niet op basis van de oorspronkelijke regular_price.
  2. Wanneer een kortingsbon wordt verwijderd, keert de bestelregel terug naar de POS-kortingsprijs.

Gedrag van exclude_sale_items​

Artikelen met POS-korting worden door WooCommerce als "in de aanbieding" behandeld wanneer _woocommerce_pos_data.price < regular_price. Coupons waarvoor exclude_sale_items is ingeschakeld, slaan deze artikelen daarom over, in overeenstemming met de manier waarop WooCommerce reguliere aanbiedingsprijzen behandelt.

Zie het filter woocommerce_pos_item_is_on_sale hieronder als ander gedrag nodig is.

Beschikbare filters​

woocommerce_pos_item_is_on_sale​

Bepaal of een artikel met POS-korting voor couponvalidatie als "in de aanbieding" wordt beschouwd.

add_filter( 'woocommerce_pos_item_is_on_sale', function ( $is_on_sale, $product, $item, $pos_data ) {
    // Allow coupons with exclude_sale_items to apply to POS-discounted items
    return false;
}, 10, 4 );

Parameters:

ParameternaamGegevenstypeBeschrijving
$is_on_saleboolOf het artikel als in de aanbieding wordt beschouwd (standaard: price < regular_price)
$productWC_ProductHet productobject
$itemWC_Order_Item_ProductHet bestelregelartikel
$pos_dataarrayDe gedecodeerde _woocommerce_pos_data JSON

REST API-eindpunt​

Het REST-eindpunt voor coupons bevindt zich in de gratis plugin op /wp-json/wcpos/v1/coupons, zodat de POS-app nooit een 404 ontvangt bij het opvragen van coupons — zelfs niet op sites waarop WCPOS Pro niet is geïnstalleerd. De couponfunctie voor gebruikers vereist echter Pro.

De controller breidt WC_REST_Coupons_Controller uit met POS-specifieke toevoegingen:

  • UUID-verwerking voor offline-first-synchronisatie
  • Machtiging access_woocommerce_pos voor toestemmingscontroles
  • Geoptimaliseerd querypad voor bulk-ID's wanneer posts_per_page=-1 en fields=id (of fields=id,date_modified_gmt) worden aangevraagd

Beschikbaarheid van kassabongegevens​

De gegevensbuilder voor kassabonnen (Receipt_Data_Builder) stelt het volgende beschikbaar:

  • lines[].discounts, lines[].discounts_incl, lines[].discounts_excl — kortingsbedrag per regel, berekend als subtotal - total. Sinds v1.9.0 betreft dit bij POS-prijsoverschrijvingen alleen couponkortingen, omdat subtotal === total wanneer geen coupon wordt toegepast.
  • totals.discount_total, totals.discount_total_incl, totals.discount_total_excl — totale couponkorting op bestelniveau uit WC_Order::get_discount_total().
  • totals.savings_total, totals.savings_total_incl, totals.savings_total_excl — totale geregistreerde besparing van reguliere naar verkoopprijs voor productregels, inclusief catalogusaanbiedingsprijzen en kassaoverschrijvingen.
  • totals.total_saved, totals.total_saved_incl, totals.total_saved_excl — gecombineerde totalen van WooCommerce-korting en besparing op de reguliere prijs. De builder sluit regelbesparingen uit die al zijn opgenomen in het WooCommerce-kortingstotaal van een bestelling van vóór v1.9.0.
  • totals.total_saved_complete — false wanneer een regel onvoldoende vastgelegde prijsgegevens bevat voor een betrouwbare aggregatie; de nullable besparingstotalen zijn in dat geval null.
  • discounts[] — array met couponregelitems met label, code en total.

De meta met een onderstreping als voorvoegsel van het regelitem (inclusief _woocommerce_pos_data) wordt door lines[].meta uit Receipt_Data_Builder::get_item_meta_pairs() gefilterd. Receipt Data v1.1 toont in plaats daarvan de vastgelegde normale prijs, verkoopprijs vóór couponkorting, besparing per regel en totale besparing via canonieke velden. Zie Normale prijs en besparing weergeven en Totalen voor sjabloonvoorbeelden.