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.
Name | Type | Nullable? | Description |
---|---|---|---|
authorization | ✔ | The authorization information necessary to fulfill this request. | |
metadata | ✔ | 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_code | string | Code used to map to what the carrier uses to identify the service. | |
ship_datetime | string | 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 | ✔ | The requested confirmation for this label. If the field is absent it should be interpreted as "None". | |
label_format | string | ✔ | The requested document format for this label. Valid values include the following:
|
label_layout | string | ✔ | The requested label layout for this label. Valid values include the following:
|
is_test_label | boolean | ✔ | 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_options | ✔ | This contains an optional set of properties describing the advanced options a user might select. | |
insurance_provider | string | ✔ | The insurance provider for the insured value of the label,
Valid values include the following:
|
is_return_label | boolean | Indicates whether the label is a return. | |
is_residential | boolean | Indicates whether the label is to a residential address. | |
packages | All the packages that make up this shipment. There will always be at least one package defined. | ||
ship_to | The shipment recipient's address. It may or may not have been validated. | ||
ship_from | The shipment sender's address. It may or may not have been validated. | ||
pickup_location | ✔ | Some carriers allow for a pickup location to be specified that differs from the If the carrier supports pickup locations and this field is populated, this will be the actual origin of the shipment and the
| |
relay_points | object | ✔ | Some carriers allow for shipments to be sent from and delivered to carrier official locations named relay points. These official locations might be lockers or a third party business that holds packages for the carrier. If this is a shipment that uses relay points, this field will show which relay points to ship from and to.
|
relay_points.ship_to | The destination relay point for the shipment. | ||
relay_points.ship_from | The origin relay point for the shipment. | ||
ship_from_display | ✔ | The address that should be displayed as the return address, only if the carrier supports this functionality. | |
next_day | boolean | ✔ | Indicates whether this shipment is expected to use a next day service class. If the field is absent it should be interpreted as false |
international | boolean | ✔ | Indicates Whether the shipment is international. |
reference | string | ✔ | A user specified free form string to identify this shipment in their own system. |
return_details | object | ✔ | If the label is for a return, return details should be specified. |
return_details.rma_number | 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. | |
fulfillment_plan_details | ✔ | Details regarding the fulfillment plan and/or original sales order, only if the carrier provider requires this info for label generation. | |
attachments | ✔ | 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.
Name | Type | Required? | Description |
---|---|---|---|
metadata | 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_id | string | ✔ | 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 | 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 | 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 | Individual Billing Line items for the label. | ||
tracking_number | string | The carrier specific tracking identifier for this shipment; if a multi-package shipment, this should be the lead tracking number. | |
trackable | boolean | Indicates whether this shipment can be tracked. | |
alternative_identifiers | Alternative identifiers associated with this shipment. | ||
estimated_delivery_datetime | string | The estimated date and time for when the shipment will be delivered. Formatted per the https://tools.ietf.org/html/rfc3339 spec. | |
relay_points | object | If this is a shipment that uses relay points, this will show which relay points to ship from and to. | |
relay_points.ship_to | ✔ | The destination relay point for the shipment. | |
relay_points.ship_from | ✔ | The origin relay point for the shipment. |
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);}