`createShipment()`

This method creates a new shipment.

Syntax

module.exports = async function createShipment(transaction, shipment) {
  // Your code here
}

import { Transaction, NewShipment, ShipmentConfirmation } from "@shipengine/connect";
export default async function createShipment(
  transaction: Transaction,
  shipment: NewShipment
): Promise<ShipmentConfirmation> {
  // Your code here
}

Parameters

`transaction`

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

`shipment`

An object containing information about the new shipment to create.

Name	Type	Nullable?	Description
`deliveryService`	delivery service object		An object that identifies a delivery service that is offered by a carrier.
`shipFrom`	address + contact info object		The address from which the shipment is being shipped.
`shipTo`	address + contact info object		The address to which the shipment is being shipped.
`pickupLocation`	address + contact info + pickup location object	✔	The location where the recipient can pick up the shipment.
`returnTo`	address + contact info object		The address to which to send the shipment in the case of a return. This may be different from the `shipFrom` address if the customer uses a centralized returns processing facility.
`shipDateTime`	date/time object		The date/time that the package is expected to ship. This is not guaranteed to be in the future.
`totalInsuredValue`	object		The total insured value of all packages in the shipment.
`totalInsuredValue.value`	number		The value of the insured amount.
`totalInsuredValue .currency`	string		The currency that the value represents.
`isNonMachineable`	boolean		Indicates whether the shipment cannot be processed automatically due to size, shape, weight, etc. and requires manual handling. This property is `true` if any package in the shipment is non-machinable.
`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.
`returns.rmaNumber`	string		A return merchandise authorization (RMA) is an associated number assigned to process the return. This number is often printed on the label and used when the original shipper processes the inbound return. This string will not contain newline characters.
`packages`	new package object[]		The list of packages in this shipment.
`package`	new package object		Returns the first package in the `packages` array. Useful for carriers that only support single-piece shipments.
`deliveryConfirmation`	delivery confirmation object	✔	The requested delivery confirmation for this shipment.
`shippingOptions`	shipping options	✔	The shipping options that are required for this shipment.

Return Value

`shipmentConfirmation`

An object that contains confirmation that a shipment has been created.

Name	Type	Required?	Description
`label`	object	✔	An object representing the shipping label details.
`label.name`	string		The user-friendly name of the label. This string must not contain newline characters.
`label.type`	string	✔	The type of document. This value should always be `label` for label objects. This object type is also used for customs forms and scan forms.
`label.size`	string	✔	The size of the label. Valid values include the following: `A4`- A4 sized paper ( 8.27 inches x 11.69 inches) `letter` - Letter sized paper (8.5 inches by 11 inches) `4x6` - Paper sized 4 inches by 6 inches `4x8` - Paper sized 4 inches by 8 inches
`label.format`	string	✔	The file format of the label. Valid values include the following: `pdf` - Portable Document Format (PDF) `zpl` - Zebra Printer Label (ZPL) `png` - Portable Graphics Format (PNG)
`label.data`	Buffer object	✔	The label data, in the specified file format.
`label.referenceFields`	string[]	✔	The actual reference fields on the label, which may not match the originally-specified reference fields due to the carrier's restrictions on the number of fields or the length of each field. Each string in this array must not contain newline characters.
`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".
`form`	object		An object representing a form, such as a customs form or scan form. This property is not required. If it is provided, it must contain all of its required properties, listed below.
`form.name`	string		The user-friendly name of the form (e.g. "Customs Form", "Scan Form"). This string must not contain newline characters.
`form.type`	string	✔	The type of form. This value should be `customs_form` or `scan_form`.
`form.size`	string	✔	The size of the form. Valid values include the following: `A4`- A4 sized paper ( 8.27 inches x 11.69 inches) `letter` - Letter sized paper (8.5 inches by 11 inches) `4x6` - Paper sized 4 inches by 6 inches `4x8` - Paper sized 4 inches by 8 inches
`form.format`	string	✔	The file format of the form. Valid values include the following: `pdf` - Portable Document Format (PDF) `zpl` - Zebra Printer Label (ZPL) `png` - Portable Graphics Format (PNG)
`form.data`	Buffer object	✔	The form data, in the specified file format.
`trackingNumber`	string		The master tracking number for the entire shipment. For single-piece shipments, this will be the same as the package tracking number. For multi-piece shipments, this may be a separate tracking number, or the same tracking number as one of the packages. This string must not contain newline characters.
`identifiers`	identifiers object		Your own identifiers for this shipment.
`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.
`packages`	object[]		An array of objects containing confirmation details about each package in the shipment. This array will contain at least one item.
`packages[].trackingNumber`	string		The master tracking number for the entire shipment. For single-piece shipments, this will be the same as the package tracking number. For multi-piece shipments, this may be a separate tracking number, or the same tracking number as one of the packages. This string must not contain newline characters.
`packages[].identifiers`	identifiers object		Your own identifiers for this package.
`packages[].metadata`	object		Custom data about this package that will be persisted by ShipEngine Connect. Must be JSON serializable.

Example

module.exports = async function createShipment(transaction, shipment) {
  // STEP 1: Validation
  for (let parcel of shipment.packages) {
    if (parcel.packaging.id === OWN_PACKAGING && parcel.weight.grams > 100000) {
      throw new Error(`${parcel.packaging.name} cannot weigh more than 100 kilograms`);
    }
  }
  // STEP 2: Create the data that the carrier's API expects
  let data = {
    operation: "generate_label",
    session_id: transaction.session.id,
    service_code: shipment.deliveryService.code,
    confirmation_code: shipment.deliveryConfirmation.code,
    ship_date: shipment.shipDateTime.toISOString(),
    from_zone: parseInt(shipment.shipFrom.postalCode, 10),
    to_zone: parseInt(shipment.shipTo.postalCode, 10),
    total_weight: shipment.package.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 await formatShipment(response.data);
}

import {
  ChargeType,
  DocumentFormat,
  DocumentSize,
  DocumentType,
  NewShipment,
  ShipmentConfirmation,
  Transaction
} from "@shipengine/connect";
export default async function createShipment(
  transaction: Transaction<Session>, shipment: NewShipment): Promise<ShipmentConfirmation> {
  // STEP 1: Validation
  for (let parcel of shipment.packages) {
    if (parcel.packaging.id === box.id && parcel.weight.ounces > (150 * 16)) {
      throw new Error(`${parcel.packaging.name} cannot weigh more than 150 pounds`);
    }
    else if (parcel.packaging.id === bag.id && parcel.weight.ounces > (45 * 16)) {
      throw new Error(`${parcel.packaging.name} cannot weigh more than 45 pounds`);
    }
  }
  // STEP 2: Create the data that the carrier's API expects
  let data: GenerateLabelRequest = {
    operation: "generate_label",
    session_id: transaction.session.id,
    service_code: shipment.deliveryService.code,
    confirmation_code: shipment.deliveryConfirmation.code,
    ship_date: shipment.shipDateTime.toISOString(),
    from_zone: parseInt(shipment.shipFrom.postalCode, 10),
    to_zone: parseInt(shipment.shipTo.postalCode, 10),
    total_weight: shipment.package.weight.ounces,
  };
  // STEP 3: Call the carrier's API
  const response = await apiClient.request<GenerateLabelResponse>({ data });
  // STEP 4: Create the output data that ShipEngine expects
  return formatShipment(response.data);
}