Invoice

First-Pass Node Dossier

This page is an evidence-backed node dossier generated from the domain hierarchy and node questionnaire.

What It Is

Invoice is the generated billing-document record that snapshots order, customer, address, and line data for a fulfillment, refund, return, or other invoice-producing event.

Parent hierarchy:

• Payments & Billing
• Billing Documents And Invoice Outputs
• Invoice

Primary implementation paths:

• packages/framework/src/Models/Invoice.php
• packages/framework/src/Http/Controllers/Api/Admin/InvoicesController.php
• packages/framework/src/Actions/Invoice
• packages/framework/src/Http/Controllers/Api/Storefront/OrdersController.php

What Users Can Do With It

Direct capabilities

Operators can:

• list and show invoices through the admin API
• view invoice items
• read invoice activity logs
• download invoice PDFs through adjacent fulfillment or order workflows

Customers can:

• download fulfillment invoices from My Account order history when an invoice exists

Indirect capabilities

Other workflows use Invoice to:

• create billing documents from fulfillments, returns, refunds, and discounts
• send invoice emails
• generate consolidated invoice PDFs from an order’s invoice set
• export invoices to accounting or tax systems

Things users cannot do directly

This pass did not find a packaged shared admin page for creating or editing invoices manually. Invoice creation is generated by the framework, not authored as a first-pass operator workflow.

Where It Is Managed

Channel	Role	Notes
Admin invoices API	Direct read	Main packaged list and detail surface
Admin fulfillments and orders	Parent-owned	Invoice download and email live on adjacent fulfillment or order actions
Storefront order history	Direct read	Shopper invoice download button when fulfillment invoice exists
Scheduled invoice generation	Indirect	Background jobs create invoices from ready events

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/InvoicesController.php
• packages/framework/src/Http/Controllers/Api/Admin/FulfillmentsController.php
• packages/framework/src/Http/Controllers/Api/Storefront/OrdersController.php
• packages/framework/src/Actions/Invoice/GenerateInvoices.php

Channel-Level Field Coverage

Stored invoice fields

The model stores:

• order_id
• customer_id
• user_id
• note
• customer_json
• shipping_address_json
• billing_address_json
• subtotal_price
• total_price
• total_tax
• total_discount
• total_shipping
• total_fees
• currency
• invoicable_id
• invoicable_type
• export timestamps

Source:

• packages/framework/src/Models/Invoice.php

Admin show surface

The admin invoice show flow can include:

• order
• customer
• items

The nested invoice-items API is read-only in the shared package.

Sources:

• packages/framework/src/Http/Controllers/Api/Admin/InvoicesController.php
• packages/framework/src/Http/Controllers/Api/Admin/InvoiceItemsController.php

Configuration And Data Model

Key model characteristics:

• soft-deletable
• UUID-based
• searchable
• activity-logged
• morphically linked to the event or model that generated the invoice

Important relationships:

• order()
• invoicable()
• items()
• customer()
• user()
• feeLines()
• taxLines()
• discountLines()
• shippingLines()

Source:

• packages/framework/src/Models/Invoice.php

Folded Supporting Records

This first pass documents these supporting line models inside Invoice rather than as standalone pages:

• InvoiceItem
• InvoiceDiscountLine
• InvoiceFeeLine
• InvoiceShippingLine

Those records matter for invoice totals, but they do not appear to be first-pass documentation anchors by themselves.

Relationships

Invoice directly connects:

• order billing state
• fulfillment billing
• refund billing
• return billing
• customer-visible PDF output

Practical dependents:

• My Account invoice downloads
• accounting export
• invoice email delivery
• consolidated invoice summaries

Rules And Downstream Effects

Generated-not-authored behavior

Invoices are created by framework actions rather than through manual admin creation.

Sources:

• packages/framework/src/Actions/Invoice/CreateInvoiceFromFulfillment.php
• packages/framework/src/Actions/Invoice/CreateInvoiceFromOrderReturn.php
• packages/framework/src/Actions/Invoice/CreateInvoiceFromRefund.php
• packages/framework/src/Actions/Invoice/CreateInvoiceFromOrderDiscount.php

Scheduled generation

The scheduled generator creates invoices for:

• fulfillments ready to be invoiced
• completed order returns without invoices
• successful customer-satisfaction refunds without invoices

Source:

• packages/framework/src/Actions/Invoice/GenerateInvoices.php

Partial-fulfillment allocation

Order-level shipping lines and order-level discounts are effectively one-shot across fulfillment invoices:

• once a shipping line has an invoiceShippingLine, later fulfillment invoices skip it
• once an order discount has an invoiceDiscountLine, later fulfillment invoices skip it

Sources:

• packages/framework/src/Actions/Invoice/CreateInvoiceFromFulfillment.php
• packages/framework/tests/Feature/app/Actions/Invoice/CreateInvoiceFromFulfillmentTest.php

Creation guards and reversal

The shared package:

• blocks duplicate fulfillment invoices for the same fulfillment
• supports ReverseInvoice, which clones the invoice and negates its line values

Sources:

• packages/framework/src/Actions/Invoice/CreateInvoiceFromFulfillment.php
• packages/framework/src/Actions/Invoice/ReverseInvoice.php

Consolidated-invoice distinction

The shared package can generate consolidated invoice PDFs and emails for order-based customers, but that does not create a separate consolidated Invoice row. It summarizes existing invoices linked to the order.

Sources:

• packages/framework/src/Actions/Order/GenerateConsolidatedInvoicePDF.php
• packages/framework/src/Actions/Order/SendConsolidatedInvoiceEmail.php

Invoiced-order locking

Once invoices exist, upstream commerce records become partially locked:

• invoiced orders cannot be deleted
• tax settings cannot be changed on an invoiced order
• invoiced order items, shipping lines, and discount lines cannot be materially changed

Sources:

• packages/framework/src/Actions/Order/DeleteOrder.php
• packages/framework/src/Actions/Order/UpdateOrder.php
• packages/framework/src/Actions/OrderItem/UpdateOrderItem.php
• packages/framework/src/Actions/OrderShippingLine/UpdateOrderShippingLine.php
• packages/framework/src/Actions/OrderDiscountLine/UpdateOrderDiscountLine.php

PDF template selection

Invoice PDF generation chooses a return-specific template when the invoice belongs to an order return; otherwise it uses the standard order invoice template.

Source:

• packages/framework/src/Actions/Invoice/GeneratePDF.php

Integrations And Automation

PDF and email outputs

Invoices are involved in:

• fulfillment invoice PDFs
• invoice downloads
• fulfillment invoice emails
• consolidated invoice PDFs and emails
• admin-only estimated invoice previews for fulfillment requests

Sources:

• packages/framework/src/Actions/Fulfillment/GenerateInvoicePDF.php
• packages/framework/src/Actions/Fulfillment/SendInvoiceEmail.php
• packages/framework/src/Actions/Order/GenerateConsolidatedInvoicePDF.php
• packages/framework/src/Actions/Order/SendConsolidatedInvoiceEmail.php
• packages/framework/src/Actions/FulfillmentRequest/BuildEstimatedInvoice.php
• packages/framework/src/Actions/FulfillmentRequest/GenerateEstimatedInvoicePDF.php

Naming overload on the order model

The shared package uses some invoice-related names on Order for quote or payment-link behavior:

• invoice_url can hold the Stripe checkout URL
• previewEmail and sendByEmail on the order use quote-style email delivery rather than Invoice model delivery

Sources:

• packages/framework/src/Actions/Stripe/CreateStripeCheckout.php
• packages/framework/src/Actions/Order/PreviewInvoiceEmail.php
• packages/framework/src/Actions/Order/SendInvoiceByEmail.php
• packages/framework/src/Mail/ForCustomer/OrderQuoteEmail.php

Accounting export

Invoice records carry export timestamps for accounting and tax-provider flows.

Source:

• packages/framework/src/Models/Invoice.php

Where It Appears To End Users

Invoice appears in both operator and shopper workflows, but mostly as a generated document to retrieve.

Operators see it through admin API, fulfillment downloads, and invoice email workflows. Shoppers see invoice download buttons in My Account order history when a fulfillment invoice exists.

Current Documentation Takeaways

1. Invoice is a generated billing snapshot, not a hand-authored document in the shared package.
2. The strongest shopper-facing invoice surface is fulfillment-based download from My Account orders.
3. Consolidated invoice outputs are related, but they summarize invoice data rather than replacing the invoice record model.
4. Refund invoice generation is selective, and partial-fulfillment invoice allocation is intentionally one-shot for order-level shipping and discount lines.
5. Some order-level email and URL names are overloaded and should not be confused with actual Invoice record delivery.

Open Questions

• This first pass did not inspect downstream accounting integrations that consume exported_to_accounting_at beyond the shared invoice record itself.