CreateLabel()

This method creates a new label.

Syntax

module.exports = async function CreateLabel(request) {
// Your code here
}
import { CreateLabelRequest, CreateLabelResponse } from "@shipengine/connect-carrier-api";
export default async function CreateLabel(
request: CreateLabelRequest
): Promise<CreateLabelResponse> {
// Your code here
}

Parameters

CreateLabelRequest

An object containing information about the new label to create.

NameTypeNullable?Description
authorization

authorization object

The authorization information necessary to fulfill this request.

metadata

metadata object

This object should contain all of the necessary properties needed to make authenticated requests with the carrier when an AuthProcess has not been configured. Every property included here will be persisted by ShipEngine Connect and included on each subsequent request from this user.

service_codestring

Code used to map to what the carrier uses to identify the service.

ship_datetimestring

When the package is expected to ship. Not guaranteed to be in the future. Formatted per the https://tools.ietf.org/html/rfc3339 spec. Will always be in UTC.

confirmation

confirmation type

The requested confirmation for this label. If the field is absent it should be interpreted as "None".

label_formatstring

The requested document format for this label.

Valid values include the following:

  • PDF
  • ZPL
  • PNG
label_layoutstring

The requested label layout for this label.

Valid values include the following:

  • 4x6
  • letter
is_test_labelboolean

Whether this request is the result of a test. When true the request must not result in any financial charges to any party. If the field is absent it should be interpreted as false

advanced_optionsobject

This is a schemaless object. It is for open ended customizations unique to particular carriers. If the field is absent it should be interpreted as the default value for any applicable options, e.g. false for booleans.

insurance_providerstring

The insurance provider for the insured value of the label, carrier indicates that the user is requesting insurance from the carrier directly, anything else is extra information that should not result in a transaction.

Valid values include the following:

  • None
  • Shipstation
  • Carrier
  • External
is_return_labelboolean

Indicates whether the label is a return.

is_residentialboolean

Indicates whether the label is to a residential address.

packages

package object[]

All the packages that make up this shipment. There will always be at least one package defined.

ship_to

shipping address object

The shipment recipient's address. It may or may not have been validated.

ship_from

shipping address object

The shipment sender's address. It may or may not have been validated.

pickup_location

pickup location object

If this is a pickup shipment, a pickup location will be populated for where the recipient can pickup the shipment.

ship_from_display

shipping address object

The address that should be displayed as the return address, only if the carrier supports this functionality.

next_dayboolean

Indicates whether this shipment is expected to use a next day service class. If the field is absent it should be interpreted as false

internationalboolean

Indicates Whether the shipment is international.

referencestring

A user specified free form string to identify this shipment in their own system.

return_detailsobject

If the label is for a return, return details should be specified.

return_details.rma_numberstring

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.

fulfillment_plan_details

fulfillment plan details object

Details regarding the fulfillment plan and/or original sales order, only if the carrier provider requires this info for label generation.

attachments

document object[]

Attachments that may be required to be sent to the carrier, in particular customs documents or commercial invoices.

Return Value

CreateLabelResponse

This object model represents the response from a successful create label request.

NameTypeRequired?Description
metadata

metadata object

This object should contain all of the necessary properties needed to make authenticated requests with the carrier. Every property included here will be persisted by ShipEngine Connect and included on each subsequent request from this user.

transaction_idstring

The transaction ID uniquely represents this request. If the request is retried then this transaction ID will be the same. You should only perform the requested action once per given transaction ID.

documents

documents object[]

Shipment level documents should be used if documents are not returned at a package level.

DO NOT include duplicate documents intentionally, a document should only be added to the CreateLabelResponse or to the LabelPackage.

packages

label package object[]

Package information returned for each requested package in the shipment.

Note: The order of the packages returned should match the order of the packages in the request.

billing_line_items

billing line item object[]

Individual Billing Line items for the label.

tracking_numberstring

The carrier specific tracking identifier for this shipment; if a multi-package shipment, this should be the lead tracking number.

trackableboolean

Indicates whether this shipment can be tracked.

alternative_identifiers

identifier object[]

Alternative identifiers associated with this shipment.

estimated_delivery_datetimestring

The estimated date and time for when the shipment will be delivered. Formatted per the https://tools.ietf.org/html/rfc3339 spec.

Example

module.exports = async function CreateLabel(request) {
let totalWeight = 0;
// STEP 1: Validation
for (let parcel of request.packages) {
if (parcel.weight_details.weight_in_grams > 100000) {
throw new Error(`${parcel.package_code} cannot weigh more than 100 kilograms`);
}
totalWeight += parcel.weight_details.weight_in_grams;
}
// STEP 2: Create the data that the carrier's API expects
let data = {
operation: "generate_label",
session_id: request.metadata.id,
service_code: request.service_code,
confirmation_code: request.confirmation,
ship_date: request.ship_datetime,
from_zone: parseInt(request.ship_from.postal_code, 10),
to_zone: parseInt(request.ship_to.postal_code, 10),
total_weight: totalWeight,
};
// STEP 3: Call the carrier's API
const response = await apiClient.request({ data });
// STEP 4: Create the output data that ShipEngine expects
return formatShipment(response.data);
}
import {
CreateLabelRequest,
CreateLabelResponse
} from "@shipengine/connect-carrier-api";
export default async function CreateLabel(request: CreateLabelRequest): Promise<CreateLabelResponse> {
let totalWeight = 0;
// STEP 1: Validation
for (let parcel of request.packages) {
if (parcel.weight_details.weight_in_grams > 100000) {
throw new Error(`${parcel.package_code} cannot weigh more than 100 kilograms`);
}
totalWeight += parcel.weight_details.weight_in_grams;
}
// STEP 2: Create the data that the carrier's API expects
let data: GenerateLabelRequest = {
operation: "generate_label",
session_id: request.metadata.id,
service_code: request.service_code,
confirmation_code: request.confirmation,
ship_date: request.ship_datetime,
from_zone: parseInt(request.ship_from.postal_code, 10),
to_zone: parseInt(request.ship_to.postal_code, 10),
total_weight: totalWeight,
};
// 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);
}