Skip to content

Shipping

shipping : object

Add custom carrier and rates, and adjust markup.

Kind: global namespace

shipping.Address

Kind: static class of shipping

new Address()

A class representing an address.

shipping.getZIPCode(zipcode, country) ⇒ Object

Get data for a ZIP Code.

Kind: static method of shipping
Returns: Object - Data about the ZIP code. See example. Fields may be empty if not available. Type may be "STANDARD", "UNIQUE", "PO BOX", or "MILITARY".

Param Type Default Description
zipcode string ZIP or postal code.
country string "US" Currently only "US" and "CA" are supported.

Example

{city: "NEW YORK", state: "NY", type: "STANDARD"}

shipping.getPackagingByID(id) ⇒ Promise.<Object>

Get a parcel's packaging type from PostalPoint's internal ID for it.

Kind: static method of shipping
Returns: Promise.<Object> - See examples.

Param Type
id number

Example

{
    id: 100,
    type: "Parcel",
    img: "box.png",
    name: "Box",
    service: "",
    l: -1,
    w: -1,
    h: -1,
    weight: true,
    hazmat: true,
    source: "Customer"
}
Example
{
    id: 1,
    type: "FlatRateEnvelope",
    img: "pm-fres.png",
    name: "Flat Rate Envelope",
    service: "Priority",
    l: -2,
    w: -2,
    h: -2,
    weight: false,
    hazmat: true,
    usps_supplied: true,
    envelope: true,
    source: "USPS",
    skus: ["PS00001000014", "PS00001000012", "PS00001000027", "PS00001000064", "PS00001001921", "PS00001035000", "PS00001036014", "PS00001128600", "https://qr.usps.com/epsspu?p=30", "https://qr.usps.com/epsspu?p=8"]
}
Example
{
    id: 201,
    type: "UPSLetter",
    img: "ups-env.png",
    name: "Envelope",
    carrier: "UPS",
    l: -2,
    w: -2,
    h: -2,
    weight: true,
    hazmat: true,
    source: "OtherCarrier"
}

shipping.getRetailPriceWithMarkup(cost, retail, carrier, service, weightOz, packaging) ⇒ Promise.<number>

Calculate the retail price for a shipment rate based on the configured margin settings.

Kind: static method of shipping
Returns: Promise.<number> - The amount to charge the customer

Param Type Description
cost number Cost of shipment to business
retail number Default retail price from label provider
carrier string Shipment carrier
service string Shipment service
weightOz number The weight of the shipment in ounces, or null if not available.
packaging string An empty string if not available, or "Letter", "FlatRateEnvelope", etc.

shipping.getCarrierName(carrierId) ⇒ string

Converts the carrier ID string into a consistent and human-readable name.

Kind: static method of shipping

Param Type
carrierId string

shipping.getServiceName(serviceId, carrier) ⇒ string

Converts the service ID string into a consistent and human-readable name. Set the carrier ID for better results.

Kind: static method of shipping

Param Type Default
serviceId string
carrier string "USPS"

shipping.registerRateEndpoint(getRates, purchase, idPrefix)

Register the plugin as a shipping rate and label provider. See the Shipping example plugin.

Kind: static method of shipping

Param Type Description
getRates function A function passed a Parcel object to get rates for. Returns a Promise that resolves to an array of rate objects.
purchase function A function passed a rate ID to purchase. Returns a Promise that resolves to the label information.
idPrefix string A unique string that will be prefixing all rate IDs from this plugin.

Example

// getRates sample return value:
[{
    rateid: `${idPrefix}_${global.apis.util.uuid.v4()}`,
    carrier: "CarrierID",
    carrierName: "Carrier Name",
    service: "CARRIER_SERVICE_ID",
    cost_rate: 10,
    retail_rate: 15,
    delivery_days: 3,
    delivery_date: null,
    guaranteed: true,
    serviceName: "Service Name",
    color: "green" // Rate card color
}]
Example
// purchase sample return value:
{
    label: labelImageToPrint,
    labeltype: "PNG",
    receiptItem: ReceiptItem,
    tracking: "12345678901234567890",
    cost: 10.0,
    price: 15.0,
    carrier: "Carrier Name",
    service: "Service Name",
    delivery_days: 3,
    delivery_date: 1234567890, // UNIX timestamp
    to: toAddressLines // Array of strings
}

shipping.registerMarkupCalculator(markupFn)

Register the plugin to modify PostalPoint's shipping markup calculation during shipment rating.

Kind: static method of shipping
Throws:

  • Error Only one plugin may register with this function; any subsequent attempts to register will throw an Error.
Param Type Description
markupFn function A function that must return either the retail price to charge for this rate, or false to opt-out of setting this particular rate.

Example

global.apis.shipping.registerMarkupCalculator(
    // Parameters:
    // cost:       Cost to shipper
    // retail:     Carrier-suggested retail price
    // suggested:  PostalPoint-suggested retail (default margin calc)
    // carrier:    Shipping carrier name
    // service:    Shipping service code
    // weightOz:   The weight of the shipment in ounces, or null if not available.
    // packaging:  An empty string if not available, or "Letter", "FlatRateEnvelope", etc. See https://docs.easypost.com/docs/parcels#predefined-package
    // parcel:     The Parcel object for this shipment.  May be null for some rate-only requests without a shipment, such as USPS price calculations.
    function (cost, retail, suggested, carrier, service, weightOz, packaging, parcel) {
        if (carrier == "USPS") {
            if (service == "First-Class Mail") {
                // Handle First-Class Mail differently if it's a 1oz letter (i.e. Forever stamp)
                if (weightOz <= 1 && packaging == "Letter") {
                    return retail + 0.05;
                } else {
                    return retail + 0.25;
                }
            }
            // Handle flat rate envelopes differently
            if (global.apis.shipping.getServiceName(service, carrier) == "Priority Mail" && packaging == "FlatRateEnvelope") {
                return retail + 1.0;
            }
            return suggested + 2.0; // Charge the PostalPoint-calculated amount plus $2
        } else {
            return cost * 2; // Charges the customer double the shipment's cost.
        }
    }
);

shipping.registerInsuranceProvider(id, name, cardText, maxValue, getQuote, insure)

Add a shipping insurance provider.

Kind: static method of shipping

Param Type Description
id string | null Unique ID for the provider. Will be autogenerated if null.
name string Human-readable name for the provider. Shown as the card heading on the Insurance section of the Ship screen.
cardText string Text or HTML to display on the Ship screen card for this provider.
maxValue number The largest number that will be accepted for the "Insured for" value.
getQuote function Returns the cost and retail price for insuring the parcel, or a Promise that resolves into the same. See the example for details.
insure function Insure the parcel and add the insurance details to the receipt. See example.

Example

async function getQuote(value, parcel, carrier, service) {
    // Do math, etc
    var cost = value / 100;

    return {
        cost: cost,
        retail: cost * 2
    };
    // Or, to remove this shipping rate from the list,
    // because the shipment/carrier/service combination
    // is not eligible for insurance:
    return false;
}

async function insure(value, parcel, carrier = "USPS", service = "Priority", trackingNumber = "94055...") {
    // Purchase the insurance
    var cost = value / 100;
    var retailPrice = cost * 2;
    var costPrice = cost;

    var receiptitem = new global.apis.pos.ReceiptItem(`sampleinsurance_${trackingNumber}`,
        "Sample Insurance",
        "Insured for " + global.apis.i18n.moneyString(value),
        retailPrice, 1, costPrice, 0
    );
    receiptitem.merch = true;
    receiptitem.category = "Shipping Insurance";
    receiptitem.barcode = trackingNumber;
    global.apis.pos.addReceiptItem(receiptitem);
}

global.apis.shipping.registerInsuranceProvider(
     "sampleproviderid", "Sample Insurance",
     "Insurance coverage from Sample Insurance. $1 per $100 of value.",
     5000, getQuote, insure);