CreateLabel

This method creates a new label.

Request
query Parameters
transactionId
string <uuid>

The transaction ID uniquely represents this request.

Request Body schema: application/json

An object containing information about the new label to create.

service_code
required
string or null

The service code uniquely identifies a shipping service that you offer. Which service codes can be passed to you will be configured in ShipEngine.

ship_datetime
required
string <date-time>

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
string (ConfirmationTypes)
Enum: "None" "Delivery" "Signature" "AdultSignature" "DirectSignature"
label_format
string (DocumentFormat)
Enum: "PDF" "ZPL" "PNG"
label_layout
string (LabelLayouts)
Enum: "4x6" "letter"
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

object (AdvancedOptions)

This is a schemaless object. It is for open ended customizations unique to particular carriers. The documented keys are some common options shared by many carriers, but are not definitive. Advanced options you support will be defined in ShipEngine. If the field is absent it should be interpreted as the default value for any applicable options, e.g. false for booleans.

insurance_provider
string (InsuranceProviders)
Enum: "None" "ShipStation" "Carrier" "External" "XCover" "ParcelGuard"
is_return_label
required
boolean

Whether this label is to return a previously shipped package. If the field is absent it should be interpreted as false.

required
Array of objects or null (Package)

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

object (Customs)
required
object (ShipTo)
required
object (ShipFrom)

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

object (PudoLocation)

Pickup/Dropoff Location used by carriers that offer this service.

object (RelayPointDetails)

Details of the relay points used for the shipment

object (ShipFromDisplay)

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

next_day
boolean or null

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 or null

Whether this shipment is deemed international.

reference
string or null

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

object (ReturnLabelDetails)

Return Label Information (Added 1.13)

object (FulfillmentPlanDetails)

This model contains information about the fulfillment plan.

Array of objects or null (Document)

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

object (BillTo)

Bill to is a generic object used for billing a part of the shipment, duties, taxes, or otherwise to a party other than the shipper (the shipper is considered the default party responsible). CarrierApi.Common.Request.CarrierApi.Common.Models.BillTo extends CarrierApi.Common.Models.Addresses.AddressWithContact since address fields are often required when associating billing to another account. Additionally, this allows for a contact to be specified, if necessary.

object (TimeWindow)
carrier_rate_id
string or null

Unique identifier for the carrier rate

display_schemes
Array of strings or null (DisplayScheme)

Display schemes that the label will be returned in. Label is returned by default

Enum: "label" "paperless_label"
transaction_id
required
string <uuid>

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.

object (Authorization)
object or null
connection_name
string or null

The name of the connection to use, if this app has connection names defined

Responses
200

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

post/CreateLabel
Request samples
application/json
{
  • "service_code": "string",
  • "ship_datetime": "2019-08-24T14:15:22Z",
  • "confirmation": "None",
  • "label_format": "PDF",
  • "label_layout": "4x6",
  • "is_test_label": true,
  • "advanced_options": {
    },
  • "insurance_provider": "None",
  • "is_return_label": true,
  • "packages": [
    ],
  • "customs": {
    },
  • "ship_to": {
    },
  • "ship_from": {
    },
  • "pickup_location": {
    },
  • "relay_points": {
    },
  • "ship_from_display": {
    },
  • "next_day": true,
  • "international": true,
  • "reference": "string",
  • "return_details": {
    },
  • "fulfillment_plan_details": {
    },
  • "attachments": [
    ],
  • "bill_shipping_to": {
    },
  • "carrier_pickup_window": {
    },
  • "carrier_rate_id": "string",
  • "display_schemes": [
    ],
  • "transaction_id": "0fec1e58-b197-4052-99cf-2218496c5482",
  • "authorization": {
    },
  • "metadata": {
    },
  • "connection_name": "string"
}
Response samples
application/json
{
  • "transaction_id": "0fec1e58-b197-4052-99cf-2218496c5482",
  • "documents": [
    ],
  • "packages": [
    ],
  • "billing_line_items": [
    ],
  • "tracking_number": "string",
  • "tracking_url": "string",
  • "trackable": true,
  • "alternative_identifiers": [
    ],
  • "estimated_delivery_datetime": "1937-01-01T12:00:27.87+00:20",
  • "consolidator_service_code": "string",
  • "carrier_pickup_window": {
    },
  • "delivery_window": {
    },
  • "relay_points": {
    },
  • "paperless_details": {
    },
  • "metadata": {
    }
}