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