## shipping : object
Add custom carrier and rates, and adjust markup.
**Kind**: global namespace
* [shipping](#shipping) : object
* [.Address](#shipping.Address)
* [new Address()](#new_shipping.Address_new)
* [.getZIPCode(zipcode, country)](#shipping.getZIPCode) ⇒ Object
* [.getPackagingByID(id)](#shipping.getPackagingByID) ⇒ Promise.<Object>
* [.getRetailPriceWithMarkup(cost, retail, carrier, service, weightOz, packaging)](#shipping.getRetailPriceWithMarkup) ⇒ Promise.<number>
* [.getCarrierName(carrierId)](#shipping.getCarrierName) ⇒ string
* [.getServiceName(serviceId, carrier)](#shipping.getServiceName) ⇒ string
* [.registerRateEndpoint(getRates, purchase, idPrefix)](#shipping.registerRateEndpoint)
* [.registerMarkupCalculator(markupFn)](#shipping.registerMarkupCalculator)
### shipping.Address
**Kind**: static class of [shipping](#shipping)
#### new Address()
A class representing an address.
### shipping.getZIPCode(zipcode, country) ⇒ Object
Get data for a ZIP Code.
**Kind**: static method of [shipping](#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**
```js
{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](#shipping)
**Returns**: Promise.<Object> - See examples.
| Param | Type |
| --- | --- |
| id | number |
**Example**
```js
{
id: 100,
type: "Parcel",
img: "box.png",
name: "Box",
service: "",
l: -1,
w: -1,
h: -1,
weight: true,
hazmat: true,
source: "Customer"
}
```
**Example**
```js
{
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**
```js
{
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](#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](#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](#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](#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**
```js
// 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**
```js
// 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](#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**
```js
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.
}
}
);
```