Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning. Version 2.1.0

• POST /api/scan_form/create_scan_form: New endpoint to create a USPS SCAN Form (PS Form 5630) for a set of already-purchased USPS shipments, returning the SCAN Form PDF URL in scan_form_image.

• POST /api/shipment/submit_pod: New endpoint to submit a Proof of Delivery request for a USPS shipment and email the POD letter to 1–3 recipients. Returns a transaction_message such as Your Proof of Delivery record is complete and will be processed shortly.
• GET /api/shipment/direct/tracking_by_tracking_no: Added a new field recipient_name to the response, the name of the person who signed for delivery (e.g. Alice).

• Shipment request options.signature: Added two enum values — usps_signature_restricted (Signature Confirmation Restricted Delivery) and usps_adult_signature_restricted (Adult Signature Restricted Delivery, 21+). Existing values signature and adult_signature are unchanged.

• GET /api/shipment/direct/tracking_by_tracking_no: Added a new field status_summary to the response, a human-readable summary of the tracking status (e.g. Your item has been delivered and is available at a PO Box at 9:34 am on June 22, 2026 in GRANITEVILLE, SC 29829.). The field is nullable and may return null when no summary is available.
• POST /api/shipment/create_and_pay: Added two fields to the response — label_data, the base64-encoded PNG content of each label corresponding one-to-one with label_urls (e.g. iVBORw0KGgoAAAANSUhEUgAA...AElFTkSuQmCC), and label_qr_code_data, the base64-encoded PNG content of each QR-code label corresponding one-to-one with qrcode_urls. label_qr_code_data is only populated for USPS QR-code labels.
• POST /api/shipment/direct_buy: Added the same two fields label_data and label_qr_code_data to the response.

• Added Spanish documentation support, allowing users to view the ShipSaving API documentation in Spanish.

• POST /api/shipment/tracking_by_platform_uk_id: Added three new local-time fields to the response: scanned_time_local, first_scan_date_local, and event_time_local. Each field provides the corresponding timestamp in the event location's local time with timezone offset in ISO 8601 format (e.g. 2026-03-16T15:49:17-05:00). All three fields are nullable and may return null when the local timezone cannot be determined.

• Added field-level descriptions (length limits, format patterns, and required-field rules) for pickup_location and a 255-character maximum length for package_location_ext in POST /api/shipment/pickup/add.
• Added 400 response examples for POST /api/shipment/pickup/add and POST /api/shipment/pickup/cancel.
• Added a Pickup Error Codes section to the Appendix, listing all error codes returned by POST /api/shipment/pickup/add and POST /api/shipment/pickup/cancel.

• Added a downloadable Postman collection (ZIP) to the Integration Guide, including the API collection and environment files (Sandbox & Production) for quick testing.

• Added new documentation page Errors & Rate Limits, covering error response format, HTTP status codes, error code naming convention, rate limiting, and handling recommendations.
• Added Error Code Reference tables to the Appendix.

• Added return_to_sender field to the response of the following endpoint:

  • GET /api/shipment/tracking_by_platform_uk_id

  This boolean field indicates whether the shipment has been returned to the sender.

• Added support for USPS Returns service levels to the following endpoint:

  • POST /api/shipment/direct_buy

  The supported USPS Returns service levels include:

  • USPS_GROUND_ADVANTAGE_RETURN
  • USPS_PRIORITY_MAIL_RETURN
  • USPS_PRIORITY_MAIL_EXPRESS_RETURN

  The service level enum definitions can be found in the Appendix.

• Added return_address_data object to the request body of the following endpoints:

  • POST /api/shipment/direct_buy
  • POST /api/shipment/get_rates

  This field is USPS-only and specifies the address where the package should be returned if it is deemed undeliverable or returned to sender.

• Added a version-specific Appendix for the New API (v2), documenting enum definitions and reference tables scoped to v2.
• Deprecated the top-level Appendix page and preserved it as a backward-compatible entry point directing users to the New API (v2) Appendix.

• Added support for bilingual documentation (English / Chinese), allowing users to switch languages when viewing the ShipSaving API documentation.

• Added a new tracking endpoint GET /api/shipment/direct/tracking_by_tracking_no, which returns tracking event timestamps in ISO 8601 format with UTC offsets included, enabling accurate interpretation of local event times across different time zones.

• Corrected a typo: field additional_handing renamed to additional_handling in API. Affected endpoints:
  • POST /api/shipment/batch/quick_rate
  • POST /api/shipment/direct_buy
  • POST /api/shipment/get_rates

• Added UPS Canada predefined package codes in carrier_package_code enum.
• Added require_saturday_delivery boolean parameter to indicate a preference for Saturday delivery if supported by the carrier and service level. Setting this flag to true may result in additional carrier surcharges or higher shipping rates. Affected endpoints:
  • POST /api/shipment/batch/quick_rate
  • POST /api/shipment/direct_buy
  • POST /api/shipment/get_rates

• Added support for retrieving UPS Canada shipping rates and purchasing UPS Canada shipment labels in the following endpoints:
  • POST /api/shipment/batch/quick_rate
  • POST /api/shipment/get_rates
  • POST /api/shipment/direct_buy

• Updated carrier list — added support for the new carrier SwiftX Express and its service level.
• Updated /api/shipment/batch/quick_rate and /api/shipment/get_rates — clients can now retrieve rates for SwiftX Express by specifying provider_id="SWIFTX" and service_levels="SWIFTX_EXP" in shipment_rate_carrier_data.
• Updated /api/shipment/direct_buy — purchasing labels using SwiftX Express is now supported. To use this service, set carrier_code="SWIFTX" and service_level="SWIFTX_EXP" when submitting the request.

• Updated /api/shipment/batch/quick_rate — added support for the optional shipment_rate_carrier_data parameter, allowing clients to request rates for specified carriers and service levels instead of the default USPS Ground Advantage.
• Updated /api/shipment/direct_buy — added the carrier_code and service_level fields. These two fields now work together to determine which carrier service level will be used for label purchase.

• Enhanced /api/shipment/tracking_by_tracking_no — added estimate_delivery_date, original_tracking_location, and destination_tracking_location to provide clearer delivery estimates and more complete carrier-reported origin/destination details.

• USPS Carrier Pickup API suite, enabling merchants to schedule, cancel, and query USPS pickup requests:
  • POST /api/shipment/pickup/add — Create a USPS pickup request.
  • POST /api/shipment/pickup/cancel — Cancel an existing pickup request.
  • GET /api/shipment/pickup/list — Retrieve a paginated list of pickup records.
  • GET /api/shipment/pickup/package/location/list — Retrieve available USPS package location values.

• Expanded /api/shipment/tracking_by_tracking_no — added support for Amazon Shipping tracking, including status lookup and event history.

• Added /api/shipment/tracking_by_tracking_no — provides USPS and UPS tracking lookup by tracking_no, returning the current tracking status, latest scan info and full tracking event history.

• Updated /api/shipment/direct_buy and /api/shipment/create_and_pay now return both the standard label and the QR-code label when purchasing USPS services with "label_print_type": "qrcode".

• Introduced the is_return_label parameter to /api/shipment/direct_buy and /api/shipment/get_rates endpoints, allowing clients to specify whether the label is for a return shipment. Default value is false.

• Added new field tracking_events (array) to the responses of /api/shipment/tracking and /api/shipment/tracking_by_platform_uk_id.
  This field represents the full shipment tracking timeline (all tracking events).

• Added detailed documentation for data.status field in /api/shipment/tracking and /api/shipment/tracking_by_platform_uk_id response.
  Introduced enumerated status values with descriptions:
  • created, available_for_pickup, in_transit, out_for_delivery, delivered, return_to_sender, voided, error, seized_by_law_enforcement, unknown.

• Added /api/shipment/batch/quick_rate endpoint to support batch shipment rate queries (up to 10 requests per call).
• Added a duplicate-checking mechanism to /api/shipment/direct_buy and /api/shipment/create_and_pay.

• Added new response field scanned_time to the tracking API.
• New endpoint /api/address/validate to validate U.S. addresses, return standardized components, and provide error/correction details.

• New endpoint /api/shipment/tracking_by_platform_uk_id to query shipment tracking status by platform_uk_id.

• /api/shipment/void_label now supports platform_uk_id for voiding a label.

• Initial release of the ShipSaving New API, supporting shipment rating, label purchase, label voiding, and shipment tracking.