`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.

Name	Type	Nullable?	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.
`returns`	object		An object that indicates whether or not this shipment is a return shipment.
`returns.isReturn`	boolean		Indicates whether or not this shipment is a return shipment.
`packages`	object[]		The list of packages in the shipment.
`packages[].packaging`	object	✔	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.code`	string		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.name`	string		The user-friendly name for this packaging (e.g. "Flat-Rate Box", "Large Padded Envelope"). This string will not contain newline characters.
`packages[] .packaging .description`	string		A short, user-friendly description of the packaging. This string will not contain newline characters.
`packages[] .packaging .requiresWeight`	boolean		Indicates whether the weight must be specified when using this packaging.
`packages[] .packaging .requiresDimensions`	boolean		Indicates whether the dimensions must be specified when using this packaging.
`packages[].dimensions`	object	✔	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 .length`	number		The length of the package. This value may contain decimals.
`packages[] .dimensions .width`	number		The width of the package. This value may contain decimals.
`packages[] .dimensions .height`	number		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 .unit`	string		The unit of measurement for the dimensions. Valid values include the following: `in` - inches `cm` - centimeters
`packages[].weight`	object	✔	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.value`	number		The weight value for this package. This value may contain decimals.
`packages[].weight.unit`	string		The unit of measure for this weight. Valid values include the following: `g` - grams `oz` - ounces `kg` - kilograms `lb` - pounds
`packages[].insuredValue`	object	✔	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 .value`	number		The value of the insured amount.
`packages[] .insuredValue .currency`	string		The currency that the value represents.
`packages[] .containsAlcohol`	boolean		Indicates whether the package contains alcohol.
`packages[] .isNonMachineable`	boolean		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.
`package`	object		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.
`totalInsuredValue`	object	✔	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 .currency`	string		The currency for this value.
`totalInsuredValue.value`	number		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.

Name	Type	Required?	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.code`	string		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.
`isNegotiatedRate`	boolean		Indicates whether this shipment used a pre-negotiated terms.
`isTrackable`	boolean		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.code`	string		Optional code used to map to what the carrier or marketplace uses to identify the packaging.
`notes`	object[]		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[].text`	string	✔	The note text itself.
`packages`	object[]		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.code`	string		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);
}