Shipping

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

{
    id: 100,
    type: "Parcel",
    img: "box.png",
    name: "Box",
    service: "",
    l: -1,
    w: -1,
    h: -1,
    weight: true,
    hazmat: true,
    source: "Customer"
}

{
    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"]
}

{
    id: 201,
    type: "UPSLetter",
    img: "ups-env.png",
    name: "Envelope",
    carrier: "UPS",
    l: -2,
    w: -2,
    h: -2,
    weight: true,
    hazmat: true,
    source: "OtherCarrier"
}

// 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
}]

// purchase sample return value:
{
    label: labelImageToPrint,
    labeltype: "PNG",
    receiptItem: ReceiptItem, // Data to add to the transaction receipt.
    tracking: "12345678901234567890",
    cost: 10.0,
    price: 15.0,
    carrier: "Carrier Name",
    service: "Service Name",
    delivery_days: 3,
    delivery_date: 1234567890, // UNIX timestamp
    to_address: new global.apis.shipping.Address(),
    from_address: new global.apis.shipping.Address(),
    plugin_sourceid: "", // Unique string for your plugin; saved alongside shipment in store database to allow queries to filter shipments by source.
    metadata: {} // Object containing extra data to be stored in the database. Serialized to JSON.
}

extraOptions = {
    getRecentLabels: async function () {
        // Return a list of recently purchased/printed labels for reprinting and/or voiding/refund purposes.
        // Your plugin must also implement voidLabel() (below) or it won't be queried for recent labels.
        return [
            {
                id: `${idPrefix}_${yourShipmentID}`,
                created: Date, // Date object of the label/shipment date. Used for ordering the list.
                refund_status: false, // false to show a refund/void button, otherwise a short string to show such as "Refunded" or "Refund processing" or "Refund rejected"
                tracking: "", // Shipment tracking number or an empty string if it has no tracking.
                label_urls: [], // Array of URLs to download the label image(s) from if the user requests a reprint.
                //                 If empty or not an array, the reprint button is disabled.
                //                 May also be a function that returns a Promise that resolves to the described array.
                //                 If this is a function, it's passed this label object as an argument.
                to: new global.apis.shipping.Address(), // Destination/to address.
                from: new global.apis.shipping.Address(), // Return/from address.
                carrier: global.apis.shipping.getCarrierName(""), // Carrier name
                service: global.apis.shipping.getServiceName("") // Shipping service
            }
        ]
    },
    voidLabel: async function (id) {
        // Try to void a label with the ID provided (an `id` returned in getRecentLabels)
        // Returns a status string that's displayed to the user in a dialog box, such as "Label refunded." or "Refund request submitted." or "Refund request rejected."
        return "Void request status message goes here";
    }
}

// imageSettings object returned by purchase:
{
    includeFIM: true, // If true, a FIM D (Facing Identification Mark, variant D) is printed to the left of the indicia. Required for letter-size postage.
    indiciaX: px, // Leftmost pixel in label image to print (pixels to the left will be cropped out). If negative, counts from the right side of the label instead.
    indiciaY: px, // Topmost pixel in label image (pixels above will be cropped out). If negative, counts from the right side of the label instead.
    indiciaWidth: px, // Width in pixels to crop to, starting from indiciaX on the left side and moving right
    indiciaHeight: px, // Height in pixels to crop to, starting from indiciaY on the top side and moving down
    dpi: 300, // Native DPI (pixels per inch) of your label. PostalPoint scales your image to 300 DPI after cropping.
    rotate: 0 // If not zero, image is rotated this many degrees (90, 180, 270, etc) before any processing.
}
// Note: Depending on indicia width, FIM presence, and label width, the indicia may be
//   scaled slightly smaller after cropping to the dimensions provided in order to fit on
//   the label media size in use. In our testing with the widest indicia (PDF417),
//   the barcode in the indicia is still scannable (and the human-readable text still legible)
//   after this adjustment, but you might wish to test the worst case scenario:
//   `includeFIM: true` on a 1.1x3.5 "standard address" label printed at 200dpi.

registerAddressVerificationProvider("example", "Example", async function (addressData) {
    // This function is passed the data structure shown below, and must return the same structure but updated with the validated addresses.
    return {
         to: new global.apis.shipping.Address(),
         from: new global.apis.shipping.Address(),
         toVerified: true, // If the to address was verified
         fromVerified: true, // If the from/return address was verified
         toErrors: [], // String messages to display on the to address verification checkmark/warning icon
         fromErrors: [] // String messages to display on the from/return address verification checkmark/warning icon
    }
});

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

async function getQuote(value, parcel, carrier, service, rateObject) {
    // See shipping rate provider documentation for rateObject structure.

    // 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);

// Sample result from this function:
// All fields except `id` and `created` might be null.
{
    id: 123, // Internal database ID for shipment
    shipmentid: "xxx", // The `shipmentid` returned from a label purchase, or null if not provided
    customeruuid: "string", // Customer UUID string
    prepaid: false, // True if a prepaid drop-off
    voided: false, // True if label marked as voided
    tracking: "string", // Tracking number
    carrier: "string",
    service: "string",
    created: Date,
    shipped: Date, // Date and time the package was marked as picked up by the carrier.
    metadata: {}, // Whatever was returned by the purchase function that created the shipment. Stored internally as a JSON string and parsed before returning. If JSON can't be parsed, is set to null.
    to_address: Address,
    from_address: Address
}

{
    fields: { // False if field not applicable for addresses in this country.
        name: true,
        company: true,
        street1: true,
        street2: true,
        city: true,
        state: true,
        zip: true
    },
    labels: { // Human-readable form field labels, localized, and country-dependent
        name: "Name",
        company: "Company",
        street1: "Address",
        street2: "Address Line 2",
        city: "City/Suburb/District/Locality",
        state: "State/Province",
        zip: "Postal Code"
    },
    placeholders: {
        name: "John Doe",
        company: "ABC Inc",
        street1: "123 Example St",
        street2: "Apt 2",
        city: "(Not Required)",
        state: "",
        zip: "12345"
    }
}