Create Shipment

The operation creates a new Shipment or generate a Shipment Label. Here, Shipment refers to process where an item is packed and shipped from one point (source) to the other (destination) using some carrier service. This operation is also used to generate a return shipment label.

The shipment can be done for both domestic and overseas/International places.

  • To create a domestic shipment, the operation requires
    • Domestic addresses 'To' and 'From' locations respectively within the same country
    • carrier services, and
    • associated special services.
  • While for the International shipment, the operation requires
    • International address(es) for delivery, that is 'To' address must be the international country location(s) and not the same country mentioned in 'From' address
    • supported international carrier services
    • associated special service(s), and
    • customs information.
SecuritybearerAuth
Request
query Parameters
includeDeliveryCommitment
boolean
Default: true

When set to true (default), the response includes delivery commitment information. Set to false to exclude delivery commitment details from the response.

header Parameters
X-PB-Developer-Partner-Id
string

This is the Developer Partner ID. When the developer is the only partner, this field is not required.

Request Body schema: application/json
One of:
size
required
string

Defines the label size of the Shipment, e.g., Shipping Label having Doc Size (4' X 6' or 8.5' X 11').

Enum: "DOC_8X11" "DOC_4X6"
type
required
string

Defines the type of the Shipment, e.g., Shipping Label.QR_CODE supported for carrier USPS only as of now.

Enum: "SHIPPING_LABEL" "QR_CODE"
format
string

Defines the type of the shipment label that is printed. QR_CODE can be generated only in GIF format.

Enum: "PDF" "ZPL2" "PNG" "GIF"
contentType
string

Specifies how the label content is encoded.
URL is supported for PDF and GIF.
BASE64 is supported for ZPL2, PNG, and GIF.

Enum: "URL" "BASE64"
dateOfShipment
string <date>

The date when shipment is created/shipped. The format of the Date is YYYY-MM-DD.

required
object
object

This is an optional field. if a package shipped from Location_A to Location_B needs to return to Location_C. The alternate address will be printed on the label. Use this object to specify a return address different from the fromAddress. Supported by FedEx, UPS, and Purolator.

required
object
carrierAccountId
required
string

A unique identifier associated with the Carrier account used by client users during shipment process.

parcelType
required
string

-Parcel Type is required for creating a shipment while rating a parcel, which varies as per Carrier selection. It has categories like Package, Envelopes, Paks, Boxes, Tube, defined per specific carrier and used in abbreviated form, e.g., FRPKG, LGENV, TUBE, PKG.

serviceId
required
string

-A unique identifier given to the carrier-specific service. This is required for creating a shipment, while it is optional for rating a parcel.

Array of objects (SpecialService)

It provides a carrier-service based special or extra service.

object (shipmentOptions)
object

This option is used to provide additional information into the label's additional space.

  • Supported for carrier FedEx as of now.
  • Supported format is ZPL2 and doc size is 4x6_75for fedEx.
Array of objects

If one or more of the shipment costs should be charged to a third-party account, enter the information in this array. This is an optional field. Supported by FedEx, UPS, DHL Express, CPC, and Purolator.

Array of objects

Additional metadata that needs to be stored for this shipment can be added here. For now, 'Cost Account Name' is supported.

required
object
required
object

Details of the third-party address used for shipments. This address is required only for LaserShip carrier.

object (soldToAddress)

Billing address of the buyer responsible for the shipment payment. It can be domestic or international address. This is a required field for carrier UPS.

  • If the importer is the same as the final recipient, the toAddress and soldToAddress must match.
  • If the importer is different from the final recipient, enter the importer address in the soldToAddress and enter the final recipient's address in the toAddress.
Array of objects (additionalAddresses)

A list of additional addresses associated with the shipment.

  • Each object includes an address and its designated type, such as BROKER or other parties involved in customs or shipping processes.
  • Additional address could be domestic or International both.
Responses
200

The shipment has been created successfully.

400

Invalid request.

401

The request could not be authorized.

500

The request could not be completed due to an internal error.

post/api/v1/shipments
Request samples
application/json
{
  • "size": "DOC_4X6",
  • "type": "SHIPPING_LABEL",
  • "format": "PDF",
  • "contentType": "URL",
  • "dateOfShipment": "2024-03-20",
  • "fromAddress": {
    },
  • "altReturnAddress": {
    },
  • "parcel": {
    },
  • "carrierAccountId": "asas2223",
  • "parcelType": "PKG",
  • "serviceId": "PM",
  • "specialServices": [
    ],
  • "shipmentOptions": {
    },
  • "docTab": {
    },
  • "carrierPayments": [
    ],
  • "metadata": [
    ],
  • "toAddress": {
    },
  • "thirdPartyAddress": {
    },
  • "soldToAddress": {
    },
  • "additionalAddresses": [
    ]
}
Response samples
application/json
{
  • "correlationId": "00adf56ed852487ba9caec62b7ab2635",
  • "fromAddress": {
    },
  • "altReturnAddress": {
    },
  • "parcel": {
    },
  • "parcelTrackingNumber": "9471309105156000826739",
  • "labelLayout": [
    ],
  • "rate": {
    },
  • "shipmentId": "USPS2200579677758143",
  • "shipmentOptions": {
    },
  • "carrierPayments": [
    ],
  • "toAddress": {
    },
  • "thirdPartyAddress": {
    },
  • "soldToAddress": {
    },
  • "additionalAddresses": [
    ]
}