Printer Configuration Tool
Audience: POS integrators, implementation and support teams, script authors.
1. Overview
1.1 What script-based printing is
Script-based printing lets an authorized user define the layout of a receipt or a kitchen chit in PAR POS with a short JavaScript program, instead of relying only on the fixed formats in Settings Editor. A script reads the order being printed, decides what to print, and builds the output line by line through a PrintJob object: aligned text, separators, emphasis, barcodes, QR codes, stored images, item grouping, modifiers and conditional content. On supported label printers the same script can also position text and draw boxes.
The script runs locally in the register at print time, in a sandbox with no network, file or system access. The fixed Options > Printing configuration stays in place as the fallback.
1.2 What it solves
Two limitations of fixed formats motivated the feature. Layout changes used to require a product code change, and it was hard to vary output by the characteristics of a transaction such as destination, chit type, future-order status, terminal, item, item group or printer. A script is a controlled customization layer that handles both without changing register code.
| Scope | Detail |
|---|---|
| Supported document types | Receipts and kitchen chits. Label output on supported Brother label printers is produced through chit scripts. |
| Not covered | Payment receipts and other document types need separate product support. Scripts cannot call external services. |
| Fallback | If the feature flag is off, no script is assigned, or a script fails, the register prints the existing Settings Editor > Options > Printing layout. |
1.3 Who should use this guide
-
POS integrators who configure brand- or location-specific output without changing register code.
-
Enterprise operators who manage marketing, fulfillment and kitchen communication requirements.
-
Implementation and support teams who preview, validate and publish changesets.
-
Script authors who know JavaScript and work with the Order, Printer, Store and PrintJob objects.
This guide assumes working knowledge of JavaScript and of Settings Editor and changeset publishing. It does not assume any knowledge of the register source code.
1.4 Quick start
This minimal script prints a store name, an order line and a thank-you. It is the shortest script that is valid in both preview and production.
Script 1: minimal receipt
function setupPreviewData() {
Store.Name = "PAR Burger";
Store.Address1 = "123 Main Street";
Order.Number = 312;
Order.Total = 9.71;
}
function print() {
PrintJob.Bold = true;
PrintJob.AddCenteredLine(Store.Name);
PrintJob.Bold = false;
PrintJob.AddCenteredLine(Store.Address1);
PrintJob.AddFilledLine("-");
PrintJob.AddLeftAndRightLine("Order " + Order.Number, "$" + Order.Total.toFixed(2));
PrintJob.AddNewLine();
PrintJob.AddCenteredLine("Thank you!");
}
Representative output (42-column printer)
PAR Burger
123 Main Street
------------------------------------------
Order 312 $9.71
Thank you!
-
In Admin Portal, open Settings Editor for your location or group.
-
Open Script Functions and select Add New Script Function.
-
Set Name to a descriptive value, Script Type to Printing Configurator and Document Type to Receipt.
-
Paste Script 1 into the editor and run the preview. A valid script renders; an invalid one shows "Script is invalid".
-
Select OK, then open Options > Printing > Receipt and select your script.
-
Publish the changeset, wait for the register to receive the settings, and print a receipt.
2. Requirements and compatibility
2.1 Software and feature flag
-
The group-level feature flag
PARPOS.EnableScriptPrintingConfigurationmust be enabled. When enabled, a selected Printing Configurator script takes precedence. When disabled, the existing Options > Printing configuration remains active and the Printing Configurator controls are hidden. -
The register and Settings Editor both run the PARPOS.JavaScriptEngine library (a .NET Standard 2.0 package built on the Jint 4.1.0 JavaScript interpreter), so a script behaves the same in preview and on the register.
2.2 Access
-
Admin Portal access with permission to open the location's Settings Editor.
-
Permission to create or edit Script Functions and to publish changesets.
-
Register access for physical print testing.
2.3 Supported printers
The documented certification scope for script-based printing is:
-
Bixolon SRP-S300 (commonly configured through Epson emulation).
-
Epson TM-U220.
-
Epson TM-T88.
-
Epson TM-L90 label printer.
3. How it works
3.1 Execution lifecycle
| Step | What happens |
|---|---|
| 1. Trigger | A receipt or chit print event occurs on the register. |
| 2. Selection | The register identifies the document type and the script selected for it under Options > Printing (Receipt or Chit). If the flag is off or nothing is selected, the existing layout is used and the steps below are skipped. |
| 3. Validation | The engine checks the script for restricted words and for the required print() function. |
| 4. Execution | The sandboxed engine receives the data objects (Order, Store, PrintJob, PrintHelper, and Printer for chits) and invokes print(). |
| 5. Rendering | print() has updated the PrintJob; the register renders it into printer commands for the configured driver and emulation. |
| 6. Delivery | The existing printer queue and worker send the output over the configured COM, USB or network path. |
3.2 Receipts versus chits
| Receipt script | Chit script | |
|---|---|---|
| Document Type | Receipt | Chit |
| Selected under | Options > Printing > Receipt Options.Printing.Receipt.ScriptId |
Options > Printing > Chit (Options.Printing.Chit.ScriptId) |
| Objects available | PrintJob, Order, Store, PrintHelper. No Printer object. |
PrintJob, Order, Store, Printer, PrintHelper |
| Cut | Automatic feed and cut after the script. Do not call AddCut. | The script ends the ticket itself with PrintJob.AddCut(85). |
| Around your output | The framework prints a header image and printer messages before your output and loyalty information after it. | No header image, printer messages or loyalty block is documented for chits. Treat the script as responsible for the whole ticket. |
| Extra data | Order.ReceiptPrintCount |
Item destination, OrderTime, Seat, Units, Weight, PreviousItems, BagItems, AllItems, KeyIngredients and more |
A receipt script and a chit script are separate scripts. They expose different data, so do not reuse one for the other without guarding every document-specific field.
3.3 The chit execution model
The same chit script runs repeatedly, and what it sees depends on Printer.ChitType:
| ChitType | How often the script runs | What Order.Items holds |
|---|---|---|
| SingleChit | Once per item | Exactly one item |
| SummaryChit | Once per printer | That printer's items |
| Bag | Once | The bag items |
The ChitType enumeration also has a Both value, but the engine never passes it to a script. Handle SingleChit, SummaryChit and Bag only.
3.4 Data objects at a glance
| Object | Access | Purpose |
|---|---|---|
PrintJob |
Read and write | The output you are building. Set properties to control formatting and call methods to add content. |
Order |
Read-only in production | The order being printed: items, totals, tenders, customer, destination, employee and more. |
Printer |
Read-only, chits only | The chit printer and the current chit run. |
Store |
Read-only | Location name, address and phone. |
PrintHelper |
Read-only | Formatting helpers (currency, short date, short and long time). |
3.5 Preview versus production
| Settings Editor preview | Register (production) | |
|---|---|---|
| Data | Plain, writable JavaScript objects. Your setupPreviewData() creates the data. | Read-only wrappers built from the real order. |
| setupPreviewData() | Required. Runs before print(). | Not called. |
| Limits | Tighter limits are applied. | Register-configured limits. |
| Frozen objects | Not frozen. | Objects flagged as frozen, including PrintHelper, cannot be modified. |
| Errors | The editor shows "Script is invalid" and the message. | The error is only written to the logs and the built-in layout prints. |
The engine freezes any object flagged as frozen when it runs outside preview. PrintHelper is one. Which other objects carry the flag has not been verified, so treat every object as read-only in production.
3.6 Fallback and silent failure
If validation fails or the script throws at runtime, the engine returns nothing and the register prints the built-in layout. The user sees an ordinary receipt or chit, and the error reaches only the register logs. A receipt that "went back to the old format" after a publish is therefore the first symptom of a script error.
4. Creating, assigning and publishing a script
4.1 Script Function fields
| Field | Value | Purpose |
|---|---|---|
| Name | Unique, descriptive | Identifies the script in the Script Functions list and in the assignment drop-down. |
| Script Type | Printing Configurator | Activates the receipt and chit specific fields and editor behavior. |
| Document Type | Receipt or Chit | Sets the document context and therefore the objects the script receives. |
| Script editor | JavaScript containing print() | Defines the output. |
| Preview data | setupPreviewData() | Creates representative data for the preview panel. |
| Publish | Published changeset | Makes the saved selection available to the register. |
4.2 Procedure
-
Log in to Admin Portal and open Settings Editor for the target location or group.
-
Select Script Functions in the left navigation.
-
Select Add New Script Function.
-
Enter a descriptive name.
-
Set Script Type to Printing Configurator.
-
Set Document Type to Receipt or Chit.
-
Enter the script. Define
print(). DefinesetupPreviewData()so the preview has data. -
Use the preview control. A valid script renders a preview; an invalid one shows "Script is invalid" with the reason.
-
Select OK to save the script record.
-
Open Options > Printing > Receipt or Options > Printing > Chit and select the saved script in the drop-down.
-
Publish the changeset and wait for the register to receive the updated settings.
4.3 Assigning scripts
-
Receipt: Options > Printing > Receipt > select a Receipt Printing Configurator script.
-
Chit: Options > Printing > Chit > select a Chit Printing Configurator script.
If no script is selected, or the feature flag is disabled, the existing configuration in the same Options tab is used.
4.4 Printer and context mapping
The selected script controls document content. Printer configuration controls the physical destination, connection, emulation, kitchen role and queue. A chit script can inspect Printer.Name, Printer.ChitType, Printer.ChitCurrentIndex and Printer.TotalChits to vary output for a specific printer or chit position.
The business factors you can use in selection logic include destination, chit type, future-order status, service type, subtotal, date or time, terminal, item, item group, printer, and customer-assigned or loyalty status.
4.5 Kitchen settings
-
Kitchen chit types are Summary, Single, Summary + Single and Bag, where the deployed version supports them.
-
Chit-specific fields include item destination, item-level modifiers, order time, seat, units, unit name, weight, key ingredients, and the collections PreviousItems, BagItems and AllItems.
-
SortPriority is exposed on items and can reorder kitchen items. Sorting by item group depends on product support and should not be assumed.
-
Existing kitchen printer settings and printer messages are separate layers. Do not assume a script replaces every legacy printer message unless the release documents it.
5. Script rules
5.1 Execution contract
-
A script is JavaScript and is case-sensitive. Use the exact names
PrintJob,Order,Printer,Store,PrintHelper,printandsetupPreviewData. -
print()is always required. The engine calls it; your code must not call it. -
setupPreviewData()is required only in the Settings Editor preview. The engine calls it before print(); your code must not call it. -
Define both as top-level function declarations. A direct call to either throws "Direct invocation of print is not allowed".
-
Do not declare a variable or function whose name is original followed by
printorsetupPreviewData; the engine uses those names.
5.2 Strict mode and declarations
Strict mode is on. Assigning to an undeclared variable throws a ReferenceError (for example "q is not defined"), so declare everything with var, let or const.
Prefer var for top-level declarations. In preview the validator evaluates your whole script once for each required function (print and setupPreviewData) in the same engine. A top-level const or let is therefore declared twice and fails with "Identifier ... has already been declared". let and const inside a function are safe, and so are top-level function declarations.
Declarations
var IG_BOXED = 673549520; // OK: top-level var
const IG_OTHER = 1; // FAILS in preview: declared twice
function print() {
const width = 42; // OK: scoped to the function
}
5.3 Restricted words
Before running, the validator searches the entire script text for restricted words. The match is case-insensitive, matches whole words, and applies anywhere: code, comments and string literals. A single match rejects the script with "Script contains disallowed pattern".
The restricted words are eval, alert, console, document, window, localStorage, sessionStorage, setTimeout, setInterval, XMLHttpRequest, fetch, onload, onerror, System.IO, System.Net and Process.Start.
5.4 Supported language features
The engine is Jint 4.1.0, which supports modern JavaScript. These are known to work: arrow functions, template literals, let and const inside functions, optional chaining (?.), spread on plain objects, padStart and padEnd, Array.from, Object.assign, Number.isFinite, and the usual Array, String, Math and Date APIs.
Not available: browser and Node.js APIs (document, window, fetch, timers, localStorage); file-system, network, process and arbitrary .NET (CLR) access; and dynamic code (eval and the Function constructor are disabled).
5.5 Execution limits
A script is stopped if it exceeds the engine's memory, time or statement limits. A stopped script falls back to the built-in layout.
| Limit | Register configuration | Library default (repository) |
|---|---|---|
| Memory | 100 MB | 1 MB |
| Timeout | 5,000 ms | 100 ms |
| Statements | 1,000,000 | 1,000 |
| Strict mode | On | On |
The register supplies its own values through the JavaScriptEngineOptions configuration. The Settings Editor preview applies tighter limits. Confirm the values of your deployed build.
5.6 PrintJob is stateful
Formatting properties stay on until you turn them off. Initialize the properties you care about at the start of a script and reset each one right after the content that needed it. This matters most on label printers, where Bold, DoubleHeight, DoubleWidth and justification carry from one label to the next.
Reset formatting after use
PrintJob.Bold = true;
PrintJob.AddCenteredLine("TOTAL");
PrintJob.Bold = false; // always switch it back off
5.7 Working with data safely
| Topic | Rule |
|---|---|
| Null and missing values | Order.Customer is null when no customer is assigned. Order.Destination is never null in JavaScript, but reading its properties throws if the destination is not in settings. Guard every optional value. |
| Collections | Production collections come from .NET. Use lowercase length. Copy a collection with Array.from(collection) before using array methods such as forEach, sort, filter or find; production scripts do this routinely. Guard against null first. |
| Types | Store.Id is a string. Order.Training is a boolean. Order.Id is a string and may be an encrypted id depending on group settings. Amounts are numbers; format them with toFixed(2). |
| Dates | CreatedDate, BusinessDate and PromiseTime are .NET DateTime values that arrive as JavaScript Date objects. Do not pass a Date to PrintHelper; pass date.toISOString(). Date output is in the register's local time and culture. |
| Currency | PrintHelper.ConvertDecimalToCurrencyString uses the register machine's culture, so the currency symbol follows that machine. For a fixed symbol, build the string yourself: "\$" + value.toFixed(2). |
| Sensitive data | Card numbers and tokens are masked in the wrappers. Do not print employee personal data beyond approved operational needs. |
6. Objects and Methods Reference
Types follow common conventions: string, int, decimal, bool and DateTime. A trailing ? (for example decimal?) means the value can be null. Members not marked chit-only or receipt-only can be relied on in both documents.
6.1 PrintJob
Properties
Each property is a toggle that applies to the content added after it is set, until it is set back.
| Property | Type | Description |
|---|---|---|
| Bold | bool | Bold text. |
| Red | bool | Red text on printers and ribbons that support it. Ignored elsewhere. |
| Center | bool | Centers subsequent text. The dedicated AddCenteredLine is usually clearer. |
| Reverse | bool | Reverse video, typically white text on black. On Brother label printers it prints as a filled bar. |
| DoubleHeight | bool | Double character height. |
| DoubleWidth | bool | Double character width. Halves the characters per line. |
| Orientation | int | Label printers only: 1 = Horizontal, 2 = Vertical. 0 is not valid. |
| FixXPosition | bool | Label printers only: anchor the X position for following lines. |
| FixYPosition | bool | Label printers only: anchor the Y position for following lines. |
| Height, Width | int | Label printers only: label size, carried across labels in a job. |
| Justification | enum | Text justification (left, center, right). Not reset when a label is cut. |
Methods
| Method | Description |
|---|---|
| AddText(string text) | Appends text at the current position without ending the line. |
| AddLine(string text) | Adds a left-aligned line. |
| AddCenteredLine(string text) | Adds a centered line. |
| AddRightLine(string text) | Adds a right-aligned line. |
| AddLeftAndRightLine(string left, string right) | Left and right text on one line. The workhorse for item and total lines. |
| AddLeftCenterRightLine(string left, string center, string right) | Three columns on one line. |
| AddLeftCenterLine(left, center) AddCenterRightLine(center, right) |
Exist, but have no effect on any in-scope printer. Use AddLeftCenterRightLine instead. |
| AddFilledLine(char c) | Fills a whole line with one character, for example "-". It takes a single character, not a string. |
| AddNewLine() | Adds one blank line. |
| AddNewLines(int count) | Adds several blank lines. |
| AddCut(byte length) | Cuts the paper. length is a byte (default 85), not a percentage. Pass 85 explicitly. |
| AddQRCode(string data, int moduleSize = 3) | Prints a QR code. The module size is optional. |
| AddBarCode(string data, symbology) | Prints a barcode. Symbologies: Code39, Ean13, UPCA. Support varies by printer. |
| AddImage(byte id) | Prints a logo already stored in the printer NVRAM, identified by its image number. It does not upload an image. |
| SetCursorPosition(int x, int y) | Label printers: jump to an absolute position, in printer dots. |
| MoveCursorPosition(int x, int y) | Label printers: move relative to the current position, in dots. Negative values move left or up. |
| AddBox(int width, int height, int thickness) | Label printers: box at the cursor. A thickness equal to the smaller dimension renders as a solid bar. |
| AddBoxToAxis(int position, int otherDimension, int thickness) | Label printers: box from the cursor out to a target point, without moving the cursor. |
PrintJob also exposes AddLines, Merge and Clone, which this guide does not document yet. Separation, Bottom, BottomLineCount, FontB and Wrap exist but have no effect on any in-scope printer (see section 7.2).
6.2 Order
The order being printed. It is read-only in production. In preview you assign the properties you need in setupPreviewData().
Top-level properties
| Property | Type | Notes |
|---|---|---|
| Id | string | May be an encrypted order id depending on group settings. |
| Number | int | Order number. |
| Name | string | Order name. Some stores append extra text after a pipe character. |
| Balance | decimal | Positive: balance due. Negative: change due. Zero: paid in full. |
| SubTotal | decimal | Subtotal. |
| SubTotalBeforeReduction | decimal? | Subtotal before reductions. |
| Tax | decimal | Order tax. Production scripts use this rather than TotalTaxAmount. |
| TotalTaxAmount | decimal | Total tax amount. |
| Rounding | decimal | Rounding adjustment; zero when none. |
| Total | decimal | Order total. |
| BusinessDate | DateTime? | Business date. |
| CreatedDate | DateTime | When the order was created. |
| PromiseTime | DateTime | Promised time. Production delivery scripts print "ASAP" when getFullYear() is not greater than 0. |
| Closed | bool | Order is closed. |
| IsFired | bool | Order has been sent to the kitchen. |
| IsFutureOrder | bool | Future order. |
| Refund | bool | Refund order. |
| TaxExempt | bool | Tax-exempt order. |
| Training | bool | Training-mode order. |
| GuestCount | string | Guest count. |
| CustomerAccountNumber | string | Customer account number. |
| CustomerAssigned | bool | A customer is assigned. |
| CustomerType | string | Customer type. |
| string | Order email. | |
| PhoneNumber | string | Order phone number. |
| ReceiptPrintCount | int | Receipt only. Number of times the receipt has printed. |
| ChitPrintCount, EditCount | int | Counters for chit prints and edits. |
Nested objects
| Property | Members | Notes |
|---|---|---|
| Customer | FirstName, LastName, FullName, PhoneNumber, Address (including Notes) | Null when no customer is assigned. |
| Delivery | Address.Address1, Address2, City, State, PostalCode, Notes; PhoneNumber | Populated for delivery orders. Check Destination.IsDelivery. |
| Destination | Id, Name, Indicator, IsDelivery, KitchenChitHeader, KitchenDescription | Never null, but properties throw if the destination is not in settings. |
| Employee, ClosedByEmployee | DisplayName, FirstName, LastName, IsTraining | DisplayName can be null; fall back to first and last name. |
| Lane | Name, Prefix | |
| Party | Name, OrderNumber | |
| Terminal | Name | The register. |
Adjustment collections
| Collection | Members |
|---|---|
| Discounts | Name, PrintedName, Amount |
| Promotions | Name, PrintedName, Amount |
| Surcharges | Name, Amount |
| Taxes | Name, Amount |
| MarketingCampaigns | Name |
Items
Order.Items holds the line items. It can include voided items (Voided is true) and the children of combos and bundles. A child has CompositeOrderItemId greater than zero and also appears under its parent in CompositeOrderItems; a top-level item has CompositeOrderItemId equal to 0. Print top-level items only and render the children through the parent. Order.VoidItems has the same shape with Voided true.
| Property | Type | Notes |
|---|---|---|
| Id, ItemId | int | Id identifies the order line, ItemId the menu item. |
| Description | string | Item name. |
| AlternateKitchenName | string | Kitchen name. |
| Quantity | int | |
| Price | decimal | Base unit price. |
| PriceWithModifiers | decimal | Unit price including modifiers. Multiply by Quantity for a line total. |
| Note | string | Item note. |
| SortPriority | byte | Display order; lower prints first. |
| ItemGroups[] | Id, Name | Can be empty. Never assume the first entry exists. |
| Modifiers[] | see below | Each modifier can contain its own Modifiers. |
| CompositeOrderItemId | int | 0 = standalone, greater than 0 = part of a combo. |
| CompositeOrderItems[] | items | Child items. Every item property applies to each child. |
| AutoNumber, AutoNumberPrefix, AutoNumberItemGroupId | byte, string, int | Auto-numbering. |
| IsEdited | bool | Changed after it was sent to the kitchen. |
| IsDeleted, IsCleared, Voided, Sent, IsTaxFree | bool | Status flags. The property is IsDeleted (capital I). |
| PrinterGroupId | int | Chit items: the printer group of the item. |
| Length | int | Item length. |
Modifier members: Description, Id, ItemId, Price, IsTaxFree, ModifierGroup.Id, ModifierGroup.Name and nested Modifiers. ModifierGroupIds and ModifierCodeId are not exposed to scripts. On chits the modifier shape is reduced to Description and ItemId.
Chit-only item properties: Destination (Id, Indicator, KitchenChitHeader, KitchenDescription, IsDelivery, Name), Discounts (PrintedName, Name, Amount), OrderTime, Seat, Units, UnitName, Weight.
NOTE: These names do not exist and cause errors if used: ItemGroupIds, Order.DestinationId, Order.DestinationName. Use ItemGroups and Order.Destination.Id and .Name.
Chit-only collections
| Property | Description |
|---|---|
| Order.PreviousItems | Items already sent on an earlier chit. Item shape. |
| Order.BagItems | Items for the bag. Item shape. |
| Order.AllItems | Every item on the order. Item shape. |
| Order.KeyIngredients | Array of { Count, Text }. |
Tenders
Order.Tenders lists payments. There is no tender type property; infer the type from the fields present. Card number and token are masked.
| Tender kind | Members |
|---|---|
| Cash | Name, Amount |
| Check | Name, Amount, CheckNumber |
| Credit card | Name, Amount, TipAmount, CardNumber, Authorization, AuthorizedTenderAmount, Token, Balance |
| Debit | Name, Amount, TipAmount, CardNumber, Authorization, AuthorizedTenderAmount |
| External | Name, Amount, TipAmount, AuthorizedTenderAmount |
| Gift card | Name, Amount, TipAmount, CardNumber, AuthorizedTenderAmount, BalanceRemaining |
| Gift certificate | Name, Amount, TipAmount, AuthorizedTenderAmount |
| House account | Name, Amount, TipAmount, AccountNumber, AuthorizedTenderAmount |
| EBT | Name, Amount, TipAmount, CardNumber, Authorization, Balance, AuthorizedTenderAmount |
Tenders may also carry AdditionalData.
Order also exposes the methods GetUCPEmbeddedBarCode(plu) and GetCode39EmbeddedBarCode(), and the collections AllOrderItems and GiftCardItems. These are not documented in detail yet.
6.3 Printer
Chit scripts only. Referencing Printer in a receipt script throws a Reference Error.
| Property | Type | Description |
|---|---|---|
| Name | string | Printer name. |
| ChitType | string | SummaryChit, SingleChit or Bag. |
| ChitCurrentIndex | int | Current chit in a multi-chit run. |
| TotalChits | int | Total chits in the run. |
| DiscountChitPlacement | string | None, Top, Bottom or Both. |
| KeyIngredientSummaryPlacement | string | None, Top, Bottom or Both. |
| PrinterGroupIds | int[] | Printer groups the printer belongs to. |
6.4 Store
| Property | Type |
|---|---|
| Id | string |
| Name | string |
| Address1, Address2 | string (Address2 can be null) |
| City, State, Zip | string |
| Phone | string |
6.5 PrintHelper
Formatting helpers that are available in preview and production. Outside preview the object is frozen and cannot be modified.
| Method | Description |
|---|---|
| ConvertDecimalToCurrencyString(decimal) | Formats using the machine culture (for example 7.5 becomes $7.50 on a US machine; the symbol follows the culture). |
| GetShortDate(string iso) | Parses an ISO 8601 string and returns the local short date. |
| GetShortTime(string iso) | Returns the local short time. |
| GetLongTime(string iso) | Returns the local long time. |
IMPORTANT: The date helpers take an ISO string. Passing a Date object fails with "was not recognized as a valid DateTime". Convert first: PrintHelper.GetShortDate(new Date(value).toISOString()). An ISO string without a Z or an offset is treated as UTC. The result is displayed in the register's local time and culture.
Safe date formatting
function formatDateTime(value) {
// value can be a production Date or a preview string
var iso = new Date(value).toISOString();
return PrintHelper.GetShortDate(iso) + " " + PrintHelper.GetShortTime(iso);
}
7. Printer capabilities
The table below comes from engineering review of the printer drivers. It describes what each driver does with a PrintJob command, not the result on physical hardware, so confirm on the real printer before go-live.
7.1 Line width and feature support
| Printer | Width | Red | Reverse | AddBarCode | AddQRCode | AddImage |
|---|---|---|---|---|---|---|
| Epson TM-T88 / RESTICK / U200 | 42 / 44 / 33 | Works | Works | Code39, Ean13, UPCA (U200 prints centered text) | Works | Stored NV image |
| Star TSP100 | 48 | No effect | No effect | Code39 only | No-op | Throws |
| NCR 7197 | 44 | Works | Works | Code39, Ean13 (UPCA throws) | No-op | Throws |
| PAR M3876 | 42 | No effect | Works | Code39, Ean13, UPCA | No-op | Stored image |
| Partner RP-320 | 42 | No effect | Works | Code39, Ean13, UPCA | No-op | Throws |
| Zebra TTP2000 | Not checked | No effect | Works | No-op | No-op | Throws |
| OPOS | From settings | Stored only | Stored only | Always Code39 | Works | Throws |
| PosForDotNet | From settings (default 42) | Stored only | Stored only | Throws | No-op | Throws |
| Brother (new driver) | Proportional (ZPL) | No effect | Filled box | Code39, Ean13, UPCA | Works | Flash image IMAGE{n}.GRF |
"No effect" means the command is accepted and ignored. "No-op" means nothing is printed. "Throws" means the script fails and the register falls back to the built-in layout. AddFilledLine works on all of these printers except the Zebra TTP2000, where it is an empty no-op.
Red and reverse are sent as these printer commands. The Brother driver does not use them: it prints reverse as a filled box, and red has no effect.
| Printer | Red | Reverse |
|---|---|---|
| Epson TM-T88 / RESTICK / U200 | ESC r | Works |
| Star TSP100 | No effect | No effect |
| NCR 7197 | ESC r | GS B |
| PAR M3876 | No effect | GS B |
| Partner RP-320 | No effect | GS B |
| Zebra TTP2000 | No effect | ESC T |
| OPOS / PosForDotNet | Stored only | Stored only |
Only the new Brother driver supports the ZPL cursor and box commands, FixXPosition, FixYPosition, Orientation, Height and Width.
7.2 Commands with no effect on any in-scope printer
AddLeftCenterLine, AddCenterRightLine, FontB, Wrap, Bottom, BottomLineCount and Separation.
7.3 Width, fonts and character sets
-
Line width, font size, red, reverse, double height and double width are limited by the printer and its emulation. A script cannot force a result the hardware cannot render.
-
Keep text inside the printable width. Truncate or wrap long item names and modifiers yourself, and test with the longest real names.
-
DoubleWidthhalves the characters per line. Width-sensitive layouts must account for it. -
Do not assume proportional fonts, Unicode glyphs, italics or underline. Use characters the printer supports.
-
Test barcodes and QR codes with a real scanner; preview does not show scan quality.
7.4 Epson TM-L90 labels
The Epson TM-L90 is within the certification scope for script-based printing. Its existing label template mechanism (the Labels page, with formatting tags such as <Bold> and parameters such as %ItemName%) is a separate feature documented in the Epson TM-L90 Label Formatting Guide. This guide does not replace it.
8. Label printing on Brother printers
Brother label printers add low-level layout control: label orientation, anchored positions, manual cursor movement and boxes. Coordinates are printer dots, not inches or millimeters. Use these members only on a printer and document type that support them; on a thermal receipt printer they have no effect.
8.1 Orientation
Set PrintJob.Orientation to switch layout. The values come from the label orientation enumeration.
| Value | Meaning |
|---|---|
| 0 (None) | Not a valid value to set. |
| 1 (Horizontal) | Standard left-to-right layout. |
| 2 (Vertical) | The label rotates 90 degrees. Text reads sideways and lines advance across the label width. |
-
Orientation carries over between labels in the same job. Always set it explicitly at the start of the script.
-
Switching mid-label keeps the current position and changes how it is interpreted; it does not return the cursor to a corner.
-
Switching on a brand-new label starts from that orientation's normal starting position.
8.2 Fixed positions
Turning FixXPosition or FixYPosition on locks the cursor's current position as an anchor. Every following line that would reset to the default margin starts from the anchor instead, until you turn it off.
-
Which physical direction an anchor governs depends on the orientation when it was turned on. Changing orientation later does not change an active anchor.
-
Turning a fix off returns that axis to its default start for the next line. It does not restore the position from before the fix.
-
Moving the cursor manually while a fix is active moves the anchor with it.
-
A full-width reversed bar drawn while a fix is active spans from the anchor to the far edge, not the whole label width.
8.3 Manual cursor control
-
MoveCursorPosition(x, y)moves relative to the current position. Values can be negative: a negative x moves left and a negative y moves up. -
SetCursorPosition(x, y)jumps to an exact position. Values are normally 0 or positive; a negative value places content off the label. -
x is always horizontal and y always vertical in the call. In vertical orientation what they do visually swaps, but the argument order never changes.
-
These are low-level commands. They do not wrap text, adjust for label size or avoid overlaps; avoiding collisions is the script's responsibility.
8.4 Boxes and bars
-
AddBox(width, height, thickness)draws a box at the cursor. When the thickness is large relative to the smaller dimension, the box renders solid, which gives a reversed or highlighted background bar. -
AddBoxToAxis(position, otherDimension, thickness)draws a box from the cursor to a target point without permanently moving the cursor.
Boxes
PrintJob.AddBox(800, 307, 2); // outer border for the whole label
PrintJob.MoveCursorPosition(765, 0);
PrintJob.AddBox(35, 35, 2); // small square callout
PrintJob.AddBox(681, 35, 35); // thickness = height: solid bar
Orientation, anchors and cursor calls
PrintJob.Orientation = 2; // Vertical
PrintJob.Orientation = 1; // back to Horizontal
PrintJob.FixXPosition = true; // lock the X anchor
PrintJob.AddLeftAndRightLine("Left text", "Right text");
PrintJob.FixXPosition = false; // release it when done
PrintJob.MoveCursorPosition(20, 0); // 20 dots right, from the current position
PrintJob.MoveCursorPosition(0, -35); // 35 dots up (negative y)
PrintJob.SetCursorPosition(8, 0); // jump to x = 8, y = 0
8.5 What resets when a label is cut
AddCut (or sending the buffer) finishes a label. Some state returns to default for the next label and some does not.
| Behavior | State |
|---|---|
| Resets to default | Reverse mode (always off); FixXPosition and FixYPosition anchors (released); cursor position (back to the start for the active orientation); any in-progress, unfinished line. |
| Carries over | Orientation; label Height and Width. |
| Does not reset (turn off yourself) | Bold, DoubleHeight, DoubleWidth and text justification. |
NOTE: Bold, DoubleHeight, DoubleWidth and justification do not reset when a label is cut. This is a known gap. Until it is addressed, turn off every style you turned on before you finish the label, or at the very start of the next script if you cannot guarantee what ran before it.
9. Recipes
Each recipe is a self-contained, tested building block. Copy the functions you need into your script. Examples assume the helper list(c) that returns c ? Array.from(c) : [].
9.1 Reading optional data safely
Guard every value that can be missing: Order.Customer, Order.Delivery, ItemGroups, Employee.DisplayName and any collection.
Safe reads
function safeReads() {
var customerName = Order.Customer && Order.Customer.FirstName
? Order.Customer.FirstName
: "Guest";
var city = Order?.Delivery?.Address?.City ?? "";
var items = Order.Items ? Array.from(Order.Items) : [];
var employee = Order.Employee.DisplayName == null
? Order.Employee.FirstName + " " + Order.Employee.LastName
: Order.Employee.DisplayName;
return [customerName, city, items.length, employee];
}
9.2 Dates and times
Two approaches work. PrintHelper formats in the register's local culture. Manual formatting gives a fixed layout that does not depend on the machine culture. Both accept a Date or a parseable string.
Manual date and time formatting
function formatDate(value) {
var d = new Date(value);
return (d.getMonth() + 1) + "/" + d.getDate() + "/" + d.getFullYear();
}
function formatTime(value) {
var d = new Date(value);
var hours = d.getHours();
var minutes = String(d.getMinutes()).padStart(2, "0");
var ampm = hours >= 12 ? "PM" : "AM";
return (hours % 12 || 12) + ":" + minutes + " " + ampm;
}
9.3 Money and totals
-
Format money yourself with
"\$" + value.toFixed(2). Production scripts moved away fromPrintHelper.ConvertDecimalToCurrencyStringafter it printed the wrong currency symbol on a machine with a different culture. -
A line total is
item.Quantity * item.PriceWithModifiers.PriceWithModifiersis the unit price including modifiers, so printing modifier prices separately double-counts. -
Show discounts with a minus sign and surcharges with a plus sign, taking the absolute value of the stored amount.
-
Print the Rounding line only when it is not zero, with its sign.
-
Derive the bottom line from
Order.Balance: positive is balance due, negative is change due (print the absolute value).
Balance and change
function printBalance() {
if (Order.Balance > 0) {
PrintJob.AddLeftAndRightLine("BALANCE DUE", "$" + Order.Balance.toFixed(2));
} else if (Order.Balance < 0) {
PrintJob.AddLeftAndRightLine("CHANGE DUE", "$" + Math.abs(Order.Balance).toFixed(2));
}
}
9.4 Columns, truncation and wrapping
PrintJob.Wrap has no effect, and long text can overflow the line. Truncate or wrap yourself, using the width of the target printer.
Word wrap
function wrapText(text, width) {
var words = String(text || "").split(" ");
var lines = [];
var line = "";
words.forEach(function (word) {
if ((line + " " + word).trim().length > width) {
if (line) { lines.push(line); }
line = word;
} else {
line = (line + " " + word).trim();
}
});
if (line) { lines.push(line); }
return lines;
}
Fixed columns
function padRight(text, width) {
return String(text).substring(0, width).padEnd(width, " ");
}
function padLeft(text, width) {
return String(text).substring(0, width).padStart(width, " ");
}
9.5 Modifiers, sub-modifiers and combos
A modifier can contain modifiers, and a combo item contains child items that have their own modifiers. A small recursive function handles any depth. In a receipt script, print only top-level items (CompositeOrderItemId == 0) and render the children through CompositeOrderItems.
Recursive modifiers
function printModifiers(modifiers, level) {
(modifiers ? Array.from(modifiers) : []).forEach(function (mod) {
PrintJob.AddLine(" ".repeat(level * 3) + mod.Description);
printModifiers(mod.Modifiers, level + 1);
});
}
9.6 Consolidating duplicate items
When the same item is rung in on several lines, you may want one line with the summed quantity. Key the merge on everything that must match: the menu item, unit price, note and modifiers.
Consolidate identical items
function itemKey(item) {
var mods = list(item.Modifiers)
.map(function (m) { return m.ItemId + ":" + m.Price; })
.sort()
.join(",");
return [item.ItemId, item.PriceWithModifiers, item.Note || "", mods].join("|");
}
function consolidate(items) {
var byKey = {};
var result = [];
items.forEach(function (item) {
var key = itemKey(item);
if (byKey[key]) {
byKey[key].Quantity += item.Quantity;
} else {
byKey[key] = Object.assign({}, item); // copy so the original is untouched
result.push(byKey[key]);
}
});
return result;
}
WARNING:Merging by ItemId alone combines a plain burger with one that has extra cheese and prints the first entry's modifiers for both. Include the modifier set in the key, as above. Combo items should also compare their children.
9.7 Customer-facing helpers
Phone number, short order number, display name
function formatPhone(raw) {
var digits = String(raw || "").replace(/\D/g, "");
var m = digits.match(/^(\d{3})(\d{3})(\d{4})$/);
return m ? "(" + m[1] + ") " + m[2] + "-" + m[3] : String(raw || "");
}
function shortOrderNumber(id) {
var s = String(id);
return s.slice(Math.max(0, s.length - 4));
}
// "Name|extra" -> "Name", at most 20 characters
function displayName(name) {
var s = String(name || "");
var i = s.indexOf("|");
return s.substring(0, i === -1 ? Math.min(20, s.length) : Math.min(i, 20));
}
9.8 Tenders and payment details
There is no tender type property. Infer the kind from the fields that are present, and print card details only for tenders that have them. Card numbers are already masked.
Infer the tender kind
function tenderKind(t) {
if (t.CheckNumber != null) return "check";
if (t.AccountNumber != null) return "house account";
if (t.BalanceRemaining != null) return "gift card";
if (t.CardNumber != null) return "card";
return "other";
}
9.9 Delivery orders
Check Order.Destination.IsDelivery before reading Order.Delivery. Use the delivery phone number for delivery orders, skip placeholder values in the second address line, and print customer or delivery notes when present.
Delivery header
function printDeliveryHeader() {
if (!Order.Destination.IsDelivery) {
return;
}
var address = Order.Delivery.Address;
var line2 = address.Address2 ? address.Address2.trim() : "";
var promise = new Date(Order.PromiseTime);
PrintJob.Bold = true;
PrintJob.DoubleHeight = true;
PrintJob.AddCenteredLine("Delivery Order");
PrintJob.AddCenteredLine(address.Address1.trim());
if (line2 && line2 !== "APT" && line2 !== "NON") { // skip placeholder values
PrintJob.AddCenteredLine(line2);
}
PrintJob.AddCenteredLine(address.City + ", " + address.State + " " + address.PostalCode);
PrintJob.AddCenteredLine("Requested: " + (promise.getFullYear() > 0
? formatDate(promise) + " " + formatTime(promise)
: "ASAP"));
PrintJob.DoubleHeight = false;
PrintJob.Bold = false;
if (address.Notes && address.Notes.trim().length > 0) {
PrintJob.AddLine("Notes: " + address.Notes.trim());
}
PrintJob.AddFilledLine("-");
}
9.10 Grouping items by item group
Group a chit by station with the first item group as the heading. Items can have no group, so supply a default. A centered banner such as ---- Entrees: 3 ---- helps kitchen staff scan the ticket.
Banner line
function banner(label, width) {
if (label.length >= width) { return label.substring(0, width); }
var left = Math.floor((width - label.length) / 2);
return "-".repeat(left) + label + "-".repeat(width - label.length - left);
}
The banner is only the heading. To build the whole grouped chit, bucket the items first, merge identical lines inside each bucket (same description and same modifiers), then print one banner per group followed by its items. The centered, double-size item lines and the closing item count are a common kitchen layout. DoubleWidth halves the characters per line, so keep the banner width at the normal line width.
Group, merge and print (uses list() and banner() from this section)
function groupItems(items) {
var groups = {};
items.forEach(function (item) {
var g = list(item.ItemGroups);
var name = g.length > 0 ? g[0].Name : "Other"; // never assume ItemGroups[0]
if (!groups[name]) { groups[name] = { items: [], total: 0 }; }
// same description + same modifiers = same line
var mods = list(item.Modifiers).map(function (m) { return m.Description; }).join(",");
var key = item.Description + "|" + mods;
var existing = groups[name].items.find(function (i) { return i.key === key; });
if (existing) {
existing.Quantity += item.Quantity;
} else {
groups[name].items.push(Object.assign({}, item, { key: key }));
}
groups[name].total += item.Quantity;
});
return groups;
}
function printGrouped(items) {
var groups = groupItems(items);
var total = 0;
Object.keys(groups).forEach(function (name) {
PrintJob.AddNewLine();
PrintJob.AddCenteredLine(banner(name + ": " + groups[name].total, 42));
PrintJob.AddNewLine();
groups[name].items.forEach(function (item) {
PrintJob.DoubleHeight = true;
PrintJob.DoubleWidth = true;
PrintJob.AddCenteredLine(item.Quantity + " " + item.Description);
PrintJob.DoubleWidth = false;
PrintJob.DoubleHeight = false;
list(item.Modifiers).forEach(function (m) { PrintJob.AddCenteredLine(m.Description); });
});
total += groups[name].total;
});
PrintJob.AddNewLine();
PrintJob.AddCenteredLine("Total Items: " + total);
}
NOTE: This groups by the first item group only. If an item can belong to several groups, decide which one drives its placement before adopting the pattern. Sorting by item group is not guaranteed by the product; rely on SortPriority for order.
9.11 Highlighting edited items
IsEdited marks an item changed after it was sent to the kitchen. Mark such items when a chit is reprinted.
Edit marker
function printWithEditMarker(items) {
items.forEach(function (item) {
var tag = item.IsEdited ? "[EDITED]" : "[NEW] ";
PrintJob.AddLine(tag + " " + item.Quantity + "x " + item.Description);
});
}
TIP: IsEdited is a plain boolean once reached. To guard against a register version where the field is not populated, check typeof item.IsEdited !== "undefined" before relying on it.
9.12 Barcodes, QR codes and stored images
-
AddBarCode(data, symbology)supports Code39, Ean13 and UPCA, but each printer supports a different subset. Pass the symbology name as a string and confirm the accepted form for your build in preview. -
AddQRCode(data, moduleSize)works on Epson, OPOS and Brother, and is a no-op on Star, NCR, PAR M3876, Partner and PosForDotNet. -
AddImage(id)prints an image that is already stored in the printer's NVRAM, by its image number. Upload the image through the supported printer process first. It throws on several printers. -
Always scan-test the physical output.
Barcode, QR code and stored logo
function printCodes() {
PrintJob.AddBarCode(String(Order.Number), "Code39");
PrintJob.AddQRCode("https://example.com/orders/" + Order.Id, 4);
PrintJob.AddImage(1);
}
10. Complete example scripts
The scripts below are complete and tested against the engine rules (restricted words, strict mode, top-level declarations, required functions). Run each in preview first, then on the target printer. Replace store-specific values such as item group ids with your own.
NOTE: The "Representative output" blocks were produced by running each script against its preview data with a 42-column text renderer. They show the intended layout. Fonts, widths, red and reverse printing depend on your printer.
10.1 Receipt
A full receipt: store header, order information, items with modifiers and combo children, voided items, discounts, surcharges, tax, rounding, total, tenders with tip and card details, and balance or change due. It assumes a standard 42-column thermal printer and does not call AddCut.
Script 2: reference receipt
/*
* Reference receipt script (Receipt script)
* - Receipt scripts receive Order, Store, PrintJob and PrintHelper.
* There is no Printer object in a receipt script.
* - Do not call AddCut(); the receipt is fed and cut automatically after the script.
*/
function setupPreviewData() {
Store.Id = "1234";
Store.Name = "PAR Burger";
Store.Address1 = "123 Main Street";
Store.City = "Syracuse";
Store.State = "NY";
Store.Zip = "13202";
Store.Phone = "315-555-0100";
Order.Id = "AAAE6LTF9QAE";
Order.Number = 312;
Order.Name = "Melissa";
Order.CreatedDate = new Date("2026-10-08T17:32:22Z");
Order.Employee = { DisplayName: "Sam K" };
Order.Destination = { Name: "Counter - Dine In", IsDelivery: false };
Order.Customer = null;
Order.Items = [
{
Voided: false, IsDeleted: false,
CompositeOrderItemId: 0, CompositeOrderItems: [],
Quantity: 2, Description: "Cheeseburger", Price: 7.50, PriceWithModifiers: 8.50,
Modifiers: [
{ Description: "Extra Cheese", Price: 1.00, Modifiers: [] },
{ Description: "No Onion", Price: 0, Modifiers: [] }
]
},
{
Voided: false, IsDeleted: false, CompositeOrderItemId: 0, Quantity: 1,
Description: "Value Basket", Price: 9.99, PriceWithModifiers: 9.99,
Modifiers: [],
CompositeOrderItems: [
{ Quantity: 1, Description: "Fries MED", Price: 0, PriceWithModifiers: 0,
Modifiers: [{ Description: "Extra Salt", Modifiers: [] }] },
{ Quantity: 1, Description: "Root Beer MED", Price: 0, PriceWithModifiers: 0,
Modifiers: [] }
]
},
{
Voided: true, IsDeleted: false,
CompositeOrderItemId: 0, CompositeOrderItems: [],
Quantity: 1, Description: "Hot Dog", Price: 3.00, PriceWithModifiers: 3.00,
Modifiers: []
}
];
Order.Discounts = [
{ PrintedName: "Employee Meal", Name: "Employee Meal", Amount: 2.00 }
];
Order.Promotions = [];
Order.Surcharges = [{ Name: "Service Fee", Amount: 1.00 }];
Order.SubTotal = 26.99;
Order.Tax = 2.02;
Order.Rounding = 0;
Order.Total = 28.01;
Order.Balance = 0;
Order.Tenders = [{
Name: "Visa", Amount: 28.01, TipAmount: 3.00, CardNumber: "************1111",
Authorization: "A2B45", AuthorizedTenderAmount: 31.01
}];
}
/* ---------- helpers ---------- */
function money(value) {
return "$" + Number(value || 0).toFixed(2);
}
function formatDateTime(value) {
// Works for a production DateTime (arrives as a JS Date) and for preview strings.
var iso = new Date(value).toISOString();
return PrintHelper.GetShortDate(iso) + " " + PrintHelper.GetShortTime(iso);
}
function list(collection) {
// Null-safe copy of a collection into a real array.
return collection ? Array.from(collection) : [];
}
function printModifiers(modifiers, level) {
list(modifiers).forEach(function (mod) {
PrintJob.Red = true;
PrintJob.AddLine(" ".repeat(level * 3) + mod.Description);
PrintJob.Red = false;
printModifiers(mod.Modifiers, level + 1); // sub-modifiers
});
}
function printItem(item, isVoid) {
var total = item.Quantity * item.PriceWithModifiers;
var label = item.Quantity + " " + (isVoid ? "VOID " : "") + item.Description;
var price = isVoid ? "(" + money(total) + ")" : (total > 0 ? money(total) : "");
PrintJob.AddLeftAndRightLine(label.substring(0, 32), price);
list(item.CompositeOrderItems).forEach(function (child) {
PrintJob.AddLine(" " + child.Quantity + " " + child.Description);
printModifiers(child.Modifiers, 2);
});
printModifiers(item.Modifiers, 1);
}
/* ---------- print ---------- */
function print() {
var items = list(Order.Items).filter(function (i) {
return i.CompositeOrderItemId == 0 && !i.IsDeleted; // top-level items only
});
var active = items.filter(function (i) { return !i.Voided; });
var voided = items.filter(function (i) { return i.Voided; });
// Header
PrintJob.Bold = true;
PrintJob.DoubleHeight = true;
PrintJob.AddCenteredLine(Store.Name + " #" + Store.Id);
PrintJob.DoubleHeight = false;
PrintJob.Bold = false;
PrintJob.AddCenteredLine(Store.Address1);
PrintJob.AddCenteredLine(Store.City + ", " + Store.State + " " + Store.Zip);
PrintJob.AddCenteredLine(Store.Phone);
PrintJob.AddNewLine();
// Order information
PrintJob.AddLine(formatDateTime(Order.CreatedDate));
PrintJob.AddLine("Destination: " + (Order.Destination ? Order.Destination.Name : ""));
PrintJob.AddLine("Order: " + Order.Number + (Order.Name ? " " + Order.Name : ""));
PrintJob.AddLine("Server: " + (Order.Employee ? Order.Employee.DisplayName : ""));
if (Order.Customer) {
PrintJob.AddLine("Customer: " + Order.Customer.FullName);
}
PrintJob.AddFilledLine("-");
// Items
active.forEach(function (item) { printItem(item, false); });
if (voided.length > 0) {
PrintJob.AddNewLine();
PrintJob.Bold = true;
PrintJob.AddCenteredLine("VOIDED ITEMS");
PrintJob.Bold = false;
voided.forEach(function (item) { printItem(item, true); });
}
PrintJob.AddFilledLine("-");
// Totals
PrintJob.AddLeftAndRightLine("Subtotal", money(Order.SubTotal));
list(Order.Discounts).forEach(function (d) {
PrintJob.AddLeftAndRightLine(d.PrintedName || d.Name, "-" + money(d.Amount));
});
list(Order.Promotions).forEach(function (p) {
PrintJob.AddLeftAndRightLine(p.PrintedName || p.Name, "-" + money(p.Amount));
});
list(Order.Surcharges).forEach(function (s) {
PrintJob.AddLeftAndRightLine(s.Name, "+" + money(s.Amount));
});
PrintJob.AddLeftAndRightLine("Tax", money(Order.Tax));
if (Order.Rounding != 0) {
var sign = Order.Rounding > 0 ? "+" : "-";
PrintJob.AddLeftAndRightLine("Rounding", sign + money(Math.abs(Order.Rounding)));
}
PrintJob.Bold = true;
PrintJob.AddLeftAndRightLine("TOTAL", money(Order.Total));
PrintJob.Bold = false;
// Tenders
list(Order.Tenders).forEach(function (t) {
PrintJob.AddLeftAndRightLine(t.Name, money(t.Amount));
if (t.TipAmount > 0) {
PrintJob.AddLeftAndRightLine(" Tip", money(t.TipAmount));
}
if (t.CardNumber) { // card tenders only
PrintJob.AddRightLine("Card: " + t.CardNumber);
if (t.Authorization) {
PrintJob.AddRightLine("Auth: " + t.Authorization);
}
}
});
// Balance / change
if (Order.Balance > 0) {
PrintJob.Bold = true;
PrintJob.AddLeftAndRightLine("BALANCE DUE", money(Order.Balance));
PrintJob.Bold = false;
} else if (Order.Balance < 0) {
PrintJob.AddLeftAndRightLine("CHANGE DUE", money(Math.abs(Order.Balance)));
}
PrintJob.AddNewLine();
PrintJob.AddCenteredLine("Thank you for your visit!");
}
Representative output
PAR Burger #1234
123 Main Street
Syracuse, NY 13202
315-555-0100
10/8/2026 5:32 PM
Destination: Counter - Dine In
Order: 312 Melissa
Server: Sam K
------------------------------------------
2 Cheeseburger $17.00
Extra Cheese
No Onion
1 Value Basket $9.99
1 Fries MED
Extra Salt
1 Root Beer MED
VOIDED ITEMS
1 VOID Hot Dog ($3.00)
------------------------------------------
Subtotal $26.99
Employee Meal -$2.00
Service Fee +$1.00
Tax $2.02
TOTAL $28.01
Visa $28.01
Tip $3.00
Card: ************1111
Auth: A2B45
Thank you for your visit!
10.2 Kitchen chit
A chit that adapts to Printer.ChitType: summary chits group items by item group, single and bag chits print items as listed. It shows a future-order banner, edited-item markers, notes and the chit position, and ends with AddCut(85).
Script 3: reference kitchen chit
/*
* Reference kitchen chit script (Chit script)
* - Chit scripts receive Order, Printer, Store, PrintJob and PrintHelper.
* - Printer.ChitType is "SummaryChit", "SingleChit" or "Bag".
* SingleChit: the script runs once per item and Order.Items holds exactly that one item.
* SummaryChit: the script runs once per printer with that printer's items.
* Bag: the script runs once.
* - Chit scripts end the ticket themselves with AddCut(85).
*/
function setupPreviewData() {
Printer.Name = "Grill";
Printer.ChitType = "SummaryChit";
Printer.ChitCurrentIndex = 1;
Printer.TotalChits = 1;
Order.Number = 312;
Order.Name = "Melissa";
Order.IsFutureOrder = true;
Order.PromiseTime = new Date("2026-10-08T18:30:00Z");
Order.Destination = {
Name: "Drive Thru", KitchenChitHeader: "DRIVE THRU", IsDelivery: false
};
Order.Items = [
{
Quantity: 1, Description: "WHOPPER", SortPriority: 2, IsEdited: false, Note: "",
ItemGroups: [{ Id: 1, Name: "Entrees" }],
CompositeOrderItems: [],
Modifiers: [{ Description: "NO PICKLES" }, { Description: "ADD ONION" }]
},
{
Quantity: 2, Description: "FRIES MED", SortPriority: 3,
IsEdited: true, Note: "Well done",
ItemGroups: [], CompositeOrderItems: [], Modifiers: []
},
{
Quantity: 1, Description: "OREO SHAKE", SortPriority: 4,
IsEdited: false, Note: "",
ItemGroups: [{ Id: 2, Name: "Drinks" }], CompositeOrderItems: [], Modifiers: []
}
];
}
function list(collection) {
return collection ? Array.from(collection) : [];
}
function groupName(item) {
var groups = list(item.ItemGroups);
// never assume ItemGroups[0] exists
return groups.length > 0 ? groups[0].Name : "Other";
}
function printItem(item) {
PrintJob.Bold = true;
PrintJob.DoubleHeight = true;
var tag = item.IsEdited ? "[EDIT] " : "";
PrintJob.AddLine(tag + item.Quantity + " " + item.Description);
PrintJob.DoubleHeight = false;
PrintJob.Bold = false;
list(item.CompositeOrderItems).forEach(function (child) {
PrintJob.AddLine(" " + child.Quantity + " " + child.Description);
});
list(item.Modifiers).forEach(function (mod) {
PrintJob.AddLine(" " + mod.Description);
});
if (item.Note) {
PrintJob.AddLine(" NOTE: " + item.Note);
}
}
function print() {
var chitType = Printer.ChitType;
var items = list(Order.Items).sort(function (a, b) {
return a.SortPriority - b.SortPriority;
});
// Header
PrintJob.Bold = true;
PrintJob.Reverse = true;
PrintJob.AddCenteredLine(Order.Destination.KitchenChitHeader || Order.Destination.Name);
PrintJob.Reverse = false;
PrintJob.DoubleHeight = true;
PrintJob.AddCenteredLine("#" + Order.Number + " " + (Order.Name || ""));
PrintJob.DoubleHeight = false;
PrintJob.Bold = false;
if (Order.IsFutureOrder) {
var promise = new Date(Order.PromiseTime).toISOString();
PrintJob.AddCenteredLine("FUTURE - " + PrintHelper.GetShortDate(promise)
+ " " + PrintHelper.GetShortTime(promise));
}
PrintJob.AddLeftAndRightLine(
Printer.Name, "Chit " + Printer.ChitCurrentIndex + " of " + Printer.TotalChits);
PrintJob.AddFilledLine("-");
// Body
if (chitType == "SummaryChit") {
var current = "";
items.forEach(function (item) {
var group = groupName(item);
if (group !== current) {
current = group;
PrintJob.AddCenteredLine("-- " + group + " --");
}
printItem(item);
});
} else {
items.forEach(printItem); // SingleChit and Bag: no grouping
}
PrintJob.AddNewLine();
PrintJob.AddCut(85);
}
Representative output (SummaryChit, 40-column printer)
DRIVE THRU
#312 Melissa
FUTURE - 10/8/2026 6:30 PM
Grill Chit 1 of 1
----------------------------------------
-- Entrees --
1 WHOPPER
NO PICKLES
ADD ONION
-- Other --
[EDIT] 2 FRIES MED
NOTE: Well done
-- Drinks --
1 OREO SHAKE
------- CUT -------
For a SingleChit run, Order.Items contains exactly one item, so the same script prints one item per ticket.
10.3 Boxed-item labels
Some items, such as whole pizzas or boxed chicken, print as their own label rather than as a line on the main chit. This pattern identifies boxed items by an item group, merges identical items, prints one label per unit (or one consolidated "12x" label from a threshold), and footers each label with "Box X of Y". Tag the menu items with a dedicated item group and replace IG_BOXED with its id.
Script 4: boxed-item labels
/*
* Boxed-item labels (Chit script, SummaryChit).
* Items in the "boxed" item group print as their own label ("Box X of Y");
* everything else is left for the normal chit.
* Replace the item group id with the one configured in your menu.
*/
var IG_BOXED = 673549520;
// From this quantity up, print one "12x" label instead of 12 labels
var CONSOLIDATE_AT = 10;
function setupPreviewData() {
Printer.Name = "Box Station";
Printer.ChitType = "SummaryChit";
Order.Number = 312;
Order.Name = "Melissa";
Order.Items = [
{ ItemId: 1, Description: "Cheese Pizza", AlternateKitchenName: "CHEESE PIZZA",
Quantity: 1, ItemGroups: [{ Id: IG_BOXED, Name: "Boxed" }],
Modifiers: [{ Description: "Light Sauce", ItemId: 50 }] },
{ ItemId: 1, Description: "Cheese Pizza", AlternateKitchenName: "CHEESE PIZZA",
Quantity: 1, ItemGroups: [{ Id: IG_BOXED, Name: "Boxed" }],
Modifiers: [{ Description: "Light Sauce", ItemId: 50 }] },
{ ItemId: 2, Description: "Wings", AlternateKitchenName: "WINGS",
Quantity: 12, ItemGroups: [{ Id: IG_BOXED, Name: "Boxed" }], Modifiers: [] },
{ ItemId: 3, Description: "Soda", AlternateKitchenName: "SODA",
Quantity: 1, ItemGroups: [], Modifiers: [] }
];
}
function list(c) { return c ? Array.from(c) : []; }
function hasItemGroup(item, groupId) {
return list(item.ItemGroups).some(function (g) { return g.Id == groupId; });
}
function modifiersEqual(a, b) {
var left = list(a).map(function (m) { return m.ItemId; }).sort().join(",");
var right = list(b).map(function (m) { return m.ItemId; }).sort().join(",");
return left === right;
}
function mergeBoxed(items) {
var merged = [];
var candidates = items.filter(function (i) { return hasItemGroup(i, IG_BOXED); });
candidates.forEach(function (item) {
var match = merged.find(function (m) {
return m.ItemId === item.ItemId && modifiersEqual(m.Modifiers, item.Modifiers);
});
if (match) {
match.Quantity += item.Quantity;
} else {
merged.push(Object.assign({}, item));
}
});
return merged;
}
function print() {
var boxed = mergeBoxed(list(Order.Items));
var totalBoxes = boxed.reduce(function (sum, i) { return sum + i.Quantity; }, 0);
var boxNumber = 1;
boxed.forEach(function (item) {
var consolidated = item.Quantity >= CONSOLIDATE_AT;
var labels = consolidated ? 1 : item.Quantity;
for (var n = 0; n < labels; n++) {
PrintJob.Bold = true;
PrintJob.AddCenteredLine("#" + Order.Number + " " + (Order.Name || ""));
PrintJob.DoubleHeight = true;
var prefix = consolidated ? item.Quantity + "x " : "";
PrintJob.AddCenteredLine(prefix + item.AlternateKitchenName);
PrintJob.DoubleHeight = false;
PrintJob.Bold = false;
list(item.Modifiers).forEach(function (m) {
PrintJob.AddCenteredLine(m.Description);
});
if (consolidated) {
var last = boxNumber + item.Quantity - 1;
PrintJob.AddRightLine("Boxes " + boxNumber + "-" + last + " of " + totalBoxes);
boxNumber += item.Quantity;
} else {
PrintJob.AddRightLine("Box " + boxNumber + " of " + totalBoxes);
boxNumber += 1;
}
PrintJob.AddCut(85);
}
});
}
Representative output
#312 Melissa
CHEESE PIZZA
Light Sauce
Box 1 of 14
------- CUT -------
#312 Melissa
CHEESE PIZZA
Light Sauce
Box 2 of 14
------- CUT -------
#312 Melissa
12x WINGS
Boxes 3-14 of 14
------- CUT -------
Box types and add-on lines
Script 4 merges on ItemId plus modifiers. To also merge items that share a kitchen name, accept a match on AlternateKitchenName as well. Beyond the boxed-item group itself, extra item groups or modifier ids can describe the box (size or type) and trigger add-on lines such as wedge-cut instructions, a seasoning packet or pepperoncini. The constants below are examples from one store's menu; substitute the item group and modifier ids from your own setup.
| Example constant | Represents |
|---|---|
| IG_Box8 / IG_Box10 / IG_Box12 | Box size (8", 10" or 12") to print on the label. |
| IG_BoxChicken / IG_BoxSandwich | Box type label ("CHICKEN BOX", "Sandwich Box"). |
| IG_NYS | Flags an item that needs wedge-cut instructions (for example New York style pizza). |
| IG_ITSeasoning | Flags an item that needs an "IT Seasoning" add-on line. |
| IG_AllPizzas / IG_ThinPizzas | Flags pizza items, and thin-crust pizza items specifically, for their respective add-on lines. |
| IG_AllSandwiches | Flags sandwich items for their add-on line. |
| I_GESC | A specific modifier ItemId checked with a helper hasItemModifier rather than an item group. |
Add-on lines (sketch, call from the label loop in Script 4)
// Replace the zeros with the ids configured in your menu.
var IG_BOX8 = 0, IG_BOX10 = 0, IG_BOX12 = 0, IG_NYS = 0, IG_SEASONING = 0;
function hasItemModifier(item, modifierItemId) {
return list(item.Modifiers).some(function (m) { return m.ItemId == modifierItemId; });
}
function printBoxLines(item) {
if (hasItemGroup(item, IG_BOX8)) { PrintJob.AddCenteredLine('8" box'); }
if (hasItemGroup(item, IG_BOX10)) { PrintJob.AddCenteredLine('10" box'); }
if (hasItemGroup(item, IG_BOX12)) { PrintJob.AddCenteredLine('12" box'); }
if (hasItemGroup(item, IG_NYS)) { PrintJob.AddCenteredLine("WEDGE CUT"); }
if (hasItemGroup(item, IG_SEASONING)) { PrintJob.AddCenteredLine("IT SEASONING"); }
}
TIP: Run the boxed-items pass before printing the regular chit, and exclude any item already claimed by the boxed-items group from that regular chit. Otherwise the item prints once as a label and again as a chit line.
10.4 Brother delivery label
A horizontal 812 by 309 dot label with nested borders, a reversed address banner, vertical side tags, an anchored totals block and a footer. It exercises orientation, cursor, fixed positions, boxes and the reset rules. Run it on a Brother label printer only.
Script 5: Brother delivery label
/*
* Delivery label for a Brother label printer (Chit script, horizontal label with
* vertical side tags). All positions are in printer dots. Run it on a
* Brother printer only; thermal receipt printers ignore the positioning calls.
*/
function setupPreviewData() {
Store.Name = "Store 5QR4";
Order.Name = "David Bratcher";
Order.Number = 12;
Order.PromiseTime = new Date(2026, 9, 8, 14, 20);
Order.Delivery = {
PhoneNumber: "(502)281-4877",
Address: { Address1: "123 Main Street", Address2: "Apt 4" }
};
Order.SubTotal = 87.06;
Order.Tax = 6.09;
Order.Total = 93.15;
}
function money(v) { return "$" + Number(v || 0).toFixed(2) + " "; }
function timeText(date) {
var d = new Date(date);
var h = d.getHours();
var ampm = h >= 12 ? "pm" : "am";
var hh = String(h % 12 || 12).padStart(2, "0");
var mm = String(d.getMinutes()).padStart(2, "0");
return hh + ":" + mm + ampm;
}
function print() {
var addr = Order.Delivery && Order.Delivery.Address ? Order.Delivery.Address : {};
PrintJob.Orientation = 1; // set orientation first (it carries over)
PrintJob.SetCursorPosition(0, 0); // top-left corner
PrintJob.AddBox(812, 309, 2); // outer border
PrintJob.MoveCursorPosition(35, 0);
PrintJob.AddBox(746, 277, 2); // inner border
PrintJob.AddBox(350, 277, 2); // left-side divider
PrintJob.AddBox(746, 240, 2);
PrintJob.AddBox(746, 100, 2); // lower section
PrintJob.AddBox(646, 100, 2);
PrintJob.AddBox(681, 35, 35); // thickness = height: a solid bar
PrintJob.Reverse = true; // white text on the solid bar
PrintJob.AddLine(addr.Address1 || "");
PrintJob.SetCursorPosition(778, 0);
PrintJob.Reverse = false;
PrintJob.AddBox(35, 35, 2); // corner mark
PrintJob.MoveCursorPosition(10, 10);
PrintJob.AddLine("C");
PrintJob.MoveCursorPosition(28, -12);
PrintJob.FixXPosition = true; // anchor X for the next line
PrintJob.Reverse = true;
PrintJob.AddLeftAndRightLine(addr.Address2 || "", "");
PrintJob.Reverse = false;
PrintJob.FixXPosition = false; // release the anchor
PrintJob.SetCursorPosition(43, 75);
PrintJob.AddLine(Order.Name);
PrintJob.SetCursorPosition(388, 75);
PrintJob.AddLine(Order.Delivery.PhoneNumber);
PrintJob.SetCursorPosition(658, 75);
PrintJob.AddLine(timeText(Order.PromiseTime));
PrintJob.SetCursorPosition(8, 10); // vertical tag, left column
PrintJob.Orientation = 2;
PrintJob.FixYPosition = true;
PrintJob.AddLeftAndRightLine(String(Order.Number).padStart(4, "0"), "5 box(es) ");
PrintJob.Orientation = 1;
PrintJob.SetCursorPosition(780, 65); // vertical tag, right column
PrintJob.Orientation = 2;
PrintJob.Reverse = true;
PrintJob.FixYPosition = true;
PrintJob.AddLeftAndRightLine("P", " " + String(Order.Number).padStart(4, "0") + " ");
PrintJob.FixYPosition = false;
PrintJob.Reverse = false;
PrintJob.Orientation = 1;
PrintJob.SetCursorPosition(388, 108); // totals block
PrintJob.FixXPosition = true;
PrintJob.AddLeftAndRightLine("Sub-Total", money(Order.SubTotal));
PrintJob.AddLeftAndRightLine("Sales Tax", money(Order.Tax));
PrintJob.Bold = true;
PrintJob.AddLeftAndRightLine("TOTAL", money(Order.Total));
PrintJob.Bold = false; // AddCut does not reset Bold
PrintJob.FixXPosition = false;
PrintJob.AddLeftAndRightLine(" THANKS FOR ORDERING", "DOWNLOAD OUR APP ");
PrintJob.AddCut(85); // ends and cuts the label
}
What the script draws
| Element | How it is drawn |
|---|---|
| Outer and inner border | SetCursorPosition(0, 0) then AddBox(812, 309, 2); a move of 35 dots, then a nested AddBox(746, 277, 2). |
| Solid address bar | AddBox(681, 35, 35): thickness equals height, so it fills. Reverse = true prints the address in white on it. |
| Corner mark | A 35 by 35 box at the top right with the letter "C" nudged inside using MoveCursorPosition(10, 10). |
| Customer, phone, time row | Three SetCursorPosition calls on the same row (y = 75). |
| Vertical side tags | Orientation = 2 with FixYPosition anchoring each pair, then Orientation = 1 to return to horizontal. |
| Totals block | FixXPosition = true so every row starts at the same left edge; Bold is switched off before the label is cut. |
10.5 Vertical pizza-box label
A Brother label with an outer border, a "C" corner mark, a vertical "P / 0006" order tag, three reversed pizza-description columns, a plain divider, a box spanning back to the label edge, a vertical "SIDES:" block, a vertical box-count tag and a reversed customer-address footer back in horizontal mode. Comments are on the lines that use orientation, anchors, cursor movement and boxes. Add a setupPreviewData() to run it in preview, and run it on a Brother label printer only.
Script 6: vertical pizza-box label
function print() {
PrintJob.SetCursorPosition(0, 0); // jump to the label's top-left corner
PrintJob.AddBox(812, 307, 2); // outer border for the whole label
PrintJob.MoveCursorPosition(777, 0); // move to the right edge for the corner box
PrintJob.AddBox(35, 35, 2); // small callout box
PrintJob.MoveCursorPosition(10, 10); // move inside the callout box
PrintJob.AddLine("C");
PrintJob.MoveCursorPosition(770, -10); // move to where the vertical tag will start
PrintJob.Orientation = 2; // switch to Vertical; keeps the current position
PrintJob.Reverse = true;
PrintJob.FixYPosition = true; // anchor for the "P" / "0006" pair
PrintJob.AddLeftAndRightLine("P", "0006");
PrintJob.MoveCursorPosition(0, -35); // move along the label's length before the next section
PrintJob.FixYPosition = false; // release the anchor
PrintJob.Reverse = false;
PrintJob.AddLeftAndRightLine('14" ORIGINAL', " ");
PrintJob.Reverse = true; // black background for the next three lines
PrintJob.AddLeftAndRightLine("# G-PARM SWIRL", " ");
PrintJob.AddLeftAndRightLine("# CLEAN CUT", " ");
PrintJob.AddLeftAndRightLine("# SQUADERE CUT", " ");
PrintJob.Reverse = false;
PrintJob.AddLeftAndRightLine("HAWAIIAN BBQ Chicken", "");
PrintJob.MoveCursorPosition(30, -8); // move past the last column before the divider
PrintJob.AddBox(2, 307, 2); // plain line
PrintJob.AddBoxToAxis(0, 35, 35); // customer address bar: spans back to the label edge without moving the cursor
PrintJob.MoveCursorPosition(0, 40); // move into the SIDES: block
PrintJob.FixYPosition = true; // anchor for the whole SIDES: block
PrintJob.Reverse = false;
PrintJob.AddLine("");
PrintJob.AddLine("SIDES:");
PrintJob.AddLine("");
PrintJob.AddLine("+1 Garlic Sauce");
PrintJob.AddLine("+1 Pepperoncini");
PrintJob.SetCursorPosition(10, 40); // jump to the box-count tag's position
PrintJob.FixYPosition = true; // anchor for the "031126" / "5 of 5" pair
PrintJob.AddLeftAndRightLine("031126", "5 of 5");
PrintJob.Orientation = 1; // back to Horizontal for the footer
PrintJob.SetCursorPosition(8, 0); // jump to the footer's starting position
PrintJob.Reverse = true;
PrintJob.AddLine("Customer Address: 1234");
PrintJob.Reverse = false; // reset styles before the cut
PrintJob.AddCut(85);
}
11. Testing and validation
11.1 Procedure
-
Start in a non-production location or a test changeset.
-
Confirm the feature flag
PARPOS.EnableScriptPrintingConfigurationis enabled for the target group. -
Create the script with a clear name and the correct Document Type.
-
Write
setupPreviewData()with representative values: long names, many modifiers, nested modifiers, combos, voids, discounts, future-order status, delivery data and missing optional fields (a null customer, empty item groups, no tenders). -
Run the preview and resolve every validation error before saving.
-
Assign the script under Options > Printing > Receipt or Chit.
-
Publish the changeset and confirm the register received the updated settings and that the intended printer is configured.
-
Print a physical test on the target printer through the real connection path.
-
Compare the output with the expected layout.
-
Test fallback: disable the feature flag or remove the script selection in a controlled environment and confirm the built-in layout prints.
-
Test failure cases: invalid script, missing optional data, offline printer, unavailable primary printer and an unsupported hardware feature.
11.2 What to verify on paper
| Check | What to look for |
|---|---|
| Line width | No wrapped or truncated lines, including with double width and the longest real item names. |
| Alignment | Left and right columns line up; centered lines are centered. |
| Emphasis | Bold, red, reverse, double height and double width appear as intended, or degrade readably where unsupported. |
| Codes | Barcode and QR code scan reliably at normal distance and contrast. |
| Images | The stored logo prints, with the correct image number. |
| Cut and feed | A receipt is cut exactly once. Chits and labels cut where expected. |
| Item order | Items, modifiers and combo children appear in the expected order and indentation. |
| Totals | Subtotal, discounts, surcharges, tax, rounding and total add up; balance or change due is correct. |
| Multiple chits | Every chit in a multi-chit job carries the right header and chit index. |
| Label state | On labels, nothing (bold, double height or width, justification) leaks from one label to the next. |
12. Troubleshooting and FAQ
12.1 Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| "Script is invalid" in preview | Syntax error, undeclared variable, missing print() or setupPreviewData(), or a restricted word anywhere in the text. |
Read the message. Check capitalization, braces and function names. Search the whole script, comments and strings included, for restricted words. |
| "Identifier ... has already been declared" | A top-level const or let in a script validated for preview. | Use var at top level, or move the declaration into a function. |
| "X is not defined" | Strict mode and an undeclared variable, or Printer referenced in a receipt script. | Declare the variable. Use Printer only in chit scripts. |
| "Script contains disallowed pattern" | A restricted word such as document or window in a comment or string. | Reword it, for example "Script type" instead of "Document type". |
| The old layout prints after publishing | Flag off, no script selected, changeset unpublished, or the script failed and the register fell back silently. | Enable the flag, select the script, publish, refresh register settings, and check the register logs for the script error. |
| Blank output | print() makes no PrintJob calls, or execution failed before output. |
Add PrintJob.AddLine("Test"), validate, then add logic step by step. |
| Prints on the wrong printer | Script selection and printer routing are separate settings. | Review Options > Printing, printer setup, kitchen destination, chit type, queue and connection settings. |
| Chit data is missing | Receipt-only fields used in a chit, or an optional value is absent. | Use chit-only fields only in chit scripts; guard optional properties. |
| Date helper error "not recognized as a valid DateTime" | A Date object passed to PrintHelper. |
Pass new Date(value).toISOString() . |
| AddFilledLine fails | A string of more than one character was passed. | Pass a single character such as "-". To repeat a pattern use "-".repeat(n) with AddLine. |
| Wrong currency symbol | ConvertDecimalToCurrencyString follows the machine culture. |
Build the amount with "\$" + value.toFixed(2). |
| Customer name is missing or errors | Order.Customer is null. |
Check Order.Customer before reading its fields. |
| Text truncated or wraps unexpectedly | Content wider than the printer, or double width in use. | Shorten or split lines, use column methods, and test on the printer. |
| Red or reverse is absent | The printer, ribbon, emulation or driver does not support it. | Confirm hardware and emulation. Provide a readable normal-text fallback. |
| QR code or barcode does not scan, or the script fails | Unsupported symbology or printer, size, quiet zone, or print quality. | Use a supported method and symbology for that printer and test physically. |
| Image does not print | The image is not in printer NVRAM, or the wrong number was used. Some printers throw on AddImage. | Store the image through the supported printer process and use its number with AddImage. |
| Label is rotated or misplaced | Orientation or cursor state carried over, or coordinates were designed for another label size. | Set orientation explicitly at the start, reset styles, and test coordinates in printer dots. |
| Next label starts bold or double height | Bold, DoubleHeight, DoubleWidth or justification are not reset by a cut. |
Turn them off before AddCut . |
| The primary printer is offline | Physical printer or queue failure. | Follow the site's printer failover procedure. A script does not guarantee backup-printer routing. |
12.2 Offline behavior
When the register is offline from above-store services, settings and scripts it has already downloaded can continue to be used, subject to local settings-cache behavior. A script cannot retrieve new data or call external services. If the script is not present locally, settings are stale, or the printer or local queue is unavailable, printing follows the register's existing failure and fallback behavior. Validate offline operation on the target deployment, because caching and queue behavior are environment-specific.
12.3 Frequently asked questions
Does script-based printing replace the existing receipt and chit configuration?
No. When enabled and selected, a script takes precedence. If the flag is disabled, no script is selected or execution fails, the existing Options > Printing configuration is used.
Can I call external APIs from a script?
No. fetch, XMLHttpRequest and similar are restricted, and the sandbox has no network access. A script works only with the data the register supplies (or the preview data).
Can I use one script for both receipts and chits?
Not in practice. Scripts are created and assigned by Document Type, the data differs, and Printer does not exist in receipt scripts.
Do I call AddCut?
In a chit or label script, yes: end with PrintJob.AddCut(85). In a receipt script, no: the receipt is fed and cut automatically.
Why did my receipt silently revert to the old format?
A validation or runtime error returns nothing and the register prints the built-in layout. The error is only in the logs. Re-validate in preview and check the logs.
Is AddBox valid for every printer?
No. The box and cursor commands are for supported Brother label printers. Use AddFilledLine for separators on receipt printers.
Does a script control the backup printer?
Not universally. Script content and physical failover are separate; backup routing depends on printer and queue configuration and must be tested on site.
Which JavaScript features can I use?
Modern syntax supported by Jint 4.1.0, including arrow functions, optional chaining, template literals and padStart. Use var at top level.
How do I print a stored logo?
Store the image in the printer NVRAM through the supported printer process and call PrintJob.AddImage(id) with its image number.
Appendix A. Preview data
Samples for setupPreviewData(). Values are placeholders. In production the register supplies the real objects and never calls setupPreviewData().
A.1 Object shapes
One assignment per nested object of Order, using the members listed in section 6.2. Order.Employee and Order.ClosedByEmployee share the same shape. Collections that hold items (Items, VoidItems, PreviousItems, BagItems, AllItems) share the item shape.
Shared by receipt and chit scripts
function setupPreviewData() {
Order.Customer = { FirstName: "Test", LastName: "Name", FullName: "Test Name", PhoneNumber: "12435456" };
Order.Delivery = {
Address: { Address1: "Address 1", Address2: "Address 2", City: "Test city", State: "Test state", PostalCode: "12345678" },
PhoneNumber: "1243635123"
};
Order.Destination = {
Id: 1, Indicator: "Test indicator", KitchenChitHeader: "TestKitchenHead",
KitchenDescription: "Test description", IsDelivery: true, Name: "Test name"
};
Order.Discounts = [{ PrintedName: "TestPrintedName", Name: "TestName", Amount: 19.68 }];
Order.Employee = { DisplayName: "DisplayTestName", FirstName: "TestFirstName", LastName: "TestLastName", IsTraining: false };
Order.Lane = { Name: "TestLane", Prefix: "TestPrefix" };
Order.MarketingCampaigns = [{ Name: "TestCampaignName" }];
Order.Party = { Name: "TestParty", OrderNumber: 1234 };
Order.Promotions = [{ PrintedName: "TestPromotionDisplayName", Name: "TestPromotionName", Amount: 11.84 }];
Order.Surcharges = [{ Name: "TestSurcharges", Amount: 22.38 }];
Order.Taxes = [{ Name: "TestTaxName", Amount: 14.12 }];
Order.Terminal = { Name: "test" };
Order.Items = [{
Id: 1, ItemId: 1214, Voided: false, IsTaxFree: true, Quantity: 2,
Description: "Amer - Hamburger", Price: 7.5, PriceWithModifiers: 8.5, Note: "Order Notes",
Modifiers: [{ Id: 1, ItemId: 123214, Description: "Extra Cheese", Price: 1.0 }]
}];
}
Chit scripts only
Order.KeyIngredients = [{ Count: 2, Text: "Key ingredient 1" }];
// PreviousItems, BagItems and AllItems all use the item shape. On chits a modifier
// is reduced to Description and ItemId.
Order.PreviousItems = [{
Id: 1, ItemId: 1214, Quantity: 2, Description: "Amer - Hamburger", Price: 7.5,
AutoNumberPrefix: "pref", AutoNumber: 1, Note: "Order Notes",
Modifiers: [{ Description: "Extra Cheese", ItemId: 123214 }]
}];
Receipt scripts only
Order.ReceiptPrintCount = 1;
A.2 Combo and composite items on a chit
Sample data with composite (combo) items. Each combo holds nested CompositeOrderItems, each with its own ItemGroups and Modifiers, next to standalone items that reuse the same menu item ids. Use it to test chit logic, such as the boxed-item pattern in section 10.3, against realistic combo structures. It defines setupPreviewData() only; add your own print().
Combo chit preview data
// Build one item. parentId is 0 for a top-level item, or the Id of its parent combo.
function mk(id, itemId, desc, kitchen, sort, group, parentId, children, mods) {
return {
Id: id, ItemId: itemId, Quantity: 1, IsDeleted: false,
Description: desc, AlternateKitchenName: kitchen, SortPriority: sort,
ItemGroups: group ? [group] : [],
CompositeOrderItemId: parentId,
CompositeOrderItems: children || [],
Modifiers: mods || []
};
}
function setupPreviewData() {
Store.Name = "Culver's 99999";
Store.Address1 = "Prairie du Sac";
Store.State = "WI";
Store.Phone = "608-643-7980";
Order.CreatedDate = new Date();
Order.Id = "AAAE6LTF9QAE";
Order.Destination = { Name: "Online Carryout" };
Order.Name = "John Doe";
Order.PromiseTime = new Date();
Order.Total = 45.99;
var DISCOUNTABLE = { Id: 1, Name: "Discountable Items" };
var SIDES = { Id: 3, Name: "Sides" };
var CHICKEN = { Id: 44, Name: "CHICKEN" };
Order.Items = [
// Combo: Dinner (id 1) with three children
mk(1, 1, "Dinner", "Din", 2, DISCOUNTABLE, 0, [
mk(2, 2, "6 Piece Shrimp (Dnr)", "6 SHRIMP", 1, DISCOUNTABLE, 1, [], [
{ Id: 3, ItemId: 3, Description: "Cocktail Sauce" },
{ Id: 4, ItemId: 4, Description: "Boom Boom Sauce" }
]),
mk(5, 5, "French Fries MED", "FRY", 4, SIDES, 1),
mk(6, 6, "Coleslaw MED", "SLAW", 5, { Id: 4, Name: "Drinks" }, 1)
]),
// Combo: Value Basket (id 7) with four children
mk(7, 7, "Value Basket", "VB", 3, null, 0, [
mk(8, 8, "Crispy Chicken Sandwich", "CRSP CHIX", 3, CHICKEN, 7),
mk(9, 9, "Regular VB", "OLO ID: 217270 91573227520", 1, { Id: 2, Name: "Regular" }, 7),
mk(10, 5, "French Fries MED", "FRY", 5, SIDES, 7),
mk(11, 11, "Root Beer MED", "RT BR MED", 6, { Id: 4, Name: "DRINKS" }, 7)
]),
// Standalone items that reuse ItemIds from the combos
mk(12, 5, "French Fries MED", "FRY", 5, SIDES, 0),
mk(13, 8, "Crispy Chicken Sandwich", "CRSP CHIX", 6, CHICKEN, 0)
];
}
NOTE: The object reference in this guide also draws on the earlier Printer Scripts reference documentation, which was compiled from local printer-script notes.
