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