Create Shipment

The Create Shipment API is used to create shipments and generate shipment labels. A shipment refers to the process of packing and transporting an item from a source location to a destination location using a carrier service. The API supports both domestic and international shipments.

Domestic Shipments

  • Both the toAddress and fromAddress addresses must be within the same country.
  • Requires carrier services and associated special services.

International Shipments

  • The toAddress must be in a different country than the fromAddress.
  • Requires international carrier services, special services, and customs information.

The V2 Create Shipment API compares shipping rates, services, and options across multiple carriers. It selects the best shipping solution based on criteria such as cost, delivery speed, or other business rules. This automates decision-making and eliminates the need for manual analysis of carrier data. It supports three RateShop types:

1. By Carrier:

  • Manually specify the carrier and service for shipment creation.
  • Provides more customization than V1 Create Shipment.

2. By RuleSet

  • Automatically select the best carrier and service based on predefined rules (e.g., cheapest, fastest). For example:
  • Shipments weighing up to 3kg use a "Standard" service type with carrier A.
  • Shipments exceeding 3kg use an "Over-weight" service type with carrier B.
  • Rules are fully client-defined, allowing for dynamic decision-making based on shipment parameters like weight, dimensions, and destination.

3. By RateGroup

  • Use predefined rate groups to select a carrier and service dynamically.For example:
  • Clients can choose between the fastest delivery or the cheapest service rate among a predefined group of carriers.
  • The system automatically determines and selects the best carrier and service, without the need for manual comparisons.

Notes

  • The rateShopBy field determines the variant to use (carrier, ruleset, or rategroup).
  • Ensure that variant-specific fields are correctly populated:
    • byCarrier: carrierAccountId, carrier, and service
    • byRuleSet: ruleType and shipOption
    • byRateGroup: ruleType and rateGroupId
SecuritybearerAuth
Request
query Parameters
isReturn
required
boolean

Applies only to carriers UPS and FedEx; for UPS, returnOptions object in the request body is required, or an error will occur. For FedEx, If isReturn is set to true, the returnOptions object is optional.

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

The Developer Partner ID is assigned by PB to uniquely identify a Developer's strategic business partners. If the developer is the sole business partner, this field isn't required.

X-PB-LocationId
string

This is the Location ID assigned as per the Developer's and Partner's parsed locations, to which all transactions will be billed.
Partner's location will be used for billing if it is configured, however, in case Partner's location is not given, then the Developer's location will be taken. Developer's location will be the default value.
Additionally, Developers and Partners can use carriers belong to this location only.

X-PB-TransactionId
string

A unique Transaction ID provided by the partner, which is used to enable debugging and linking between the client's transaction and the system.

X-PB-Default-ID
string

A unique identifier assigned to the Default while its creation using CreateDefaults API.

Request Body schema: application/json
One of:
required
object (fromAddressV2)

The complete address of the Sender.

required
object (toAddressV2)

The complete address of the Recipient or Department (in case if the address is not pointed to any individual recipient).

object (soldToAddressV2)

Billing address of the buyer responsible for the shipment payment. It can be domestic or international address.

  • 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.
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.

object (parcelV2)

The details of the Parcel.

parcelType
required
string

Parcel Type is required for creating a shipment while rating a parcel, which varies as per Carrier selection.
ParcelType can have categories like Package, Envelopes, Paks, Boxes, Tube, etc.
Max length = 30

rateShopBy
required
string

RateShop, which is attached to an Enterprise or Location, is done through three approaches: by Carrier, by RateGroup, and by Ruleset.
Through Carrier, customers can choose the carriers as per requirement, based on which services, parcel types, and special services can be selected, and RateShop is done.
Through RateGroup, customers can select the RateGroup, which has been divided into two categories: Cheapest (w.r.t. price) and Fastest (w.r.t. delivery hours).
Through Ruleset, customers can define the Condition/rule for selecting carriers and their services, so they do not need to worry for Rate Shopping every time they create Shipment. For example, For a particular location, they can set one definite carrier, or apply RateGroup - Cheapest/Fastest. Similarly, for a particular amount like below $1000 Dollars, they can select a definite carrier service, based on RateGroup.

Enum: "carrier" "rateGroup" "ruleset"
object (byCarrierV2)

The shipment is grouped by Carrier and their Service.

object

Shipment Options have an added feature that is Manifest.
With Manifest, the Mail Center agent can print the Manifest (End of day records of all created shipment) of selected carrier.

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.

object

This option is used to provide additional information into the label's additional space. It is supported only for doc size 4x6_75.

object

Indicates the supporting special service or document as an evidence of shipment delivery. For the delivery confirmation, user can select any of the following special services, but they may vary as per the carrier selection.

  • Signature Required/ Indirect Signature Required : SIGNATURE
  • Delivery confirmation: DELIVERY_CONFIRMATION
  • Proof of age required (18 years) Adult Signature Required: ADULT_SIGNATURE
  • Proof of age required (19 years): ADULT_SIGNATURE_19
  • No Signature Required: NO_SIGNATURE
  • Direct Signature Required: DIRECT_SIGNATURE
  • Chain of Signature: CHAIN_OF_SIGNATURE

Carrier specific options:

  • UPS supports SIGNATURE and ADULT_SIGNATURE.
  • FedEx supports SIGNATURE, ADULT_SIGNATURE, NO_SIGNATURE, and DIRECT_SIGNATURE.
  • Purolator supports ADULT_SIGNATURE, NO_SIGNATURE, and CHAIN_OF_SIGNATURE.
  • GoFor supports SIGNATURE.
  • CPC supports SIGNATURE, DELIVERY_CONFIRMATION, ADULT_SIGNATURE, ADULT_SIGNATURE_19, and NO_SIGNATURE.
object

Few shipments need a special handling, and the reason can be fragile items or highly secured shipments. There might be other case scenarios. In a simple term, this field defines shipment handling, which provides users a capability to select handling options.
User can select any of the following handling options (special services), but they may vary as per the carrier selection.

  • Hold For Pickup: HOLD_FOR_PICKUP
  • Saturday Delivery: SATURDAY_DELIVERY
  • UPS Premium Care: PREMIUM_CARE
  • Direct Delivery Only: DIRECT_DELIVERY_ONLY
  • Additional Handling: ADDITIONAL_HANDLING

Carrier specific options:

  • UPS supports all handling options mentioned above.
  • FedEx supports HOLD_FOR_PICKUP, SATURDAY_DELIVERY, and ADDITIONAL_HANDLING.
  • Purolator supports HOLD_FOR_PICKUP, SATURDAY_DELIVERY, and ADDITIONAL_HANDLING.
object

Indicates the insurance coverage, which is selected by users while create shipment - rate shopping. User can select below-mentioned special service for insurance:

  • Declared Value Surcharge: INSURANCE

Carrier specific options:

  • UPS, FedEx, Purolator, and CPC support special service INSURANCE.
object (referenceV2)

References are tags or information that is printed on Shipping Label based on the customer's requirement.
Reference Fields can have values/indication like department name, invoice no., package description, purchase order no., carrier note, cost account no., transportation no., or PO no., print custom message etc.
Each of the reference field can have only one indication/value.

Array of objects

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

labelSize
required
string

Defines the label size of the Shipment, that is, the Shipping Label is available in different Doc Size.
Max length = 10

Enum: "DOC_8X11" "DOC_4X8" "DOC_4X6"
labelType
required
string

Defines the type of the Shipment. QR_CODE supported for carrier USPS only as of now.
Max length = 14

Enum: "SHIPPING_LABEL" "QR_CODE"
labelFormat
required
string

"Defines the file/format in which the label is printed.
For ZPL2, DOC_4X6 will be supported, while for PDF, both the sizes are supported. QR_CODE can be generated only in GIF format. Max length = 14"

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"
printerAliasName
string

Refers to a printer connected (directly or via network) to a computer. Max length = 60

dateOfShipment
string <date>

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

object

There are two options of delivery: deliverBy and useBestNextDate, where customer can schedule the delivery date in deliverBy.
In case if the customer's scheduled deliverBy date falls under Holiday, then useBestNextDate will be used by our system. Then, we will mark the second option and deliver the same.

object

This object defines return shipment options. It should be passed when requesting return labels. Supported only for carriers UPS and FedEx as of now.
For UPS, this object is required.
For FedEx, this object is optional.
Note: The returnOptions object must be sent with the isReturn query parameter.

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/v2/shipments
Request samples
application/json
{
  • "fromAddress": {
    },
  • "toAddress": {
    },
  • "soldToAddress": {
    },
  • "additionalAddresses": [
    ],
  • "altReturnAddress": {
    },
  • "parcel": {
    },
  • "parcelType": "PKG",
  • "rateShopBy": "carrier",
  • "byCarrier": {
    },
  • "shipmentOptions": {
    },
  • "carrierPayments": [
    ],
  • "docTab": {
    },
  • "deliveryConfirmation": {
    },
  • "handling": {
    },
  • "insurance": {
    },
  • "references": {
    },
  • "metadata": [
    ],
  • "labelSize": "DOC_4X6",
  • "labelType": "SHIPPING_LABEL",
  • "labelFormat": "ZPL2",
  • "contentType": "BASE64",
  • "printerAliasName": "test",
  • "dateOfShipment": "2024-03-20",
  • "deliveryOption": {
    },
  • "returnOptions": {
    }
}
Response samples
application/json
{
  • "correlationId": "3e2a71cc421e40b7970db9d540b1c7f2",
  • "shipmentId": "FEDEX2200626443337314",
  • "parcelTrackingNumber": 329039098457,
  • "labelLayout": [
    ],
  • "parcel": {
    },
  • "rate": {
    },
  • "references": {
    },
  • "printStatus": "submitted",
  • "printError": {
    },
  • "fromAddress": {
    },
  • "toAddress": {
    },
  • "soldToAddress": {
    },
  • "additionalAddresses": [
    ],
  • "shipmentOptions": {
    },
  • "carrierPayments": [
    ]
}