PostalPoint_Plugins/docs/Plugin API/shipping.md

shipping : object

Add custom carrier and rates, and adjust markup.

Kind: global namespace

• shipping : object
  • .Address
    • new Address()
  • .getZIPCode(zipcode, country) ⇒ Object
  • .getPackagingByID(id) ⇒ Promise.<Object>
  • .getRetailPriceWithMarkup(cost, retail, carrier, service, weightOz, packaging) ⇒ Promise.<number>
  • .getCarrierName(carrierId) ⇒ string
  • .getServiceName(serviceId, carrier) ⇒ string
  • .registerRateEndpoint(getRates, purchase, idPrefix)
  • .registerMarkupCalculator(markupFn)

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.
        }
    }
);