# 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 following 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 ShipViaCode - Instead of passing multiple fields (carrier, carrier account, parcel type, service, and special services) every time in your request payload, you can: - Generate a Ship Via 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. 5. By byExternalSystemCode - This enables shipment creation using an external System Code (For SPE users). - When an ExternalSystemCode is passed in the request, the system retrieves all shipment configuration details (carrier, account, parcel type, service, and special services) linked to that code in the legacy system. 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. The value of shipOption is Ship Via Code. Ship Via Code is configured as part of the automation rule. - byRateGroup: ruleType and rateGroupId - byShipViaCode: code - byExternalSystemCode: externalSystemCode, carrierCode, serviceCode and parcelTypeCode - 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. Endpoint: POST /api/v2/shipments Version: 1.0.0 Security: bearerAuth ## 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) The X-PB-LocationId header identifies the enterprise, division, or partner location under which a shipment is processed and billed. If this header is not provided, the system automatically uses the enterprise-level location that was created during developer account onboarding. This default location is then used for shipment processing, carrier selection, and billing. Location Scope - Carrier accounts and services available in a request must belong to the specified location or the default enterprise location. - Attempting to use carriers or services that are not configured for the resolved location will result in a validation error. Requirement Rules - The X-PB-LocationId header is optional when the shipment origin country code matches the enterprise's default address country code. - The X-PB-LocationId header is required when the shipment origin country code differs from the enterprise's default address country code. - If the header is required but not provided, the API returns a validation error indicating that the location must be specified for the given shipment origin. - `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. ## Query parameters: - `isReturn` (boolean) Applies only to USPS, UPS, FedEx, Purolator, and CPC carriers. - For UPS: If isReturn is set, either the returnOptions object must be provided (when using individual service objects) or serviceId: PRL must be specified (when using specialService). Otherwise, the request will fail. - For FedEx, Purolator, and CPC: If isReturn is set to true, the returnOptions object is optional. - For USPS: For USPS returns, the account is not charged when the return label is created. Charges for the return shipment are applied only after the Scan-Based Return is inducted. - `includeDeliveryCommitment` (string) When set to true (default), the response includes delivery commitment information. Set to false to exclude delivery commitment details from the response. ## Response 400 fields (application/json): - `errorCode` (string) Error code(s) that appear due to HTTP 400- Invalid or Bad Request, e.g., validation-error. Example: "validation_error" - `errorDescription` (string) The HTTP 400 Bad Request response status code indicates that the server cannot process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). Example: "string" - `additionalCode` (string) A unique identifier for the error, for example 1101055, 0100008, or 1021126. - `additionalInfo` (string) This is an additional information about the error. This error 'Invalid Request' might appear due to invalid dimension, weight, or serviceID, or if the information is missing. - `additionalParameters` (array) ## Response 401 fields (application/json): - `message` (string, required) This is HTTP 401 Unauthorized response status code, which indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource. ## Response 500 fields (application/json): - `message` (string, required) This is HTTP 500 Internal Server Error response status code, which indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.