rateShipment()

This method calculates the shipping costs for a shipment, or multiple permutations of a shipment, to allow your customers to select the best rate.

Most carrier apps should implement this method, unless you don't support rating shipments.

Syntax

module.exports = async function rateShipment(transaction, criteria) {
// Your code here
}
import { Transaction, RateCriteria, Rate } from "@shipengine/connect";
export default async function rateShipment(
transaction: Transaction,
criteria: RateCriteria
): Promise<Rate[]> {
// Your code here
}

Parameters

transaction

A transaction object containing information about the transaction and session state.

criteria

An array of objects containing information used to calculate shipping charges. This object may include a deliveryService and/or a fulfillmentService.

If these are provided, your method should only return rates that match all the required criteria. If none of these are provided, your method should return all rates.

NameTypeNullable?Description
shipDateTime

date/time object

The date/time that the shipment is expected to ship. This is not guaranteed to be in the future.

shipFrom

address + contact Info object

The sender's contact info and address.

shipTo

address + contact info object

The recipient's contact info and address.

pickupLocation

address + contact info + pickup location object

The location where the recipient can pick up the shipment.

returnsobject

An object that indicates whether or not this shipment is a return shipment.

returns.isReturnboolean

Indicates whether or not this shipment is a return shipment.

packagesobject[]

The list of packages in the shipment.

packages[].packagingobject

The packaging that may be used. If not specified, then rate quotes should be returned for all applicable packaging.

This property may be null. If it is provided, all its required properties, listed below, will be included.

packages[].packaging.id

UUID

A UUID that uniquely identifies the object. This is the UUID you used in the Packaging Definition file for this packaging.

packages[]   .packaging   .identifiers

identifiers object

Your own identifiers for this packaging.

packages[].packaging.codestring

Optional code used to map to what the carrier uses to identify the packaging.

The value custom indicates user-defined packaging. Some of our products allow users to enter custom packaging instead of one of your app's pre-defined packaging types.

packages[].packaging.namestring

The user-friendly name for this packaging (e.g. "Flat-Rate Box", "Large Padded Envelope"). This string will not contain newline characters.

packages[]   .packaging   .descriptionstring

A short, user-friendly description of the packaging. This string will not contain newline characters.

packages[]   .packaging   .requiresWeightboolean

Indicates whether the weight must be specified when using this packaging.

packages[]   .packaging   .requiresDimensionsboolean

Indicates whether the dimensions must be specified when using this packaging.

packages[].dimensionsobject

The dimensions for the package.

This property may be null. If it is provided, all its required properties, listed below, will be included.

packages[]   .dimensions   .lengthnumber

The length of the package. This value may contain decimals.

packages[]   .dimensions   .widthnumber

The width of the package. This value may contain decimals.

packages[]   .dimensions   .heightnumber

The height of the package. This value may contain decimals.

This property may be null. If it is provided, all its required properties, listed below, will be included.

packages[]   .dimensions   .unitstring

The unit of measurement for the dimensions. Valid values include the following:

  • in - inches
  • cm - centimeters
packages[].weightobject

The weight of the package.

This property may be null. If it is provided, all its required properties, listed below, will be included.

packages[].weight.valuenumber

The weight value for this package. This value may contain decimals.

packages[].weight.unitstring

The unit of measure for this weight. Valid values include the following:

  • g - grams
  • oz - ounces
  • kg - kilograms
  • lb - pounds
packages[].insuredValueobject

The insured value of this shipment.

This property may be null. If it is provided, all its required properties, listed below, will be included.

packages[]   .insuredValue   .valuenumber

The value of the insured amount.

packages[]   .insuredValue   .currencystring

The currency that the value represents.

packages[]   .containsAlcoholboolean

Indicates whether the package contains alcohol.

packages[]   .isNonMachineableboolean

Indicates whether the package cannot be processed automatically due to size, shape, weight, etc. and requires manual handling.

packages[].customs

customs object

The customs associated with this package.

This property may be null. If it is provided, all its required properties, listed in the linked page, will be included.

packageobject

Returns the first package in the packages array. Useful for carriers that only support single-piece shipments. This object has all the same properties as the objects in the packages array described above.

deliveryService

delivery service object

An object that indicates the delivery service to get rates for. If neither deliveryService nor fulfillmentService are specified, then rate quotes should be returned for all applicable services.

fulfillmentService

fulfillment service string

The fulfillment service that may be used to fulfill the shipment. If neither deliveryService nor fulfillmentService are specified, then rate quotes should be returned for all applicable services.

deliveryConfirmation

delivery confirmation object

The type of package delivery confirmation to use for this rate request.

deliveryDateTime

date/time object

The latest date and time that the shipment can be delivered.

totalInsuredValueobject

The total insured value of all packages in the shipment. If specified, then rate quotes should include carrier-provided insurance.

This property may be null. If it is provided, all its required properties, listed below, will be included.

totalInsuredValue   .currencystring

The currency for this value.

totalInsuredValue.valuenumber

The amount of this value.

shippingOptions

shipping options

The shipping options that are required for this shipment.

Return Value

rates[]

An array of objects representing the quoted shipping rates based on the specified rate criteria.

NameTypeRequired?Description
deliveryService

delivery service object or string

The delivery service this rate is for. This property accepts an object or a string representing the code.

If an object is provided, it must have the following properties.

deliveryService.id

UUID

A UUID that uniquely identifies the object. This is the UUID you used in the Delivery Service Definition file for this delivery service.

deliveryService   .identifiers

identifiers object

Your own identifiers for this delivery service.

deliveryService.codestring

Optional code used to map to what the carrier or marketplace uses to identify the delivery service.

charges

charge object[]

The breakdown of charges for this shipment. If the carrier does not provide a detailed breakdown, then just use a single charge of type "shipping". If the carrier does not provide any charges values at all, return a $0 value charge.

shipDateTime

date/time object,
or Date object object,
or a string representing the date and time in ISO format.

The date/time that the shipment is expected to ship. This is not guaranteed to be in the future.

deliveryDateTime

date/time object,
or Date object object,
or a string representing the date and time in ISO format.

The estimated date and time the shipment will be delivered.

isNegotiatedRateboolean

Indicates whether this shipment used a pre-negotiated terms.

isTrackableboolean

Indicates whether tracking numbers are provided.

deliveryConfirmation

delivery confirmation object or string

The delivery confirmation included in this rate. This property accepts an object or a string representing the id, code, or type.

If an object is provided, it must have the following properties.

deliveryConfirmation.id

UUID

UUID that uniquely identifies the delivery confirmation. This ID should never change.

deliveryConfirmation   .identifiers

identifiers object

Your own identifiers for this delivery confirmation.

deliveryConfirmation.codestring

Optional code used to map to what the carrier or marketplace uses to identify the packaging.

notesobject[]

An array of objects containing additional information about this rate.

This property is not required. If it is provided, it must contain all of its required properties, listed below.

notes[].type

notes type string

The type for this note.

notes[].textstring

The note text itself.

packagesobject[]

An array of objects describing the list of packages in the shipment.

packages[].packaging

object or string

The packaging this rate is for. This property accepts an object or a string representing the code.

This property is not required. If it is provided, it must contain all of its required properties, listed below.

packages[].packaging.id

UUID

A UUID that uniquely identifies the object. This is the UUID you used in the Packaging Definition file for this packaging type.

packages[]   .packaging   .identifiers

identifiers object

Your own identifiers for this packaging.

packages[].packaging.codestring

Optional code used to map to what the carrier or marketplace uses to identify the packaging.

The value custom indicates user-defined packaging. Some of our products allow users to enter custom packaging instead of one of your app's pre-defined packaging types.

Example

module.exports = async function rateShipment(transaction, shipment) {
// STEP 1: Validation
// TODO: add any validation logic here
// STEP 2: Create the data that the carrier's API expects
let data = {
operation: "quote_rates",
session_id: transaction.session.id,
service_codes: [shipment.deliveryService.code],
confirmation_codes: [shipment.deliveryConfirmation.code],
parcel_codes: [shipment.packages[0].packaging.code],
ship_date: shipment.shipDateTime.toISOString(),
delivery_date: shipment.deliveryDateTime.toISOString(),
from_zone: parseInt(shipment.shipFrom.postalCode, 10),
to_zone: parseInt(shipment.shipTo.postalCode, 10),
total_weight: shipment.packages[0].weight.ounces,
};
// STEP 3: Call the carrier's API
const response = await apiClient.request({ data });
// STEP 4: Create the output data that ShipEngine expects
return response.data.map(formatRate);
}
import {
ChargeType,
RateCriteria,
Rate,
Transaction
} from "@shipengine/connect";
export default async function rateShipment(
transaction: Transaction<Session>, shipment: RateCriteria): Promise<Rate[]> {
// STEP 1: Validation
// TODO: add any validation logic here
// STEP 2: Create the data that the carrier's API expects
let data: QuoteRatesRequest = {
operation: "quote_rates",
session_id: transaction.session.id,
service_codes: [shipment.deliveryService.code],
confirmation_codes: [shipment.deliveryConfirmation.code],
parcel_codes: [shipment.packages[0].packaging.code],
ship_date: shipment.shipDateTime.toISOString(),
delivery_date: shipment.deliveryDateTime.toISOString(),
from_zone: parseInt(shipment.shipFrom.postalCode, 10),
to_zone: parseInt(shipment.shipTo.postalCode, 10),
total_weight: shipment.packages[0].weight.ounces,
};
// STEP 3: Call the carrier's API
const response = await apiClient.request<QuoteRatesResponse>({ data });
// STEP 4: Create the output data that ShipEngine expects
return response.data.map(formatRate);
}