Custom Checkout Fields: documentation

Overview

DataFirefly Custom Checkout Fields adds custom fields to the checkout and the registration form of PrestaShop 8 and 9: purchase order number, requested delivery date, SIRET, business sector, attachment, or any other field you create. Values are checked before the order is placed, then carried to the order page, the PDF invoice, the delivery slip, emails, back-office lists, CSV exports and the webservice.

Installation

1. In the back office, open Modules > Module Manager and click Upload a module.
2. Select the dfcheckoutfields.zip file.
3. Installation creates three tables, the protected upload/dfcheckoutfields folder, the Orders > Custom fields and Orders > Custom fields export menus, and five ready-to-use fields.
4. Click Configure to set the general options.

To update, upload the new ZIP over the old one: the upgrade scripts add new columns without touching your fields or stored values.

Fields created on install

• Purchase order number (po_number): text up to 50 characters, stored on the order, shown on the invoice, the delivery slip and as a column of the order list.
• Requested delivery date (desired_date): earliest date today + 2 days, working days only.
• SIRET number (siret): checked with the Luhn key, stored on the customer account, asked at registration and checkout, limited to customers whose country is France.
• Business sector (sector): list of eight sectors, stored on the customer account, asked at registration.
• Attachment (attachment): PDF, images and Office documents, 8 MB max.

None of these fields is required by default. Edit, disable or delete them to suit your shop.

General settings

Modules > Module Manager > Custom Checkout and Registration Fields > Configure.

• Position of the block in the checkout: payment step, above the payment methods (default), or delivery step, below the carriers. Carts with virtual products only always use the payment step.
• Block title: shown at checkout, on order pages, PDFs and emails, per language.
• Position on the PDF invoice: header below the invoice number, or bottom of the invoice. See Invoice and delivery slip.
• Private note when a required field is missing: adds the list of missing fields to the private note of the order when a payment module bypasses the checkout check.
• Copy SIRET fields to the native customer SIRET: keeps the SIRET field of the customer record, used by PrestaShop B2B mode, up to date.

Create or edit a field

Orders > Custom fields, then Add a field or the pencil icon of a row. The form only shows the options that apply to the selected type and storage.

Field

• Label, placeholder and help text: per language. An empty language uses the label of the default language.
• Code: technical identifier in lowercase letters, digits and underscores. Also used as the {dfcf_CODE} email variable and in the webservice.
• Type: text, multi-line text, number, email, date, drop-down list, checkbox, SIRET or file.
• Stored on: Order (one value per order) or Customer account (value kept on the customer record, prefilled at checkout and copied to each order).
• List options: one option per line as key|Label, for example industry|Manufacturing. Keep the same keys in every language.

Where and when

• Show at registration and required at registration: customer account fields only, file type excluded. They also appear in the My personal information form of the customer account.
• Show at checkout and required at checkout.
• Show only if: see Conditional display.
• Countries: country of the invoice address at checkout, of the visitor at registration. Empty for every country.
• Customer groups: everything unchecked for every group.

Validation

• Maximum length: 0 for the default (255 characters, 2000 for multi-line text).
• Validation pattern: regular expression without delimiters, for example ^[A-Z]{2}[0-9]{6}$.
• Minimum lead time and maximum horizon in days for a date stored on the order.
• Working days only: refuses Saturday and Sunday.
• Closing days: one per line, 2026-12-24 for a day, 2026-08-01:2026-08-21 for a period, 12-25 for every year.
• Allowed extensions and maximum file size for a file. Scripts and executables are always refused.

Documents and exports

Show to the customer (confirmation, customer account, customer emails), on the PDF invoice, on the delivery slip, as a searchable column of back-office lists, in CSV exports.

Field list

The list icons switch a setting on or off in one click. Drag rows to change the display order. The Duplicate action creates a disabled copy with the code code_copy. A field with values on orders cannot be deleted: disable it to keep the history.

Conditional display

Example: show the SIRET to businesses only.

1. Create a Checkbox field stored on the customer account, code is_company, label I am a business.
2. Edit the SIRET field, Where and when section, and set Show only if: I am a business. Leave “has one of these values” empty: for a checkbox it means checked.

For a drop-down list, enter the expected keys separated by commas, for example health,public. Conditions can be chained: a field whose parent is hidden is hidden too. A hidden field is never required and its value is not kept. The parent field must be shown in the same place (registration or checkout), or already filled in on the customer account.

Customer side

At checkout

The block appears at the selected step. Each value is saved while the customer types. As long as a required field is empty or invalid, clicking Place order (or Continue at the delivery step) is blocked, the message appears below the field and the page scrolls to it. The attachment is sent by drag and drop or by click, with a progress bar. The customer can remove it and send another.

At registration and in My personal information

Customer account fields marked Show at registration are added to the native account creation form, the guest form of the checkout and the My personal information form. Errors are shown like those of PrestaShop fields.

After the order

Values marked Show to the customer appear on the confirmation page and in the order details of the customer account. The attachment can be downloaded there by the customer who owns the order.

Invoice and delivery slip

Bottom of the invoice: the module uses the displayPDFInvoice hook and prints a table after the totals. No file is modified.

Header, below the invoice number: PrestaShop has no hook there. When you save this setting, the module adds a block delimited by {* dfcf:start *} and {* dfcf:end *} at the end of themes/YOUR_THEME/pdf/invoice.summary-tab.tpl. If the file does not exist, it is created from the PrestaShop one. If it already exists, the module completes it and keeps a .dfcf-backup copy. Switching back to Bottom of the invoice or uninstalling removes the block. If the file is not writable, a message gives its path.

With DataFirefly Invoice Editor, which replaces the invoice rendering, use Bottom of the invoice: the editor keeps module content at the position you choose.

The delivery slip uses the displayPDFDeliverySlip hook, field by field.

Emails

Two kinds of variables are available in emails that contain the order ID, including order_conf and new_order:

• {dfcf_fields}: every value in a table. In order_conf, only fields marked Show to the customer are included. In new_order, sent to the merchant, all fields are.
• {dfcf_CODE}: a single value, for example {dfcf_po_number} or {dfcf_desired_date}.

Add them in Design > Email Theme, or in the mail files of your theme.

Back office

• Order page: Custom fields card with every value. The Edit button lets you correct a value or replace the attachment.
• Customer page: card with the customer account fields, editable the same way.
• Lists: each field marked as a searchable column appears in the order list with a text filter. Customer account fields also appear in the customer list.

CSV export

Orders > Custom fields export. Choose Orders or Customers, the period, the order statuses (everything unchecked for all), the separator, and whether only rows with at least one value are exported. The file is UTF-8 with BOM, opened directly by Excel. Orders are exported with reference, date, status, customer, totals tax excluded and included and currency, followed by the fields marked Include in CSV exports.

Webservice

1. Advanced Parameters > Webservice: enable the webservice and create or edit a key.
2. Tick GET on the dfcf_values resource.
3. Call /api/dfcf_values?filter[id_order]=[123]&display=full.

Each value is returned with id_dfcf_field, id_order, id_customer, id_cart, value, value_display, field_code, field_label and has_file. Customer profile values have id_order and id_cart set to 0.

Attachments and security

Each file is checked on its extension (field list) and on its real content: a script renamed to .pdf is refused. It is stored in upload/dfcheckoutfields with a random name and no extension, in a folder where direct access is denied by an .htaccess file. On Nginx, add the rule location ^~ /upload/dfcheckoutfields/ { deny all; }. Downloads always go through the module, which checks that the visitor is the customer of the order or an employee.

GDPR

Values stored on a customer account are deleted with the customer. The module answers the export and deletion requests of the official PrestaShop GDPR module. Values copied to orders are kept with the order.

Troubleshooting

The block does not appear at checkout

Check that the field is active, marked Show at checkout, and that the customer group and country match its restrictions. If you chose the delivery step, check that your theme calls the displayAfterCarrier hook.

The Place order button is not blocked

The module recognises the button of the Classic and Hummingbird themes. A theme that replaces this button with another element, or an express payment started from the product page, is not covered: enable the private note to be warned of incomplete orders.

The fields do not appear in the invoice header

Check that the theme file pdf/invoice.summary-tab.tpl is writable, save the settings again, then clear the cache in Advanced Parameters > Performance.

An email variable shows as is

It is only filled in emails that contain the order ID. Also check that the code exactly matches the field code.