Create Shipment

Note: This Request sample includes the full set of supported fields across all carriers. However, not all fields are applicable to every carrier. When making API calls from the doc portal, ensure you include only the parameters supported by the specific carrier you are integrating with. If unsupported fields are included, the request may fail.
To simplify integration and avoid errors, refer to the Postman Collection.
To explore which label types, label formats, label sizes, parcel types, services, and special services are supported by each carrier, see the Carrier Catalog. Detailed field descriptions are also provided below.

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

4. By CustomCarrierCode

  • Instead of passing multiple fields (carrier, carrier account, parcel type, service, and special services) every time in your request payload, you can:

    • Generate a Custom Carrier Code once, with all those values defined.

    • Use that single code in your create shipment requests.

    • The carrier, account, service, parcel type, and special service values from that code will then automatically apply.

  • If parcel type, service, or special services are also passed in the request payload, they will be overridden by the values defined in the Custom Carrier Code.

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
    • byCustomCarrierCode: code

  • Define special services in one of two ways - by using a specialServiceId or by specifying special service objects such as deliveryConfirmation, handling, insurance, or returnOptions. These two cannot be used together in the same request.

SecuritybearerAuth
Request
query Parameters
isReturn
required
boolean

Applies only to carriers UPS and FedEx; For UPS, if isReturn is passed, you must either include the returnOptions object (when using individual service objects) or specify the serviceId:PRL (when using specialService), or an error will occur. For FedEx, If isReturn is set to true, the returnOptions object is optional.

includeDeliveryCommitment
string
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 four approaches: by Carrier, by RateGroup, by RuleSet and by CustomCarrierCode**.
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.
Through customCarrierCode, customers can create a shipment using a single code (Custom Carrier Code) that represents a specific combination of carrier, carrier account, parcel type, service, and special services.

Enum: "carrier" "rateGroup" "ruleSet" "customCarrierCode"
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 FedEx Carrier Payment (object) or UPS Carrier Payment (object) or DHL Express Carrier Payment (object) (carrierPayments)

Defines how carrier charges are billed to a third party. Use this field to specify account and charge type details for transportation and/or duties and taxes. This field is optional and currently supported for FedEx, UPS, and DHL Express.

  • If no party (who will pay for TRANSPORTATION_CHARGES or duties and taxes) is explicitly specified during shipment creation, the charges will automatically default to the sender (shipper). To direct charges to a different party, the appropriate bill-to details must be provided in the request.
object

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

Array of objects (SpecialService)

It provides a carrier based special or extra service, which also varies as per selected service and parcel type. User can override this value by defining it at shipment level.

Provide either the specialserviceId or the specialservice objects such as deliveryConfirmation, handling, insurance and returnOptions, but not both.

object

Indicates the supporting special service or document as an evidence of shipment delivery.

Provide either the specialserviceId or the specialservice objects such as deliveryConfirmation, handling, insurance and returnOptions, but not both.

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.

Provide either the specialserviceId or the specialservice objects such as deliveryConfirmation, handling, insurance and returnOptions, but not both.


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.

Provide either the specialserviceId or the specialservice objects such as deliveryConfirmation, handling, insurance and returnOptions, but not both.

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.
Supported values are Cost Account Name, Cost Account Id, Cost Account Code, Account Code and Company Code

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.

Provide either the specialserviceId or the specialservice objects such as deliveryConfirmation, handling, insurance and returnOptions, but not both.

object

Customs information required for international shipments.

  • Required only for RMG carrier in domestic shipment requests.
  • Must include customsItems and customsInfo objects.
  • Other carriers do not require this object for domestic shipments.
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": {
    },
  • "specialServices": [
    ],
  • "deliveryConfirmation": {
    },
  • "handling": {
    },
  • "insurance": {
    },
  • "references": {
    },
  • "metadata": [
    ],
  • "labelSize": "DOC_4X6",
  • "labelType": "SHIPPING_LABEL",
  • "labelFormat": "ZPL2",
  • "contentType": "BASE64",
  • "printerAliasName": "test",
  • "dateOfShipment": "2024-03-20",
  • "deliveryOption": {
    },
  • "returnOptions": {
    },
  • "customs": {
    }
}
Response samples
application/json
{
  • "correlationId": "3e2a71cc421e40b7970db9d540b1c7f2",
  • "shipmentId": "FEDEX2200626443337314",
  • "parcelTrackingNumber": 329039098457,
  • "labelLayout": [
    ],
  • "parcel": {
    },
  • "rate": {
    },
  • "references": {
    },
  • "printStatus": "submitted",
  • "printError": {
    },
  • "fromAddress": {
    },
  • "toAddress": {
    },
  • "soldToAddress": {
    },
  • "additionalAddresses": [
    ],
  • "shipmentOptions": {
    },
  • "carrierPayments": [
    ]
}