Angebote, Aufträge und Erfüllung

Quotes, Orders & Fulfillment

When to Use

Use when implementing commercial CPQ (Configure, Price, Quote), sales orders, order amendments, delivery/fulfillment tracking, partial shipments, or order-to-invoice handoffs.

1. Quotes, Revisions & Commercial Snapshots

• Quote Versioning (quote_number + revision):
  • When a customer requests changes to a sent or approved quote (Q-2026-0042 v1), create a tracked revision (v2) that supersedes v1 while preserving v1's exact snapshot for audit and comparison.
• Line-Item Pricing & Discount Integrity:
  • Each line item must store catalog_unit_price, discount_type (percentage | fixed), discount_value, effective_unit_price, quantity, unit_of_measure, tax_rate, line_net_amount, line_tax_amount, and line_gross_amount.
  • Compute document totals (subtotal_net, total_discount, total_tax, grand_total_gross) deterministically on the server—never trust client-calculated totals!
• Expiration & Acceptance Lock:
  • Enforce valid_until expiration dates on quotes; an expired or unapproved quote cannot be accepted or converted into a confirmed SalesOrder without renewal/approval.

2. Quote-to-Order Conversion (Idempotent & Atomic)

• Converting an accepted/approved Quote into a SalesOrder must be idempotent:
  • Lock the Quote row (SELECT ... FOR UPDATE), verify status === 'approved' | 'accepted' (and verify Permit's approval payload hash matches), create the SalesOrder and SalesOrderLines copying the exact locked commercial snapshots, link sales_order.source_quote_id = quote.id, and transition the quote to converted.

3. Line-Level Fulfillment Tracking (Partial & Split Deliveries)

Real-world orders are frequently delivered in multiple shipments or milestones. Track quantities at the Order Line level (sales_order_lines): $$\text{qty_ordered} = \text{qty_fulfilled} + \text{qty_cancelled} + \text{qty_open}$$

• Invariant: On every sales_order_line, enforce qty_fulfilled >= 0, qty_cancelled >= 0, and qty_fulfilled + qty_cancelled <= qty_ordered.
• Fulfillment / Shipment Documents (fulfillments + fulfillment_lines):
  • Each physical shipment or service delivery milestone creates a Fulfillment document (draft $\rightarrow$ packed $\rightarrow$ shipped / delivered) referencing the specific sales_order_line_id and qty_delivered.
  • Derive the parent SalesOrder.fulfillment_status deterministically from its lines:
    • unfulfilled when SUM(qty_fulfilled) == 0
    • partially_fulfilled when 0 < SUM(qty_fulfilled) < SUM(qty_ordered - qty_cancelled)
    • fulfilled when SUM(qty_fulfilled) == SUM(qty_ordered - qty_cancelled) (and > 0).

4. Clean Handoff to Billing / Invoicing

• Track qty_invoiced (or milestone billed amount) per order line / fulfillment so partial deliveries can generate accurate partial invoices without double-billing or losing unbilled remainder lines.