# Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Version 2.1.0 ## [1.3.6] - 2026-08-25 ### Added - `POST /api/shipment/direct_buy`: Added a new request field `option_data.is_lithium_battery`. When set to `true`, the shipment is automatically declared as containing hazardous materials: `option_data.hazardous_materials` is forced to `true` and the USPS unmarked lithium battery (Class 9) hazmat classification is applied, so only USPS Ground Advantage rates are returned. Defaults to `false`. ## [1.3.5] - 2026-07-28 ### Added - `POST /api/shipment/get_rates`: Added a new field `price_details` to each rate, a FedEx specific array breaking the rate down by charge component (e.g. `{"code":"BASE_CHARGE","description":"Shipping Label Charge","price":99.31}`). The field is nullable and may return `null` for non-FedEx rates. ## [1.3.4] - 2026-07-21 ### Added - `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`. ## [1.3.3] - 2026-07-14 ### Added - `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`). ## [1.3.2] - 2026-07-02 ### Changed - 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. ## [1.3.1] - 2026-06-23 ### Added - `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. ## [1.3.0] - 2026-05-19 ### Added - Added Spanish documentation support, allowing users to view the ShipSaving API documentation in Spanish. ## [1.2.9] - 2026-05-14 ### Added - `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. ## [1.2.8] - 2026-05-13 ### Updated - 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`. ## [1.2.7] - 2026-04-09 ### Added - Added a downloadable Postman collection (ZIP) to the Integration Guide, including the API collection and environment files (Sandbox & Production) for quick testing. ## [1.2.6] - 2026-04-02 ### Added - 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. ## [1.2.5] - 2026-02-03 ### Added - 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. ## [1.2.4] - 2026-01-23 ### Added - 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. ## [1.2.3] - 2026-01-13 ### Changed - 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. ## [1.2.2] - 2026-01-03 ### Added - Added support for bilingual documentation (English / Chinese), allowing users to switch languages when viewing the ShipSaving API documentation. ## [1.2.1] - 2025-12-24 ### Added - 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. ## [1.2.0] - 2025-12-16 ### Fixed - 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 - 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` ### Updated - 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` ## [1.1.3] - 2025-12-10 ### Update - 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. ## [1.1.2] - 2025-12-04 ### Update - 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. ## [1.1.1] - 2025-11-24 ### Update - 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. ## [1.1.0] - 2025-11-21 ### Added - 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. ## [1.0.8] - 2025-11-19 ### Update - Expanded `/api/shipment/tracking_by_tracking_no` — added support for Amazon Shipping tracking, including status lookup and event history. ## [1.0.7] - 2025-11-11 ### Added - 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. ### Changed - 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"`. ## [1.0.6] - 2025-10-30 ### Added - 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. ## [1.0.5] - 2025-09-23 ### Added - 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). ## [1.0.4] - 2025-09-23 ### Added - 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`. ## [1.0.3] - 2025-08-29 ### Added - 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`. ## [1.0.2] - 2025-08-27 ### Added - 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. ## [1.0.1] - 2025-08-25 ### Added - New endpoint `/api/shipment/tracking_by_platform_uk_id` to query shipment tracking status by `platform_uk_id`. ### Changed - `/api/shipment/void_label` now supports `platform_uk_id` for voiding a label. ## [1.0.0] - 2025-08-13 ### Added - Initial release of the ShipSaving New API, supporting shipment rating, label purchase, label voiding, and shipment tracking.