Skip to content

# Shipping

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