Developer documentation – Paperwork for WooCommerce

What you can rely on #

Paperwork reads orders through the WooCommerce order API, never through post meta, so it behaves the same with the legacy tables or with High-Performance Order Storage.

A document is rendered once, when it is issued, and stored. Later downloads serve that file. Nothing you hook into changes a document that has already been issued.

Overriding a template #

Every view the renderer uses can be overridden from your theme. Copy the file into a paperwork directory in your theme, keeping its path, and it takes precedence.


your-theme/
  paperwork/
    documents/
      blocks/
        items.php      ← overrides the line-item table
        footer.php     ← overrides the footer

The document data array #

Every block view is handed the same structure. Filter it to add your own keys, and read them in an overridden block.


add_filter( 'paperwork/document/data', function ( $data, $order, $type ) {
    if ( ! $order instanceof WC_Order ) {
        return $data;
    }

    $data['my_plugin'] = array(
        'reference' => $order->get_meta( '_my_reference' ),
    );

    return $data;
}, 10, 3 );

Guard on the order. The same filter runs for a document that has none — a standalone quote or statement — and for the sample used by the preview.

Adding a block #

A block is a schema entry and a view. Declare the schema so the designer can offer it, and ship the view so the renderer can draw it.


add_filter( 'paperwork/blocks/schema', function ( $blocks ) {
    $blocks['my_notice'] = array(
        'label'       => __( 'My notice', 'my-plugin' ),
        'description' => __( 'A line of my own under the totals.', 'my-plugin' ),
        'settings'    => array(
            'text' => array( 'type' => 'rich', 'label' => __( 'Text', 'my-plugin' ) ),
        ),
    );

    return $blocks;
} );

Hook reference #

Generated from the plugin source, so every entry names the file and line it fires on.

paperwork/admin

Filter paperwork/admin/guarded_screens

$screens: string[]

src/Admin/NoticeGuard.php:66

Filter paperwork/admin/suppress_admin_notices

$suppress: bool; * @param \WP_Screen $screen

src/Admin/NoticeGuard.php:117

paperwork/assets

Filter paperwork/assets/url

$url: string; * @param string $file

src/Core/FileManager.php:164

paperwork/blocks

Filter paperwork/blocks/schema

src/Templates/BlockSchema.php:216

paperwork/bulk

Action paperwork/bulk/job_done

$job: Job

src/Bulk/JobRunner.php:418

Filter paperwork/bulk/job_types

$types: string[]

src/Bulk/Job.php:38

paperwork/cache

Filter paperwork/cache/enabled

$enabled: bool

src/Core/Cache.php:47

Action paperwork/cache/purged

src/Core/Cache.php:101

paperwork/compliance

Filter paperwork/compliance/export_xml

$document: Document

src/Compliance/Archive/FiscalYearExport.php:277

Filter paperwork/compliance/fiscal_year_range

$range: array; { from: "Y-m-d", to: "Y-m-d" }
$year: int

src/Compliance/Archive/FiscalYearExport.php:127

Filter paperwork/compliance/notices

$notices: array; * @param TaxTreatment $treatment
$check: VatCheck

src/Compliance/ComplianceData.php:208

Filter paperwork/compliance/payment_country

$country: string; * @param WC_Order $order

src/Compliance/Vat/OssEvidence.php:250

Filter paperwork/compliance/platforms

src/Delivery/Peppol/NationalPlatformRegistry.php:48

Filter paperwork/compliance/profiles

src/Compliance/Profiles/ProfileRegistry.php:76

Filter paperwork/compliance/retention/removable

$removable: bool; * @param Document $document

src/Compliance/Archive/RetentionCleanup.php:205

Filter paperwork/compliance/treatment

$treatment: TaxTreatment; * @param WC_Order $order
$check: VatCheck

src/Compliance/Vat/TreatmentResolver.php:63

paperwork/connectors

Filter paperwork/connectors/registered

$connectors: ConnectorInterface[]

src/Connectors/ConnectorRegistry.php:79

Filter paperwork/connectors/remote_path

$path: string; * @param Document $document

src/Connectors/UploadQueue.php:326

Action paperwork/connectors/uploaded

$document: Document; * @param string $connectorSlug
$result: Result

src/Connectors/UploadQueue.php:302

paperwork/container

Action paperwork/container/services_init

$container: \Paperwork\Core\ServiceContainer

src/PaperworkPlugin.php:241

paperwork/customer

Filter paperwork/customer/identifiers

$identifiers: array[]; { type, label, value }.
$order: \WC_Order

src/Documents/DocumentDataSource.php:1037

paperwork/delivery

Filter paperwork/delivery/emails

src/Delivery/AttachmentMatrix.php:117

paperwork/diagnostics

Filter paperwork/diagnostics/checks

$checks: array; * @param Diagnostics $diagnostics

src/Admin/Diagnostics.php:177

paperwork/document

Action paperwork/document/before_issue

$order: \WC_Order; * @param DocumentType $type
$options: IssueOptions

src/Documents/DocumentIssuer.php:181

Filter paperwork/document/conditions

$order: \WC_Order; * @param DocumentType $type

src/Documents/ConditionEvaluator.php:42

Filter paperwork/document/data

src/Standalone/StandaloneData.php:71

Filter paperwork/document/date

$date: DateTimeImmutable; * @param \WC_Order $order
$type: DocumentType

src/Documents/DocumentDataSource.php:122

Action paperwork/document/downloaded

$document: Document; * @param string $actor user \| customer \| signed_link.
$download: bool

src/Delivery/DocumentEndpoint.php:140

Filter paperwork/document/eligible

$eligible: bool; * @param \WC_Order $order
$type: DocumentType

src/Documents/DocumentType.php:249

Action paperwork/document/emailed

$document: Document; * @param \WC_Order $order
$emailId: string; * @param mixed $email The WC_Email, when WooCommerce passed it.

src/Delivery/EmailAttachments.php:239

Filter paperwork/document/filename

$filename: string; * @param Document $document

src/Documents/Document.php:379

Action paperwork/document/issued

$document: Document; * @param \WC_Order $order
$options: IssueOptions

src/Documents/DocumentIssuer.php:424

Filter paperwork/document/language

$locale: string; * @param \WC_Order $order

src/Integrations/Multilingual/Multilingual.php:91

Action paperwork/document/regenerated

$document: Document; * @param \WC_Order $order
$options: IssueOptions

src/Documents/DocumentIssuer.php:415

Action paperwork/document/reissued

$replacement: Document; * @param Document $document The voided original.
$reason: string

src/Numbering/ReissueService.php:172

Action paperwork/document/voided

$document: Document; * @param string $reason
$actorId: int

src/Documents/DocumentIssuer.php:252

paperwork/documents

Filter paperwork/documents/types

$types: DocumentType[]

src/Documents/DocumentTypes.php:55

paperwork/einvoicing

Filter paperwork/einvoicing/formats

$formats: SerialiserInterface[]

src/EInvoicing/Serialisers/SerialiserRegistry.php:40

Filter paperwork/einvoicing/invoice

$invoice: Invoice; * @param Document $document
$data: array

src/EInvoicing/ModelBuilder.php:130

Action paperwork/einvoicing/produced

$result: EInvoiceResult; * @param Document $document
$invoice: Model\Invoice; * @param string $xml

src/EInvoicing/EInvoiceService.php:361

Filter paperwork/einvoicing/tax_category

$proposal: TaxCategoryProposal; * @param TaxRate $rate
$context: TaxContext

src/EInvoicing/Tax/TaxCategoryMapper.php:72

Filter paperwork/einvoicing/validate

$report: Report; * @param Invoice $invoice
$xml: string; * @param string $format

src/EInvoicing/Validation/Validator.php:165

paperwork/email

Filter paperwork/email/attach

$attach: bool; * @param DocumentType $type
$emailId: string; * @param \WC_Order $order

src/Delivery/EmailAttachments.php:112

paperwork/engine

Filter paperwork/engine/channel_url

$url: string

src/Engine/PackChannel.php:106

Action paperwork/engine/installed

$version: string; * @param array $manifest

src/Rendering/EnginePack.php:352

Filter paperwork/engine/manifest

src/Rendering/EnginePack.php:112

Action paperwork/engine/removed

$version: string; The version that was removed, or "" when it was not recorded.

src/Engine/PackInstaller.php:158

Filter paperwork/engine/source_url

$url: string; * @param array $manifest

src/Rendering/EnginePack.php:132

paperwork/export

Action paperwork/export/job_done

$job: Job; * @param ExportRunner $runner

src/Bulk/ExportCentre/ExportRunner.php:516

Action paperwork/export/schedule_ran

$schedule: ExportSchedule; The updated schedule.
$failure: string; The reason it failed; "" on success.

src/Bulk/ExportCentre/ScheduleRunner.php:189

paperwork/features

Filter paperwork/features/has

$available: bool; * @param string $feature

src/Licensing/Features.php:78

paperwork/fonts

Filter paperwork/fonts/available

src/Settings/RenderSettings.php:74

Filter paperwork/fonts/files

src/Admin/FontManager.php:201

paperwork/fulfilment

Action paperwork/fulfilment/barcode_warning

$entry: array; Symbology, payload, reason and which document it was.
$context: array; What the block knew about the document.

src/Fulfilment/Barcodes/BarcodeWarnings.php:83

Filter paperwork/fulfilment/gift_message_keys

$keys: string[]; * @param GiftReceipt $type

src/Documents/Types/GiftReceipt.php:111

Action paperwork/fulfilment/pick_list_built

$jobId: int; * @param array $data The composed pick list data.
$path: string; Relative store path of the PDF.

src/Fulfilment/PickList/PickListBuilder.php:187

Filter paperwork/fulfilment/rma_number

$rma: string; * @param \WC_Order $order
$prefix: string

src/Fulfilment/Returns/Rma.php:67

Filter paperwork/fulfilment/vendor_document_data

$data: array; * @param Vendor $vendor
$type: DocumentType|null

src/Fulfilment/Vendors/VendorIdentity.php:99

paperwork/identifiers

Filter paperwork/identifiers/known_plugins

src/Integrations/Identifiers/IdentifiersIntegration.php:137

paperwork/integrations

Filter paperwork/integrations

$integrations: AbstractIntegration[]

src/Integrations/IntegrationManager.php:56

Action paperwork/integrations/booted

$manager: IntegrationManager

src/Integrations/IntegrationManager.php:123

paperwork/interchange

Filter paperwork/interchange/accounting_connectors

$connectors: AccountingConnectorInterface[]

src/Interchange/Connectors/AccountingConnectorRegistry.php:70

Action paperwork/interchange/exported

$result: ExportResult; * @param string $path Store-relative path of the file.
$rejectsPath: string; Store-relative path of the rejects list, "" when there are none.
$filters: \Paperwork\Bulk\ExportCentre\ExportFilters

src/Interchange/Exports/AccountingExportRunner.php:209

Filter paperwork/interchange/exports

$exporters: AccountingExportInterface[]

src/Interchange/Exports/ExportRegistry.php:71

Action paperwork/interchange/imported

$result: ImportResult; * @param ImporterInterface $importer
$plan: ImportPlan

src/Interchange/Import/ImportRunner.php:219

Filter paperwork/interchange/importers

$importers: ImporterInterface[]

src/Interchange/Import/ImporterRegistry.php:48

paperwork/issuing

Filter paperwork/issuing/class

$class: string; Fully qualified class name.
$short: string; Which role: DocumentIssuer, IssueOptions or IssueException.

src/Bulk/Issuing.php:154

paperwork/link

Filter paperwork/link/ttl

$ttlSeconds: int; * @param Document $document

src/Delivery/SignedLinks.php:137

paperwork/logger

Filter paperwork/logger/enabled

$enabled: bool

src/Core/Logger.php:49

paperwork/multilingual

Filter paperwork/multilingual/locale_for_code

$locale: string; * @param string $code

src/Integrations/Multilingual/Providers/AbstractLanguageProvider.php:222

Filter paperwork/multilingual/providers

$providers: LanguageProviderInterface[]

src/Integrations/Multilingual/Multilingual.php:172

Filter paperwork/multilingual/translatable_options

$options: string[]; Full option names.

src/Integrations/Multilingual/Multilingual.php:205

paperwork/my_account

Filter paperwork/my_account/documents

$entries: array[]; { document, type, label, number, date, view_url, download_url }.
$order: \WC_Order; * @param string $context my_account \| thank_you.

src/Delivery/CustomerDocuments.php:132

paperwork/number

Filter paperwork/number/format

$number: string; * @param Sequence $sequence
$value: int; * @param array $context

src/Numbering/NumberFormatter.php:43

Filter paperwork/number/placeholders

$context: array; { document_date, order }.

src/Numbering/NumberFormatter.php:123

paperwork/numbering

Filter paperwork/numbering/sequence

$sequence: Sequence; * @param \WC_Order $order
$type: DocumentType

src/Numbering/NumberingService.php:258

paperwork/payments

Action paperwork/payments/block_refused

$block: string; * @param string $reason
$message: string

src/Payments/PaymentBlocks.php:189

Filter paperwork/payments/epc_remittance

$remittance: string; * @param array $data DocumentData array.

src/Payments/EpcQr.php:259

Filter paperwork/payments/pay_now_url

$url: string; * @param mixed $order

src/Payments/PayNowLink.php:99

Filter paperwork/payments/reminder_email

$email: array; { to, subject, body, headers }.
$document: Document; * @param int $offset

src/Payments/DueDates.php:289

Action paperwork/payments/reminder_sent

$document: Document; * @param int $offset

src/Payments/DueDates.php:321

paperwork/peppol

Filter paperwork/peppol/adapters

src/Delivery/Peppol/PeppolRegistry.php:70

Filter paperwork/peppol/document_invoice

$invoice: object|null; A Paperwork\EInvoicing\Model\Invoice once that exists.
$document: Document

src/Delivery/Peppol/PeppolDelivery.php:349

Filter paperwork/peppol/document_xml

$xml: string; * @param Document $document

src/Delivery/Peppol/PeppolDelivery.php:332

Filter paperwork/peppol/recipient

$recipient: string; * @param object $invoice

src/Delivery/Peppol/StorecoveAdapter.php:355

paperwork/printers

Filter paperwork/printers/registered

$printers: PrinterInterface[]

src/Printing/PrinterRegistry.php:44

paperwork/printing

Action paperwork/printing/printed

$document: Document; * @param PrinterInterface $printer
$result: PrintResult

src/Printing/AutoPrint.php:288

paperwork/render

Action paperwork/render/chromium_fallback

$entry: array; The reason and which document it was.
$data: array; DocumentData array.

src/Rendering/Chromium/ChromiumEngine.php:200

Filter paperwork/render/chromium_requested

$asked: bool; * @param mixed $template
$data: array

src/Rendering/Chromium/ChromiumEngine.php:145

Filter paperwork/render/dompdf_options

$settings: array; Option name => value, as accepted by Dompdf\Options::set().
$request: RenderRequest

src/Rendering/DompdfRenderer.php:300

Filter paperwork/render/engine

src/Fulfilment/PickList/PickListBuilder.php:677

Action paperwork/render/engine_fallback

$entry: array; Reason, message and which document it was.
$data: array; DocumentData array.

src/Rendering/RendererFactory.php:306

Filter paperwork/render/html

$html: string; * @param array $data
$template: Template

src/Rendering/TemplateCompiler.php:130

Filter paperwork/render/mpdf_config

$config: array; * @param RenderRequest $request

src/Rendering/MpdfRenderer.php:154

Filter paperwork/render/needs_mpdf

$reason: string; * @param array $data
$template: Template|null

src/Rendering/RendererFactory.php:193

paperwork/sample

Filter paperwork/sample/data

$data: array; The sample document data.
$type: DocumentType; The type being previewed.

src/Admin/SamplePreview.php:351

paperwork/settings

Filter paperwork/settings/advanced_settings

$settings: array

src/Settings/Sections/Advanced/AdvancedSection.php:73

Filter paperwork/settings/available_integrations

$available: array; * @param array $all

src/Settings/Sections/Integrations/IntegrationsSection.php:224

Filter paperwork/settings/compliance_settings

$settings: array

src/Settings/Sections/Compliance/ComplianceSection.php:259

Filter paperwork/settings/connectors_settings

$settings: array

src/Settings/Sections/Connectors/ConnectorsSection.php:186

Filter paperwork/settings/documents_settings

$settings: array

src/Settings/Sections/Documents/DocumentsSection.php:141

Filter paperwork/settings/einvoicing_settings

$settings: array

src/EInvoicing/Settings/EInvoicingSection.php:191

Filter paperwork/settings/field_dependencies

$rows: array; { id, dependencies: { field: ':checked' \| value \| [values] } }
$section: SectionAbstract|null

src/Settings/Settings.php:353

Filter paperwork/settings/fulfilment_settings

$settings: array

src/Settings/Sections/Fulfilment/FulfilmentSection.php:190

Filter paperwork/settings/general_settings

$settings: array

src/Settings/Sections/General/GeneralSection.php:61

Filter paperwork/settings/general_subsections

$subsections: array; SubsectionAbstract class names or instances.

src/Settings/Sections/General/GeneralSection.php:75

Action paperwork/settings/imported

$changes: array; The options that were written.
$payload: array; The whole import payload.

src/Settings/ImportExport.php:357

Filter paperwork/settings/integrations_settings

$settings: array

src/Settings/Sections/Integrations/IntegrationsSection.php:80

Filter paperwork/settings/interchange_settings

$settings: array; WooCommerce Settings API field arrays.

src/Settings/Sections/Interchange/InterchangeSection.php:283

Filter paperwork/settings/modules_settings

$settings: array

src/Settings/Sections/Modules/ModulesSection.php:94

Filter paperwork/settings/printing_settings

$settings: array

src/Settings/Sections/Printing/PrintingSection.php:185

Action paperwork/settings/reset

$slug: string; * @param SectionAbstract $section

src/Settings/ImportExport.php:446

Filter paperwork/settings/section_fields

$fields: array; * @param SectionAbstract $section

src/Settings/Settings.php:151

Filter paperwork/settings/section_visible

$visible: bool; * @param string $slug
$section: SectionAbstract

src/Settings/Sections/SectionAbstract.php:101

Filter paperwork/settings/sections

$sections: SectionAbstract[]

src/Settings/Settings.php:116

Filter paperwork/settings/sections_order

src/Settings/Settings.php:183

Filter paperwork/settings/standalone_settings

$settings: array

src/Settings/Sections/Standalone/StandaloneSection.php:209

Filter paperwork/settings/transferable

src/Settings/ImportExport.php:134

Action paperwork/settings/updated

$section: SectionAbstract|null

src/Settings/Settings.php:298

paperwork/standalone

Action paperwork/standalone/before_issue

$request: StandaloneRequest; * @param DocumentType $type
$existing: Document|null; The version being replaced, if any.

src/Standalone/StandaloneIssuer.php:182

Filter paperwork/standalone/data

$data: array; * @param StandaloneRequest $request
$type: DocumentType

src/Standalone/StandaloneData.php:83

Action paperwork/standalone/deposit_pair

$deposit: Document; * @param Document $balance
$plan: DepositPlan; * @param WC_Order $order

src/Standalone/Deposits/DepositService.php:147

Filter paperwork/standalone/deposit_plan

$plan: DepositPlan|null; * @param \WC_Order $order

src/Standalone/Deposits/DepositSource.php:127

Filter paperwork/standalone/deposit_providers

$providers: DepositProviderInterface[]

src/Standalone/Deposits/DepositSource.php:69

Action paperwork/standalone/deposit_refused

$orderId: int; * @param DepositPlan\|null $plan
$reason: string

src/Standalone/Deposits/DepositService.php:344

Action paperwork/standalone/issued

$document: Document; * @param StandaloneRequest $request
$type: DocumentType

src/Standalone/StandaloneIssuer.php:322

Action paperwork/standalone/quote_accepted

$quote: Document; * @param \WC_Order $order

src/Standalone/Quotes/QuoteService.php:216

Action paperwork/standalone/quote_declined

$quote: Document; * @param string $reason

src/Standalone/Quotes/QuoteService.php:259

Action paperwork/standalone/recurring_ran

$schedule: RecurringSchedule; The updated schedule.
$document: Document|null; What it issued, or null when it failed.
$failure: string; The reason it failed; "" on success.

src/Standalone/Recurring/RecurringRunner.php:213

paperwork/store

Filter paperwork/store/dir_mode

$mode: int; Octal permissions, 0775 by default.

src/Storage/FileStore.php:672

Filter paperwork/store/file_mode

$mode: int; Octal permissions, 0664 by default.

src/Storage/FileStore.php:171

paperwork/template

Action paperwork/template/after_render

$__template: string; * @param array $__variables

src/Core/FileManager.php:206

Action paperwork/template/before_render

$__template: string; * @param array $__variables

src/Core/FileManager.php:195

Filter paperwork/template/id

$id: string; * @param DocumentType $type
$language: string; * @param string $country

src/Rendering/TemplateRepository.php:147

Filter paperwork/template/location

$file: string; * @param string $template

src/Core/FileManager.php:260

Filter paperwork/template/tokens

$tokens: array; * @param Template $template
$data: array

src/Rendering/TemplateCompiler.php:74

paperwork/templates

Filter paperwork/templates

src/Rendering/TemplateRepository.php:107

Filter paperwork/templates/resolve

$template: Template; * @param DocumentType $type
$language: string; * @param string $country

src/Templates/TemplateRepository.php:109

paperwork/webhooks

Filter paperwork/webhooks/payload

$payload: array; * @param Document $document

src/Api/WebhooksController.php:314