# Overview The Shipping APIs provide a unified, multi-carrier platform to rate shipments, generate labels, manage pickups, and track parcel movement from creation through delivery. These APIs support a wide range of carriers and services, enabling developers to integrate shipping functionalities into their applications with ease. The Shipping APIs are designed to handle single-parcel, multi-parcel, and high-volume workflows. They also include features for managing carrier accounts, configuring defaults, and handling post-shipment operations like reprints, cancellations, and tracking updates. With comprehensive documentation, sample code, and a sandbox environment for testing. If you are integrating for the first time, follow this path: 1. Authenticate before calling Shipping APIs - Start with the [Auth API](/openapi/auth/other/getaccesstoken) to generate an OAuth access token. - Send the token in the Authorization header for every request: `Authorization: Bearer `. 2. Start with account and carrier setup - Use Get Carrier Accounts to identify available carrierAccountId values. - Use Get Carriers, Get Services, Get Parcel Types, and Get Special Services to discover what is valid for your scenario. 3. Validate shipment inputs before creating labels - Confirm address quality with the Address APIs. - For international shipments, prepare customs data and upload Electronic Trade Documents when required. 4. Rate first, then ship - Use Rate Shipment to compare options by carrier, rate group, rule set, Ship Via Code, or external system code. - Use Create Shipment to generate the label once the preferred option is selected. 5. Manage post-shipment operations - Reprint or cancel labels when needed. - Retrieve shipment details and tracking updates. - Schedule pickups, check pickup availability, and generate pickup documents. 6. Use Batch Shipments for high-volume processing - Use Batch Shipment APIs when creating large shipment volumes. - Choose synchronous bulk creation or asynchronous CSV import, then process and monitor using batchId. - Use batch status, shipment-level details, and batch void operations to manage exceptions at scale. 7. Optimize for production scale - Use Defaults to reduce repeated request fields. - Use Multipiece Shipment for multi-parcel workflows. - Use metadata, references, manifests, and reports for operational control and reconciliation. Version: 1.0.0 ## Servers ``` https://api-dev.sendpro360.pitneycloud.com/shipping ``` ``` https://api-qa.sendpro360.pitneycloud.com/shipping ``` Sandbox Server ``` https://api-sandbox.sendpro360.pitneybowes.com/shipping ``` Production Server (uses live data) ``` https://api.sendpro360.pitneybowes.com/shipping ``` Sandbox Server for Canada ``` https://api-ppd.shipping360.pitneybowes.com/ca/shipping ``` Production Server for Canada ``` https://api.shipping360.pitneybowes.com/ca/shipping ``` Admin Sandbox Server for global region ``` https://admin-ppd.spo.pitneybowes.com/shipping ``` Admin Production Server for global region ``` https://admin-global.shipping360.pitneybowes.com/shipping ``` Client Sandbox Server for global region ``` https://app-global-ppd.spo.pitneybowes.com/shipping ``` Client Production Server for global region ``` https://app-global.shipping360.pitneybowes.com/shipping ``` ## Security ### basicAuth Type: http Scheme: basic ### bearerAuth Type: http Scheme: bearer ## Download OpenAPI description [Overview](https://docs.sendpro360.pitneycloud.com/_bundle/openapi/shipping.yaml) ## Shipment The Shipment APIs provide a unified interface to create, manage, and track shipments across multiple carriers. These APIs support the complete shipment lifecycle, including carrier configuration, rate retrieval, shipment creation, label generation, and post-shipment operations. ### Get Carriers - [GET /api/v1/carriers](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/getcarriers.md): The operation fetches all supported carriers. This service is used to get list of supported carriers and their properties. ### Carrier facilities - [POST /api/v1/carrier-facility](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/carrierfacility.md): This operation locates Post Offices and other facilities for a given carrier. You can use this operation, for example, to locate all USPS Post Offices near a given postal code. ### Get Countries - [GET /api/v1/countries](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/getcountries.md): The operation fetches list of supported destination countries for a provided carrier and origin country. If query parameters are not provided, it will default to USPS as carrier and US as origin country. ### Get Services - [GET /api/v1/services](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/getservices.md): The operation fetches a list of supported services for a carrier with respect to specific origin and destination country. If query parameters are not provided, this will default to USPS as carrier, US as both origin and destination country code. ### Get Parcel Types - [GET /api/v1/parcelTypes](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/getparceltypes.md): The operation fetches Parcel Types based on the provided carrier, origin county, and the destination country. If query parameters are not provided, this will default to USPS as carrier, US as both origin and destination country code. ### Get Special Services - [GET /api/v1/specialServices](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/getspecialservices.md): The operation fetches Special Services for a given carrier, service, origin country, and the destination country. If query parameters are not provided, it will default to USPS as carrier, US as both origin, and destination country and will show for all service and parcel types ### Get Carrier Accounts - [GET /api/v1/carrierAccounts](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/getcarrieraccount.md): The operation retrieves onboarded Carriers with their Carrier Account IDs which uniquely identify multiple accounts of same carrier. ### Get All Shipments - [GET /api/v1/shipments](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/getallshipments.md): The operation fetches all created Shipments. If query parameters are not provided, it will default endDate as current date, page as 1 and size as 10. ### Create Shipment - [POST /api/v2/shipments](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/createshipmentv2.md): > 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. ### Rate Shipment - [POST /api/v2/rates](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/rateshipment.md): This operation generates rate Shop for a specified shipment without generating the labels. ### Create ERR Single Coversheet - [POST /api/v1/err/coverSheet](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/createerrcoversheet.md): This API generates Electronic Return Receipt (ERR) artifacts for a parcel, including a coversheet, ERR barcode, and ERR stamp. The response output can be configured using the type parameter to return a coversheet, barcode and stamp images, or all outputs. ### Get Shipment by Id - [GET /api/v1/shipments/{shipmentId}](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/shipmentbyid.md): The operation retrieves shipment details using shipmentId. ### Reprint Shipment - [POST /api/v2/shipments/reprint](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/reprintshipmentbyidv2.md): This operation retrieves an existing shipping label associated with a shipment. The API uses the shipmentId returned by the original Create Shipment request. Use this API only if the original shipping label has been lost or damaged. Key Considerations: - This operation is applicable only if the original shipment was successfully created. It cannot be used if the initial Create Shipment request resulted in no response or encountered an error. - USPS allows only 1 reprint. - GoFor does not allow reprint. - RMG allows 3 reprints. - All other carriers allow up to 8 reprints. - Reprints are valid for 24 hours from the time the label was first created. - Reprinting should only be used when necessary. Excessive reprint attempts are restricted and monitored. - Follow the Troubleshooting section in case you are facing any issues creating a shipment. ### Cancel Shipment - [POST /api/v2/shipments/cancel](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/cancelshipmentbyidv2.md): This operation cancels or voids a shipment label that has not been processed by the carrier. When you cancel an unused prepaid shipment label, the API initiates a request for an electronic refund. Key Considerations - Cancelation must occur before the shipment is picked up or processed by the carrier. - Refunds are only applicable for unused labels. Voiding a used label may result in penalties or billing. - USPS: - Cancel unused USPS prepaid labels within 30 days of printing to start the refund process. - Refund requests are processed within 14 business days from the date the refund was requested, provided the label has not been used. - Approved refunds are automatically credited to the account you used to pay for the label. - Note: USPS considers it a federal offense to induct a label that has already been refunded. - Note: Refunds are not available for First-Class Mail letters and flats. - Note: Refunds are subject to the policies of the applicable carrier. - For unused post-paid labels, you must void them. Voiding avoids billing for the label and allows the carrier to maintain an accurate count for pickups. - Always destroy voided labels to prevent accidental use. If a voided label is shipped, you will be billed for the label. - Once a refund has been claimed, you cannot use the shipping label for sending packages. It will be rejected. Shipment Cancelation Rules - Provide either shipmentId or parcelTrackingNumber to cancel a shipment. - If both are provided, shipmentId takes precedence and parcelTrackingNumber is ignored. - If only parcelTrackingNumber is provided, the shipment associated with that parcel tracking number is canceled. ### Signature Image ERR - [GET /api/v1/err/shipments/{shipmentId}/signaturefile](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/getsignatureimageerr.md): This API provides a downloadable link containing the signature image for a specific ERR (Electronic Return Receipt) shipment. This signature image serves as Proof of Delivery (POD). What is Proof of Delivery (POD)? Proof of Delivery is a document or file that acts as evidence of successful shipment delivery. This file contains a digital copy of the recipient's signature, provided as a downloadable link or URL. Key Considerations: - It provides the recipient's signature image captured at the time of delivery as proof that the shipment was successfully delivered. - The API provides the recipient's signature image as Proof of Delivery (POD) to confirm successful shipment delivery. - A request requires the mandatory shipmentId. - If a signature is captured by the carrier, the API returns it as a downloadable link of the PDF in the signatureFileURL field. - The signatureFileURL provided in the API response expires after 60 minutes. - If no signature is available, the API returns an error. - Signature Image ERR is supported for USPS carrier only. ### Cancel Stamps ERR - [POST /api/v1/err/stamps/void](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/cancelstampserr.md): This operation cancels (voids) stamps generated for ERR (Electronic Return Receipt). - User needs to provide *Shipment IDs in the stampIds array to cancel those specific ERR stamps. - User can download the Refund Form having details of generated Postage. - At once, maximum 1000 stamps can be requested for cancelation. ### Download BPOD Files - [POST /api/v1/err/shipments/bpod](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/downloadbpodfiles.md): This API operation is used to download bulk of ERR (Electronic Return Receipt) - POD (Proof of Delivery) files, which are specific to USPS carrier. User can download BPOD (Bulk Proof of Delivery) files either using Shipment IDs or Date Range. - To get the records based on dates and download BPOD files accordingly, Start Date and End Date need to be passed in the request body as a query filter. Note: To get a downloadable link of BPOD files on the basis of date range provided, an empty JSON body {} must be passed in the request body. - When both the date range and Shipment IDs are provided in the request, Shipment IDs will take precedance. - User is restricted to download 1000 BPOD files as max limit. ### Update Carriers - [PUT /api/v1/carriers/{carrier}](https://docs.sendpro360.pitneycloud.com/openapi/shipping/shipment/setsubscriptioncapabilities.md): This API operation sets the allowed capabilities—services, packages, and special services - for a subscription and carrier. By default, all carrier-provided capabilities are available. After this call, only the specified capabilities are permitted for Rate Shop and Create Shipment operations. Requests that use capabilities not in this allowlist are rejected with an error. The Get Services, Get Parcel Types , and Get Special Services APIs will also return only the capabilities defined in this allowlist. ## Electronic Trade Document The Electronic Trade Document API facilitates uploading electronic trade documents for international shipments.
These APIs support faster customs processing by enabling required trade information to be captured and shared electronically at earlier stages of the shipment. ### Upload Electronic Trade Document - [POST /api/v1/importUrl](https://docs.sendpro360.pitneycloud.com/openapi/shipping/electronic-trade-document/uploadetd.md): Electronic Trade Documents Upload API is an international shipping document upload solution that simplifies global shipping needs and allows you to electronically upload customs documentation required for international shipments. You can submit most of your trade documents electronically relieving yourself from printing or attaching trade documents with the shipment. This API simplifies and accelerates customs clearance by replacing physical paperwork with electronic documentation. The customs and other agencies receive electronically sent documents faster than paper copies attached with your shipment. The customs clearance process is also optimized as capturing and sharing of critical trade information is done at earlier stages of shipping. > Note: - FedEx supports ETD with the special service ELECTRONIC_TRADE_DOCUMENTS. - DHL Express supports ETD with the special service PAPERLESS. - In certain scenarios, the originals of specific international documents still need to be attached to the package. - For smooth customs clearance and to avoid delays, ensure that the documents are visually clear and not distorted in any way. How the Workflow Operates Step 1: Submit Electronic Trade Document Metadata Initiate the process by making a POST request to the ETD Upload API with the document metadata (e.g., file name, document type, and content type). In response, the system returns: - A pre-signed S3 upload URL (url) - A fileName - A relative s3FileId used to reference the uploaded document later Step 2: Upload the Document File After receiving the response, you must perform a separate HTTP PUT request to the provided url. - This request must upload the binary content of the file (e.g., PDF or image) - Upload the same file whose metadata was submitted in step-1 Step 3: Reference the Document in Shipment Creation Once the ETD uploaded successfully, the document is stored in the S3 bucket. - Once uploaded, the document is stored in the S3 bucket and can later be referenced via the s3FileId in Create International Shipment API under customsDocuments object. ## Pickups APIs to create and manage pickup requests, check availability, cancel scheduled pickups, and generate or retrieve pickup documents. ### Schedule Pickup - [POST /api/v1/pickups](https://docs.sendpro360.pitneycloud.com/openapi/shipping/pickups/schedulepickup.md): Pickups endpoint allows you to schedule pickups with USPS, DHL Express, UPS and FedEx carriers for eligible shipments. The pickup schedule scope is determined by what you provide in the request: - If pickupSummary is provided: a pickup is scheduled for the packages described in the summary. - If shipmentIds are provided: a pickup is scheduled for the specified shipments. - If both pickupSummary and shipmentIds are provided: a pickup is scheduled for all shipments including by both inputs. - If neither is provided: a pickup is scheduled for all shipments created on the given carrier account by that time of the day. - carrierAccountId handling: carrierAccountId is required to schedule a pickup. Either provide carrierAccountId in the request payload, or provide X-PB-LocationId with a location that has only one carrier account configured for the selected carrier. > Note: The sender's first name and last name are required for USPS. For example: "name": "John Doe" ### Get Pickups - [GET /api/v1/pickups](https://docs.sendpro360.pitneycloud.com/openapi/shipping/pickups/getpickups.md): Get Pickups ### Cancel Pickups - [PUT /api/v1/pickups/cancel](https://docs.sendpro360.pitneycloud.com/openapi/shipping/pickups/cancelpickups.md): Cancel Pickups. ### Get Pickup Document - [GET /api/v1/pickups/{pickupId}/document](https://docs.sendpro360.pitneycloud.com/openapi/shipping/pickups/getpickupdocument.md): The API retrieves the document for a scheduled pickup receipt using the pickupId, generated when the pickup is successfully scheduled. ### Cancelled Pickup Document - [POST /api/v1/pickups/document](https://docs.sendpro360.pitneycloud.com/openapi/shipping/pickups/cancelledpickupdocument.md): This operation generates a PDF receipt for pickup cancellations. It supports creating receipts for multiple cancelled pickups. ### Check Pickup Availability - [POST /api/v1/pickups/availability](https://docs.sendpro360.pitneycloud.com/openapi/shipping/pickups/checkpickupavailability.md): Validates if the requested carrier can perform a pickup at the provided address, given the shipment details and requested pickup date/time. The response also indicates: - If pickup is available at the location. - What types of pickup (residential, on-demand, scheduled) are supported. - Cutoff times and valid pickup time windows. ## Multipiece Shipment APIs to rate and create shipments with multiple parcels under a single shipment, and to manage them through reprint and cancellation operations. ### Multipiece Shipment - [POST /api/v1/multipiece/shipments](https://docs.sendpro360.pitneycloud.com/openapi/shipping/multipiece-shipment/multipieceshipment.md): The operation creates Multipiece Shipments. Shipments with multiple parcels sent to the same destination can be grouped together in a multipiece shipment. - UPS, FedEx, DHL Express, Suprmsys, Purolator, Apple Express, Tforce Mile, Loomis and Canpar are supported for Multipiece Shipments. - Maximum Parcels Allowed per Carrier: - DHL: 75 - FedEx: 40 - UPS: 50 - Purolator: 100 - Apple Express: 75 - Tforce Mile: 75 - Loomis: 75 - Canpar: 25 - For UPS- multipiece shipment with Envelopes (having parcel Type as LTR) is not supported. - For FedEx Multipiece, all parcels must be of same packaging type while creating multipiece shipment - USPS does not support multi-piece parcels in a single shipment at this time. ### Multipiece Rates - [POST /api/v1/multipiece/rates](https://docs.sendpro360.pitneycloud.com/openapi/shipping/multipiece-shipment/multipiecerates.md): The operation is used for rateshop and to get specific rate based on serviceId for Multipiece. ### Reprint Multipiece Shipment - [GET /api/v1/multipiece/shipments/{shipmentId}/reprint](https://docs.sendpro360.pitneycloud.com/openapi/shipping/multipiece-shipment/multipieceshipmentreprint.md): The operation is used to reprint the multipiece label. It takes the shipmentId of the multipiece shipment done. All supported carriers (UPS, FedEx, DHL Express, Suprmsys, Purolator, and Apple Express) allow up to 8 reprint. ### Cancel Multipiece Shipment - [PUT /api/v1/multipiece/shipments/{shipmentId}/cancel](https://docs.sendpro360.pitneycloud.com/openapi/shipping/multipiece-shipment/multipieceshipmentcancel.md): The operation is used to cancel the multipiece label. It takes the shipmentId of the multipiece shipment done. ## Print APIs to print shipping labels and documents, configure and manage printer mappings, and retrieve print job status. ### Print Document - [POST /api/v1/document/print](https://docs.sendpro360.pitneycloud.com/openapi/shipping/print/printdocument.md): It contains information about a label or a document, e.g., a shipping label, a customs form, manifest report etc., that pertains to a shipment or manifest. ### Printer mapping - [POST /api/v1/printer/mapping](https://docs.sendpro360.pitneycloud.com/openapi/shipping/print/printermapping.md): printer mapping document ### Get Printer mapping - [GET /api/v1/printer/mapping](https://docs.sendpro360.pitneycloud.com/openapi/shipping/print/getprintermapping.md): Get printer mapping document ### Delete Printer mapping - [DELETE /api/v1/printer/mapping](https://docs.sendpro360.pitneycloud.com/openapi/shipping/print/deleteprintermapping.md): delete printer mapping document ### Job status - [GET /api/v1/jobs/{jobId}](https://docs.sendpro360.pitneycloud.com/openapi/shipping/print/jobstatus.md): job status ## Defaults APIs to create, retrieve, update, and delete default shipment settings for frequently used fields such as carrier, service, sender address, label preferences, and parcel details. ### Create Defaults - [POST /api/v1/defaults](https://docs.sendpro360.pitneycloud.com/openapi/shipping/defaults/createdefaults.md): While creating shipment, a few columns/ fields information are used mandatorily, and if the value for those columns are used repetitively, then it is always better to save last used values. And hence, this API has been introduced. Using this API, default values can be set up for frequently used columns/fields information like carrier and linked services. Setting up the defaults will save both time and efforts. ### Get All Defaults - [GET /api/v1/defaults](https://docs.sendpro360.pitneycloud.com/openapi/shipping/defaults/getalldefaults.md): The operation fetches all created Defaults. If query parameters are not provided, it will consider default page as 1 and default size as 10. ### Update Defaults - [PUT /api/v1/defaults/{defaultID}](https://docs.sendpro360.pitneycloud.com/openapi/shipping/defaults/putdefaultsbyid.md): This operation updates the values set for Defaults. ### Get Defaults By ID - [GET /api/v1/defaults/{defaultID}](https://docs.sendpro360.pitneycloud.com/openapi/shipping/defaults/getdefaultsbyid.md): This operation fetches the values set for the Defaults. ### Delete Defaults by ID - [DELETE /api/v1/defaults/{defaultID}](https://docs.sendpro360.pitneycloud.com/openapi/shipping/defaults/deletedefaultsbyid.md): This operation deletes the existing Defaults.