Skill · Version 1.0.0

Quotes, orders and fulfillment

Connects accepted quotations to orders and partial fulfillment while preserving agreed terms and accurate remaining billable quantities.

quotes-orders-fulfillment

See how it helps

When is it useful?

Use it when commercial operations need revisions, split deliveries, cancellations or partial invoices without double counting.

What does it help you do?

Preserves quote revisions and agreed price snapshots.
Converts accepted quotes to orders atomically and repeat-safely.
Tracks fulfilled, cancelled and invoiced quantities per line.

Try asking this

Convert an approved quote once and invoice two partial deliveries correctly. Replay quote acceptance, deliver two batches and invoice each once. The combined fulfilled and invoiced quantities must never exceed the accepted order lines.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

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.

Included files 1

SKILL.md