Getting started

After installing the module, administrative users with the "Administer order documents" permission will be able to create new order documents. The configuration form is located via the Commerce > Configuration > Orders > Documents menu item.

Use the Add order document button to create a new order document. You will see a configuration form that looks like this:

Configuration options

• Name
  • This document name will appear in the administrative Order Documents listing.
• Machine name
  • This (unique) document id is generated automatically from the document Name. For Default-type documents, this id is used for the associated document template.
• Order type
  • Each document is associated with a single Order type. To create documents for multiple order types, the Duplicate operation can be used for order documents.
• Status
  • Disabled order documents are not available for use by administrative users.
• Plugin
  • Order document plugins control how documents are generated. Each plugin provides its own configuration options. For this documentation, we will use the Receipt plugin as an example. Additional document plugin types can be implemented by developers as custom code.
• Display name
  • The display name is shown to administrative users who create documents for orders. Additionally, for some document plugin types, it may be used for document download filenames.
• Conditions
  • Conditions are used to limit the list of order documents available to administrative users. For example, if you want to create two versions of an order document for different types of customers, you could create two (or more) order documents and use the Customer:Customer role condition to limit each to a separate group of customers.

Plugin-specific configuration

The Receipt document plugin has configuration options that match those on the Order Type configuration form:

• Email the customer a receipt when an order is placed
  • Note that if this option is already enabled for the Order Type and is also enabled for your Order Document, then two emails will be sent to the customer. (So you should not enable both!) 
  • If selected, you can optionally specify an email bcc value
• Send a copy of the receipt to this email:
  • Enter one or more email addresses, separated by commas to be used for the document email bcc value.
• Subject for the order receipt email:
  • Commerce order tokens can be used for the email Subject text. This email Subject will be used for both automatically sent emails and emails sent manually by administrative users.

The Default document plugin has configuration options:

• Administrative users can download document
  • If your document template has formatting that doesn't work for the PDF download and you don't have a custom template for the PDF version, use can use this option to disable the order document download option.
• Administrative users can email document
  • Use this option to prevent documents that should only be used internally from being emailed to customers.
• Subject for the order receipt email:
  • Commerce order tokens can be used for the email Subject text. This email Subject will be used for both automatically sent emails and emails sent manually by administrative users.

After saving the order document, it will appear on the Order documents listing. If more than one document is listed, the list will be draggable. You can reorder the documents to control the order in which they are displayed to administrative users who generate the order documents.

Edit, Duplicate, and Delete operations are also available.

Try it out

Go ahead and create a Receipt type order document. If you already use Order Receipts, you can use the same configuration you have for an Order Type. Once you've created the Receipt document, it will be available as an option for administrative users with the "Administer orders" permission. You can access this page via the Operations menu on the Orders listing page or using a tab link at the top of an order's View/Edit/etc. pages.

When you click on View Document, you should see your Order Receipt document, opened in a new browser window, with standard, non-administrative theming. The page renders the Order Receipt document using the standard receipt template file:

• commerce-order-receipt.html.twig

When you click on Download Document, the receipt will be rendered as a PDF document and automatically downloaded. The standard Entity Print receipt template file is used:

• commerce-order-receipt--entity-print.html.twig

 Note that a patch is currently required for the Entity Print module: issue #3361528: Fix render factory handling of multiple items

When you click on Edit Document, a confirmation form opens, similar to the "Resend receipt" confirmation form. If the Send document button is clicked, the order receipt email is sent to the order email address. Additionally, if the Commerce Log module is enabled, the email success/failure is logged to the Order Activity listing on the order's View page.

If you enabled the Email the customer a receipt when an order is placed option for the Order Receipt document, you can also place a new order to confirm that the order document is sent at checkout completion.