Custom Scripts

Custom Scripts let you change how the register behaves with a little JavaScript: show a warning, adjust the sale, hide a payment method, or change which stores and carriers are offered. They run in the register itself, as the sale changes.

Where to find them

Go to Admin › Custom Scripts. It's one screen: the list of scripts acts as tabs, so select one to open it in the editor beside it. Make your changes and select Save changes. If a script has a syntax error, you'll see its line and column.

The scripts

How a script runs

A script is the body of a function: your data is on $, and you change it in place. You don't declare a function or return anything.

// Sales Line Change: warn when a return has no customer
var hasReturn = $.sale.lines.some(function (l) { return l.quantity < 0; });
if (hasReturn && !$.sale.customer_id) {
  $.alert.show = true;
  $.alert.msg = 'Customer required for returns';
  $.alert.variant = 'warning';
}

• Change $ and the register picks it up. What it uses afterwards depends on the script (see the table above).
• $.alert shows a message on the sale screen. Set show to true, msg to the text, and variant to info, warning or danger.
• Each script has 2 seconds. A script that takes longer is stopped, and you see Script did not finish within 2000 ms and was stopped.
• A failed script changes nothing. If a script throws an error or times out, the register keeps its data as it was and shows the error. The one exception is Get Payment Methods: see below.
• Scripts that keep changing the sale stop themselves. A Sales Line Change script that changes the lines triggers itself again. After 3 re-runs in a row, the register stops running it until the next change you make.

Get Payment Methods

$.payment_methods must stay an array of objects (an empty array is fine). Remove entries to hide those methods for this sale:

// Hide Account for sales with no customer
if (!$.sale.customer_id) {
  $.payment_methods = $.payment_methods.filter(function (m) { return m.name !== 'Account'; });
}

🚧

A broken payment methods script hides every payment method

If this script fails, times out or leaves $.payment_methods as anything but an array of objects, the register shows no payment methods and says: Payment methods are unavailable due to a custom script error. Fix the payment methods script in Admin > Custom Scripts. Test it carefully before you save.

Get SOH Availability and Get Shipping Carriers

Change the list and the register shows your version:

// Get SOH Availability: don't offer stores with fewer than 2 in stock
$.availability = $.availability.filter(function (s) { return s.quantity >= 2; });

// Get Shipping Carriers: free standard shipping for a known customer
if ($.customer && $.customer.id) {
  $.carriers.forEach(function (c) { if (c.name === 'Standard') c.price = 0; });
}

Test a script

Open Test script under the editor to try a script without saving it. It runs in the same worker the register uses, with the same 2-second limit.

1. Edit Sample input ($) as JSON. It starts with a sample for the script you have open, and Reset sample puts it back.
2. Select Run test.
3. Read the result: Finished with the time it took (or Timed out or Error), any Console output from console.log, the Changes your script made to $, and the whole Output $.

For example, Finished in 13 ms with No changes means the script ran but didn't change anything for that sample, which is what you'd expect from the return warning above on a sale with no returns.

Tips

• Keep scripts short and fast. They run every time the sale changes, on every register.
• Change only what you mean to. Check the Changes list in the test panel: it shows every path your script changed.
• Use console.log while testing. Its output shows in the test panel's Console.