Skip to content

Pos

pos : object

Point of Sale, transaction, and payment-related functionality.

Kind: global namespace

pos.ReceiptItem

Kind: static class of pos
Properties

Name Type Default Description
merch boolean false True if merchandise, false if shipping.
barcode string Item barcode, or tracking number if merch = false.
qty number 1 Item quantity.
retailPrice number The calculated retail/markup price for a shipment, regardless of actual sale price. If unset, defaults to priceEach * qty.
taxRate number 0 Tax rate
toAddress Address Shipping destination address.
fromAddress Address Shipping return address.
carrier string Shipping carrier.
service string Shipping service.
category string Merchandise/item category.
electronicReturnReceipt boolean false If true, the customer's receipt will have instructions on retrieveing the return receipt from USPS.
mailboxDays number 0 Number of days this item adds to a mailbox's expiration date.
mailboxMonths number 0 Number of months this item adds to a mailbox's expiration date.
mailboxNumber string Mailbox number to apply mailboxDays or mailboxMonths to after checkout.
setCertifiedInfo() function Set Certified Mail receipt data. setCertifiedInfo(trackingNumber, certfee, extrafees, postage, date, location, toaddress)
toJSON() function Get the item as an object suitable for JSON encoding.
fromJSON(json) static_function Returns a ReceiptItem created from the object returned by item.toJSON().

new ReceiptItem(id, label, text, priceEach, quantity, cost, taxrate, taxableAmount)

A class representing a sale item in the current transaction.

Param Type Default Description
id string Unique ID number for this item (UPC code, inventory number, etc). Used to deduplicate and merge line items on the receipt. Unique items (like shipping labels) should be a unique/random ID.
label string One-line item information.
text string Extra multi-line item information.
priceEach number Sale price per unit.
quantity number Number of units.
cost number Cost per unit. Used for automatic expense tracking.
taxrate number 0.0 Examples: 0 (for 0%), 0.05 (for 5%), etc
taxableAmount string The part of the sale price that's taxable. "" for default (all), "markup" for only taxing profit.

pos.ReceiptPayment

Kind: static class of pos
Properties

Name Type Description
label string (readonly) The human-readable string of the payment type.
id string Automatically-generated unique ID for this payment.
toJSON() function Get the payment as an object suitable for JSON encoding.
fromJSON(json) static_function Returns a ReceiptPayment created from the object returned by payment.toJSON().

new ReceiptPayment(amount, type, text)

A class representing a payment entry for the current transaction.

Param Type Description
amount number amount paid
type string payment type
text string extra data (credit card info, etc)

pos.addReceiptItem(item)

Add an item (shipment, merchandise, etc) to the current transaction.

Kind: static method of pos

Param Type
item ReceiptItem

pos.addReceiptPayment(payment)

Add a payment to the current transaction/receipt.

Kind: static method of pos

Param Type
payment ReceiptPayment

pos.getReceipt() ⇒ Receipt

Get the current receipt for the currently active transaction.

Kind: static method of pos

pos.getCustomerAccountInfo() ⇒ Object | boolean

Get information about the active customer account.

Kind: static method of pos
Returns: Object | boolean - The object in the example, or false if no active customer account.
Example

{
    uuid: "",
    name: "",
    company: "",
    email: "",
    phone: "", // primary phone number, E.164 format.
    phone2: "", // second phone/fax, not usually visible in PostalPoint
    phone3: "", // third phone/fax, not usually visible in PostalPoint
    street1: "", // address line 1
    street2: "", // address line 2
    zip: "", // postal code
    city: "",
    state: "", // state/province/etc
    country: "", // 2-letter ISO country code
    taxid: ""
}

pos.addOnscreenPaymentLog(msg)

Append a line of text to the onscreen log displayed during credit card processing. Not shown in kiosk mode.

Kind: static method of pos

Param Type Description
msg string Line of text to add to the log.

pos.getReceiptID() ⇒ string

Get the unique alphanumeric ID for the current transaction/receipt. This is the same code printed on receipts and used in digital receipt URLs.

Kind: static method of pos

pos.onReceiptChange(f)

Specify a function to be called whenever the transaction data/receipt is changed. It is passed a single argument, a Receipt object containing the entire transaction so far.

Kind: static method of pos

Param Type
f function

~~pos.onTransactionFinished(f)~~

Deprecated

The supplied function will be called when a transaction is finished. It is passed a single argument, a Receipt object containing the entire transaction. Recommended to listen for the transactionFinished event instead.

Kind: static method of pos

Param Type
f function

pos.registerCardProcessor(f)

Register as a card payment processor.

Kind: static method of pos

Param Type Description
f Object Payment processor functions

Example

global.apis.pos.registerCardProcessor({
    // Shown in PostalPoint settings menu
    name: "Demo Card Processor",
    // Set true if the integration can credit funds back to a customer card.
    // A return/refund/credit transaction will call checkout with a negative amount.
    // If this is not true, the card payment option will not be shown on the checkout
    // during a return transaction.
    allowCreditCharges: false,
    init: async function () {
        // This will run after PostalPoint launches
        // and before any payments are processed.
        // In some situations it might run multiple times in a session.
    },
    checkout: async function ({amount, capture = true}) {
        // Charge a credit card using a card reader device.
        // amount is in pennies (or the equivalent base unit in the local currency).
        // If a credit is to be issued to the card, amount is * -1.

        // Add a payment to the receipt with the total amount paid, card details, etc.
        global.apis.pos.addReceiptPayment(
            new global.apis.pos.ReceiptPayment(
                global.apis.i18n.currencyMinorToMajor(amount),
                "card", // Payment type. Accepted values are card, ach, crypto, cash,
                // check, account, and free.  Other types will be displayed as-is.
                "Demo Card\nCardholder Name, etc\nMore info for receipt" // Additional text for receipt
            )
        );


        // Must return boolean false if the payment failed.
        // Otherwise it will be assumed it succeeded.
        // If an error is encountered, handle it and return false.
        // It's recommended to display a short "payment failed" error
        // message via global.apis.alert, and outputting more details
        // via global.apis.pos.addOnscreenPaymentLog.

        // If capture is false, perform an authorization but don't capture,
        // and return a value you can use to identify the authorization later
        // and complete it.  The value will be passed back to finishPayment, below.
        // This is used mainly for the self-serve kiosk mode, in case the label fails
        // to be purchased/generated by the carrier.
    },
    cancelCheckout: function () {
        // The user has requested the card transaction be canceled before it completes.
        // Reset the terminal to its resting state, clear its screen, etc.
    },
    finishPayment: async function ({checkoutResponse}) {
        // Finish a payment that was authorized but not captured
        // because checkout() was called with capture = false.
        // If payment was already captured and added
        // to the receipt, just return true.
        global.apis.pos.addReceiptPayment(
            new global.apis.pos.ReceiptPayment(
                global.apis.i18n.currencyMinorToMajor(amount),
                "card",
                "Demo Card\nCardholder Name, etc\nMore info for receipt"
            )
        );
    },
    updateCartDisplay: function (receipt) {
        // Show transaction data on the card reader display.
        // This function is called when the "cart" or total changes.
        // `receipt` is a receipt object, see docs for details.
    },
    checkoutSavedMethod: async function ({customerID, paymentMethodID, amount}) {
        // Same as checkout() except using a payment method already on file.
        // customerID and paymentMethodID are provided by getSavedPaymentMethods below.

        // Must return true upon success.
        // If the payment is not successful, and you didn't throw an Error to show the user,
        // then `return false` instead and it'll appear that the user's action to start the payment did nothing.
        return true;
    },
    saveCardForOfflineUse: async function ({statusCallback, customerUUID, name,
             company, street1, street2, city, state, zip, country, email, phone}) {
        // Use the card reader to capture an in-person card and save it for offline use.
        // Provided details are the customer's info, which might be empty strings except for the customerUUID.
        // Saved card details must be tied to the customerUUID, as that's how saved cards are looked up.

        // statusCallback(string, boolean) updates the progress message on the cashier's screen.
        // If the boolean is true, the progress message is replaced with a confirmation message.
        statusCallback("Saving card details...", false);

        return true; // Card saved to customer
        // If an error occurred, you can throw it and the error
        // message will be displayed to the cashier.
        // Alternatively, return boolean false and display the error
        // yourself with global.apis.alert(message, title) or something.
    },
    cancelSaveCardForOfflineUse: function () {
        // Cancel the process running in saveCardForOfflineUse() at the user/cashier's request.
    },
    getSavedPaymentMethods: async function ({customerUUID}) {
        // Return all saved payment methods tied to the provided customer UUID.
        return [{
            customer: "<internal string referencing the customer>", // Passed to checkoutSavedMethod as customerID
            customer_uuid: customerUUID,
            id: "<card/payment method identifier>", // Passed to checkoutSavedMethod as paymentMethodID
            type: "card", // Payment type. Accepted values are card, ach, crypto, cash, check, account, and free.
            label: "Visa debit x1234 (exp. 12/29)", // Label for payment method
            label_short: "Visa debit x1234" // Abbreviated label for payment method
        }];
    },
    deleteSavedPaymentMethod: async function ({customerUUID, customerID, paymentMethodID}) {
        // Delete the payment method identified by paymentMethodID
        // and tied to the PostalPoint customerUUID and the card processor customerID.
        // If unable to delete, throw an error and the error message
        // will be displayed to the cashier.
    }
});

pos.registerCryptoProcessor(f)

Register as a cryptocurrency payment processor.

Kind: static method of pos

Param Type Description
f Object Payment processor functions

Example

global.apis.pos.registerCryptoProcessor({
    name: "Demo Crypto", // Shown in PostalPoint settings menu
    init: async function () {
        // This is run after PostalPoint starts,
        // and before any other crypto functions are called.
    },
    checkout: async function ({amount}) {
        // Run the checkout process.
        // amount is the amount of fiat currency to collect,
        // in pennies (or the local equivalent).

        // If an error is encountered during processing,
        //    display an error message in a dialog and return boolean false.
        //    If this function returns anything except false or undefined,
        //    and doesn't throw an error,
        //    it is assumed the payment was successful.

        // Adds a line of text visible to the cashier
        global.apis.pos.addOnscreenPaymentLog("Getting crypto payment...");

        // Display a web page (i.e. with a payment QR code)
        // to the customer on the customer-facing display.
        global.apis.ui.setCustomerScreen("<html></html>", "html");
        global.apis.ui.setCustomerScreen("https://postalpoint.app", "raw");

        // Poll the status of the crypto transaction
        var paymentComplete = false;
        do {
            await global.apis.util.delay(1000);
            paymentComplete = true;
        } while (paymentComplete != true);

        global.apis.pos.addReceiptPayment(
                new global.apis.pos.ReceiptPayment(
                        global.apis.i18n.currencyMinorToMajor(amount),
                        "crypto", // Payment type.
                        "Bitcoin\n0.00001234 BTC" // Additional text for receipt
                        )
                );
        global.apis.pos.addOnscreenPaymentLog("Payment successful!");
        global.apis.ui.clearCustomerScreen();
    },
    cancelCheckout: function () {
        // The user requested to cancel the payment.
        // Reset things accordingly.
        global.apis.ui.clearCustomerScreen();
    },
    isConfigured: function () {
        // Is this plugin properly setup
        // and able to process payments?
        // If not, return false.
        // This determines if the crypto payment method button will be shown.
        return true;
    }
});

pos.getShippingSalesTax() ⇒ Object

Get the sales tax percentage to charge on a shipping service ReceiptItem.

Kind: static method of pos
Returns: Object - {type: "", percent: 0.15} type is an empty string for taxing the entire price, or "markup" for only adding tax to the markup amount. percent is the tax percentage. A value of 0.15 means a 15% tax.

pos.getTransactions(startDate, endDate, customeruuid) ⇒ Promise.<Array>

Get a list of transactions inside a date range.

Kind: static method of pos
Returns: Promise.<Array> - See example for returned data structure.

Param Type Description
startDate Date | Number Return transactions after this date. Can be a Date object or UNIX timestamp.
endDate Date | Number Return transactions before this date. Can be a Date object or UNIX timestamp.
customeruuid null | String If set, only return transactions belonging to this customer UUID.

Example

[{
    "transactionid": 220, // Internal database ID.
    "uuid": "fh38mmun15f7qdmj", // The receipt's public ID.
    "date": "2026-04-06 19:35:47",
    "cashierid": -1, // Employee's database ID number, or -1 if not using employee logins.
    "customeruuid": "be89ab9c-83a4-4ee7-a8ff-9464bf656f15", // Customer UUID, or null.
    "originaluuid": null, // If a return, the original receipt's ID.
    "type": "SALE", // "SALE" or "RETURN"
    "total": 22,
    "itemCount": 1,
    "paidTotal": 22,
    "costTotal": 0,
    "taxTotal": 0,
    "cashTotal": 22,
    "cardTotal": 0,
    "checkTotal": 0,
    "cryptoTotal": 0,
    "discountTotal": 0,
    "roundingTotal": 0, // Cash rounding to 5 cents
    "otherTotal": 0, // Other payment types.
    "dueTotal": 0,
    "paid": true,
    "cashCount": 1,
    "cardCount": 0,
    "checkCount": 0,
    "cryptoCount": 0,
    "discountCount": 0,
    "roundingCount": 0, // Cash rounding to 5 cents
    "otherCount": 0, // Other payment types.
    "netProfit": 22, // Net profit if the sale were fully paid: revenue - costTotal - taxTotal
    "netProfitActual": 22, // Actual net profit based on payments received so far: paidTotal - costTotal - taxTotal
    "items": [
        {
            "category": "", // Item category name.
            "merchandiseid": null, // If set, is a string UUID for a merchandise item.
            "type": "ship", // "merch" or "ship"
            "label": "Item Label",
            "priceEach": 22, // Price for one unit of the item.
            "qty": 1, // Quantity/units sold.
            "taxRate": 0, // Tax rate.
            "taxableAmount": "", // If "markup", only the margin/markup is taxable. Rarely, this is how shipping is taxed in some jurisdictions.
            "cost": 0, // Item cost for one unit, set by the user in the merchandise database.
            // See ReceiptItem docs for info on the JSON data.
            "json": "{\"id\":\"item_id_12345\",\"label\":\"Item Label\",\"text\":\"Item Receipt Text Lines\",\"priceEach\":22,\"qty\":1,\"cost\":0,\"retail\":0,\"taxRate\":0,\"taxableAmount\":\"\",\"taxTotal\":0,\"free\":false,\"barcode\":\"406183511501\",\"certifiedInfo\":false,\"isMerch\":false,\"merchid\":null,\"surcharge\":false,\"mailboxNumber\":null,\"mailboxDays\":0,\"mailboxMonths\":0,\"carrier\":\"\",\"service\":\"\",\"category\":\"\",\"electronicReturnReceipt\":false,\"isStamp\":false,\"extraData\":{}}"
        }
    ],
    "payments": [
        {
            "type": "cash",
            "amount": 22,
            "text": "" // Extra text lines printed on the receipt. Present for card payments and in some other situations.
        }
    ]
}]

pos.getCategories() ⇒ Promise.<Array.<String>>

Get a list of merchandise categories defined in the database (i.e. belonging to at least one item). Note that this doesn't return all categories possible, but only the user-defined ones. System-generated categories exist as well.

Kind: static method of pos

pos.updateStock(merchId, adjustment) ⇒ Promise

Update the stock count of a merchandise item.

Kind: static method of pos

Param Type Description
merchId String Merchandise item UUID.
adjustment number Amount to add to the count. Negative numbers subtract.

Example

// Reduce the stock count by 2
await global.apis.pos.updateStock("243d4c0f-c9ce-414a-aec7-9fc753eb13d6", -2);

// Increase the stock count by 5
await global.apis.pos.updateStock("243d4c0f-c9ce-414a-aec7-9fc753eb13d6", 5);

pos.getMerchDB() ⇒ Promise.<Array.<Object>>

Dump the merchandise database table. This is the same data used in the Merchandise Admin interface.

Kind: static method of pos
Returns: Promise.<Array.<Object>> - See example.
Example

[{
 "id": "", // UUID v4
 "name": "",
 "category": "",
 "price": 1.0,
 "cost": 0.5,
 "barcode": "",
 "taxrate": 0.1,
 "stock": 10,
 "show": 1, // Boolean
 "length": 0,
 "width": 0,
 "height": 0,
 "rental_days": 0,
 "rental_months": 0,
 "rental_size": "1"
}]

pos.saveMerchDB(data, overwrite) ⇒ Promise

Save merchandise item database. Items already in the database that are not in data are deleted.

Kind: static method of pos

Param Type Description
data Object See output of getMerchDB()
overwrite boolean Default false. If true, merch table is purged before inserting. If false, records with matching IDs are updated in place.