# ShipSaving New API Version: v2 License: Apache 2.0 ## Servers Production server ``` https://x-api.shipsaving.com ``` ## Security ### BearerAuth Bearer token authentication (JWT). Type: http Scheme: bearer Bearer Format: JWT ### basicAuth Basic auth using AppKey/AppSecret. Type: http Scheme: basic ## Download OpenAPI description [ShipSaving New API](https://docs.shipsaving.com/_bundle/v2/openapi.yaml) ## Authentication ### Get Access Token - [POST /oauth2/token](https://docs.shipsaving.com/v2/openapi/authentication/getaccesstoken.md): Issue a short-lived access token using the OAuth 2.1 Client Credentials grant. Provide: - Authorization: Basic base64(AppKey:AppSecret) - Content-Type: application/x-www-form-urlencoded ## Shipment ### Batch Quick Rate - [POST /api/shipment/batch/quick_rate](https://docs.shipsaving.com/v2/openapi/shipment/batchquickrate.md): This endpoint allows you to quickly retrieve shipment rate quotes by providing the from_address_data, to_address_data, package_data and the ship_date. Each API call can include up to 10 individual rate requests. Previously, this endpoint only returned rates for USPS Ground Advantage. With the new update, you may optionally specify additional carriers and service levels using the shipment_rate_carrier_data field. A detailed explanation of how to use this parameter can be found in the request schema. - If shipment_rate_carrier_data is omitted: The system will return rates only for USPS Ground Advantage (default behavior). - If shipment_rate_carrier_data is provided: The system will return rates only for the specified provider(s) and service level(s). Multiple combinations may be sent in a single request. ### Get Rates - [POST /api/shipment/get_rates](https://docs.shipsaving.com/v2/openapi/shipment/getrates.md): Retrieves shipping rates from all active carriers and service levels under your account, optionally filtered by specified carriers and service levels, and returns results sorted by fastest, cheapest, and other criteria along with any applicable error information. ### Buy Label - [POST /api/shipment/create_and_pay](https://docs.shipsaving.com/v2/openapi/shipment/createandpay.md): Creates and pays for a shipment label using the rate_id obtained from a prior get_rates call. This endpoint also allows purchasing shipment insurance in the same request (insurance cannot be purchased separately). To prevent duplicate purchases caused by network fluctuations or retries, the API checks ether a shipment already exists under the specified platform_uk_id. - If a related shipment is found, the existing shipment information will be returned, and the duplicate_label field in the response will be set to true. - If no shipment exists, a new shipment will be created as normal, and the duplicate_label field will be false. ### Directly Buy Label - [POST /api/shipment/direct_buy](https://docs.shipsaving.com/v2/openapi/shipment/directbuy.md): Creates and purchases a shipment label in a single step without calling get_rates separately. This endpoint currently supports USPS Returns service levels. See the Appendix for the full list of supported values. To prevent duplicate purchases caused by network fluctuations or retries, the API checks ether a shipment already exists under the specified platform_uk_id. - If a related shipment is found, the existing shipment information will be returned, and the duplicate_label field in the response will be set to true. - If no shipment exists, a new shipment will be created as normal, and the duplicate_label field will be false. ### Void Label - [POST /api/shipment/void_label](https://docs.shipsaving.com/v2/openapi/shipment/voidlabel.md): This endpoint allows voiding label by providing either shipment_no or platform_uk_id. Only one parameter is required to uniquely identify a shipment. ### Query Insurance Rate - [GET /api/shipment/insurance/rate](https://docs.shipsaving.com/v2/openapi/shipment/paths/~1api~1shipment~1insurance~1rate/get.md) ## Tracking ### Query Shipment Tracking Status by platform_uk_id - [GET /api/shipment/tracking_by_platform_uk_id](https://docs.shipsaving.com/v2/openapi/tracking/getshipmenttrackingbyplatformukid.md): Indicates the current location or state of a package within the supply chain (e.g., in_transit, out for delivery). Use the tracking status object to monitor shipment progress. In test mode, this API will return fixed mock data to facilitate testing and integration validation. ### Query tracking status by tracking no - [GET /api/shipment/tracking_by_tracking_no](https://docs.shipsaving.com/v2/openapi/tracking/getshipmenttrackingbytrackingno.md): Retrieves the shipment’s tracking status, event history, estimated delivery date, and associated origin/destination location details as reported by the carrier. ### Query tracking status by tracking no (with UTC offset) - [GET /api/shipment/direct/tracking_by_tracking_no](https://docs.shipsaving.com/v2/openapi/tracking/getshipmenttrackingwithutcoffset.md): Retrieves the current shipment tracking event, first scan tracking event, and the complete tracking event history as reported by the carrier. Compared to /api/shipment/tracking_by_tracking_no, this endpoint returns all tracking event timestamps in ISO 8601 format with the UTC offset included, allowing clients to accurately interpret local event times across different time zones. ## Pickup ### Schedule pickup - [POST /api/shipment/pickup/add](https://docs.shipsaving.com/v2/openapi/pickup/addpickupbyshipment.md): Create a USPS Carrier Pickup request using existing shipment information. This endpoint schedules a postal carrier to pick up eligible packages on the next USPS delivery day. ### Cancel pickup - [POST /api/shipment/pickup/cancel](https://docs.shipsaving.com/v2/openapi/pickup/cancelpickup.md): Cancel a previously scheduled carrier pick up. A carrier pickup can no longer be updated or cancelled once cancelled. It requires no additional parameters other than the pickup_no. The status will change to CANCELED on success. ### Retrieve pickup records - [GET /api/shipment/pickup/list](https://docs.shipsaving.com/v2/openapi/pickup/getpickuplist.md): Fetches a paginated list of pickup records created in the system. This endpoint supports optional filters such as USPS confirmation number, pickup status, and carrier code. Pagination parameters (page and page_size) allow controlling the size of the returned dataset, and the order_by flag determines the sorting order of the results. ### Get package location - [GET /api/shipment/pickup/package/location/list](https://docs.shipsaving.com/v2/openapi/pickup/getpackagelocation.md): Returns the list of valid package location enum values. These values indicate where the packages will be placed at the pickup address for the USPS carrier to retrieve during the scheduled pickup. ## Address Validation ### Address Validation - [POST /api/address/validate](https://docs.shipsaving.com/v2/openapi/address-validation/validateaddress.md): The Address Validation API checks the validity of U.S. domestic addresses and returns standardized address components in accordance with USPS® addressing standards. This helps improve delivery accuracy, reduce undeliverable mail, and support consistent pricing for shipping and logistics.