Skip to content
/Shipment

ShipSaving New Open API (v1.0.5)

Overview
License

Apache 2.0

Languages
Servers
Sandbox server

https://x-api.shipsaving.us/

Production server

https://x-api.shipsaving.com/

Authentication

Operations

Shipment

Operations

Batch Quick Rate

Request

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. Currently, only the USPS Ground Advantage service level is supported.
Each API call can include up to 10 individual rate requests.

Security
BearerAuth
Bodyapplication/jsonrequired
rate_requestsArray of objects(ShipmentRate4BatchRequest)
curl -i -X POST \
  https://x-api.shipsaving.us/api/shipment/batch/quick_rate \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "rate_requests": [
      {
        "request_unique_id": "unique_uuid_001",
        "from_address_data": {
          "phone": "1234567890",
          "email": "support@shipsaving.com",
          "street": "xxxx Castleton Street",
          "street2": "STE XXX",
          "city": "Los Angeles",
          "state": "CA",
          "country": "US",
          "company_name": "company name",
          "first_name": "Alice",
          "last_name": "Green",
          "zip_code": "917XX",
          "address_type": "residential"
        },
        "to_address_data": {
          "phone": "1234567890",
          "email": "support@shipsaving.com",
          "street": "xxxx Castleton Street",
          "street2": "STE XXX",
          "city": "Los Angeles",
          "state": "CA",
          "country": "US",
          "company_name": "company name",
          "first_name": "Alice",
          "last_name": "Green",
          "zip_code": "917XX",
          "address_type": "residential"
        },
        "package_data": {
          "type": "my_package",
          "length": 10,
          "width": 10,
          "height": 10,
          "weight": 10,
          "carrier_package_code": "USPS_LETTER",
          "dimension_unit": "in",
          "weight_unit": "lb"
        },
        "option_data": {
          "signature": "signature",
          "custom_text_on_label_1": "text1",
          "custom_text_on_label_2": "text2",
          "hazardous_materials": true,
          "additional_handing": false
        },
        "ship_date": "2025-07-31T00:00:00+08:00"
      }
    ]
  }'

Responses

OK

Body*/*
codestring
Example: "ok"
msgstring
Example: "ok"
dataArray of objects(BatchQuickRateItem)

Get Rates

Request

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.

Security
BearerAuth
Bodyapplication/jsonrequired
from_address_dataobject(ShipmentAddressData)required

Address object of the sender/recipient.

from_address_data.​phonestring

Phone number of the sender/recipient. Required for international shipments. Providing a phone number is highly recommended for all shipments to ensure accurate delivery and facilitate carrier contact if needed. For the Batch Quick Rate API, this parameter is optional.

Example: "1234567890"
from_address_data.​emailstring

Email address of the sender/recipient. May be used by the carrier for delivery notifications or issue resolution. For the Batch Quick Rate API, this parameter is optional.

Example: "support@shipsaving.com"
from_address_data.​streetstringrequired

First street line.

Example: "xxxx Castleton Street"
from_address_data.​street2string

Optional secondary address line (e.g., Apt, Suite, Unit, Floor).

Example: "STE XXX"
from_address_data.​citystringrequired
Example: "Los Angeles"
from_address_data.​statestringrequired
  • For U.S. addresses, this field must be a valid two-letter state code as defined by ISO 3166-2:US (e.g., "CA" for California, "NY" for New York).
  • For non-U.S. addresses, there is no restriction on the value.
Example: "CA"
from_address_data.​countrystringrequired

2-letter code for country. This field’s value will be an ISO 3166-1 two-digit code.

Example: "US"
from_address_data.​company_namestring
Example: "company name"
from_address_data.​first_namestringrequired

For the Batch Quick Rate API, this parameter is optional.

Example: "Alice"
from_address_data.​last_namestringrequired

For the Batch Quick Rate API, this parameter is optional.

Example: "Green"
from_address_data.​zip_codestringrequired
Example: "917XX"
from_address_data.​address_typestring

Specifies if the address is residential, which can impact the quoted shipping rate. Strongly recommended to provide this parameter.

Enum"residential""commercial"
Example: "residential"
shipment_rate_carrier_dataArray of objects(ShipmentRateCarrierData)

Specifying this parameter allows you to filter rates by carrier and service level, enabling faster queries.

to_address_dataobject(ShipmentAddressData)required

Address object of the sender/recipient.

to_address_data.​phonestring

Phone number of the sender/recipient. Required for international shipments. Providing a phone number is highly recommended for all shipments to ensure accurate delivery and facilitate carrier contact if needed. For the Batch Quick Rate API, this parameter is optional.

Example: "1234567890"
to_address_data.​emailstring

Email address of the sender/recipient. May be used by the carrier for delivery notifications or issue resolution. For the Batch Quick Rate API, this parameter is optional.

Example: "support@shipsaving.com"
to_address_data.​streetstringrequired

First street line.

Example: "xxxx Castleton Street"
to_address_data.​street2string

Optional secondary address line (e.g., Apt, Suite, Unit, Floor).

Example: "STE XXX"
to_address_data.​citystringrequired
Example: "Los Angeles"
to_address_data.​statestringrequired
  • For U.S. addresses, this field must be a valid two-letter state code as defined by ISO 3166-2:US (e.g., "CA" for California, "NY" for New York).
  • For non-U.S. addresses, there is no restriction on the value.
Example: "CA"
to_address_data.​countrystringrequired

2-letter code for country. This field’s value will be an ISO 3166-1 two-digit code.

Example: "US"
to_address_data.​company_namestring
Example: "company name"
to_address_data.​first_namestringrequired

For the Batch Quick Rate API, this parameter is optional.

Example: "Alice"
to_address_data.​last_namestringrequired

For the Batch Quick Rate API, this parameter is optional.

Example: "Green"
to_address_data.​zip_codestringrequired
Example: "917XX"
to_address_data.​address_typestring

Specifies if the address is residential, which can impact the quoted shipping rate. Strongly recommended to provide this parameter.

Enum"residential""commercial"
Example: "residential"
package_dataobject(ShipmentPackageData)required
package_data.​typestring

Defines the type of package being shipped.

  • my_package: Use when specifying custom package dimensions. Requires width, length, height, dimension_unit, weight, and weight_unit.
  • predefined: Use when selecting a carrier’s predefined package type. Requires carrier_package_code and weight fields only; dimension fields are ignored.
Enum"my_package""predefined"
Example: "my_package"
package_data.​lengthnumber

Length of the package in the selected unit.

Example: 10
package_data.​widthnumber

Width of the package in the selected unit.

Example: 10
package_data.​heightnumber

Height of the package in the selected unit.

Example: 10
package_data.​weightnumber

Weight of the package in the selected unit.

Example: 10
package_data.​carrier_package_codestring

carrier package code

Enum"USPS_LETTER""USPS_LARGE_ENVELOPE_OR_FLAT""USPS_THICK_ENVELOPE""USPS_SMALL_FLAT_RATE_BOX""USPS_MEDIUM_FLAT_RATE_BOX""USPS_LARGE_FLAT_RATE_BOX""USPS_FLAT_RATE_ENVELOPE""USPS_PADDED_FLAT_RATE_ENVELOPE""USPS_LEGAL_FLAT_RATE_ENVELOPE""UPS_LETTER"
Example: "USPS_LETTER"
package_data.​dimension_unitstring

Selected dimension unit.

Enum"in""cm"
Example: "in"
package_data.​weight_unitstring

Selected weight unit.

Enum"kg""lb"
Example: "lb"
custom_dataobject(ShipmentCustomData)

custom data

option_dataobject(ShipmentOptionData)

Additional shipping options

ship_datestringrequired

Timestamp in ISO 8601 format, including local time and time zone offset.

Example: "2025-07-31T00:00:00+08:00"
curl -i -X POST \
  https://x-api.shipsaving.us/api/shipment/get_rates \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from_address_data": {
      "phone": "1234567890",
      "email": "support@shipsaving.com",
      "street": "xxxx Castleton Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "country": "US",
      "company_name": "company name",
      "first_name": "Alice",
      "last_name": "Green",
      "zip_code": "917XX",
      "address_type": "residential"
    },
    "shipment_rate_carrier_data": [
      {
        "provider_id": "USPS_B",
        "service_levels": [
          "USPS_GROUND_ADVANTAGE"
        ]
      }
    ],
    "to_address_data": {
      "phone": "1234567890",
      "email": "support@shipsaving.com",
      "street": "xxxx Castleton Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "country": "US",
      "company_name": "company name",
      "first_name": "Alice",
      "last_name": "Green",
      "zip_code": "917XX",
      "address_type": "residential"
    },
    "package_data": {
      "type": "my_package",
      "length": 10,
      "width": 10,
      "height": 10,
      "weight": 10,
      "carrier_package_code": "USPS_LETTER",
      "dimension_unit": "in",
      "weight_unit": "lb"
    },
    "custom_data": {
      "signing_person": "Ray",
      "content_type": "merchandise",
      "tax_ids": [
        {
          "tax_id_type": "TIN",
          "tax_id_number": "tin2888",
          "country_code": "US"
        }
      ],
      "eel_pfc_type": "EXEMPTION_CODE",
      "eel_pfc_code": "X20250719123456",
      "undeliverable_option": "return_to_sender",
      "item_data_list": [
        {
          "description": "cloth",
          "quantity": 10,
          "origin": "US",
          "weight": 10,
          "unit_cost": 19.99,
          "weight_unit": "lb",
          "hs_tariff_number": "xx"
        }
      ]
    },
    "option_data": {
      "signature": "signature",
      "custom_text_on_label_1": "text1",
      "custom_text_on_label_2": "text2",
      "hazardous_materials": true,
      "additional_handing": false
    },
    "ship_date": "2025-07-31T00:00:00+08:00"
  }'

Responses

OK

Body*/*
codestring
Example: "ok"
msgstring
Example: "ok"
dataobject

Buy Label

Request

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.
Security
BearerAuth
Bodyapplication/jsonrequired
rate_idstringrequired

The unique identifier of a shipping rate returned by the get_rates endpoint. Use this value to reference a specific rate when purchasing a label.

Example: "dc288147-f7dd-494d-9353-5ce00020c7aa"
platform_uk_idstringrequired

A unique identifier provided by the calling party (e.g., the caller’s order number). Each platform_uk_id must correspond to exactly one shipment and cannot be reused across multiple shipments.

Example: "platformUkId175377917713"
insurance_dataobject(ShipmentInsuranceCreateRequest)

insurance data

label_print_typestringrequired

Defines the label print format. Supported types vary by carrier and may also depend on the selected service level. For example, USPS and FedEx may support qrcode, while UPS may support barcode.

Enum"common""qrcode""barcode"
Example: "common"
curl -i -X POST \
  https://x-api.shipsaving.us/api/shipment/create_and_pay \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "rate_id": "dc288147-f7dd-494d-9353-5ce00020c7aa",
    "platform_uk_id": "platformUkId175377917713",
    "insurance_data": {
      "rate_id": "dc288147-f7dd-494d-9353-5ce00020c7aa"
    },
    "label_print_type": "common"
  }'

Responses

OK

Body*/*
codestring
Example: "ok"
msgstring
Example: "ok"
dataobject(CreateAndBuyData)

Directly Buy Label

Request

Creates and purchases a shipment label in a single step without calling get_rates 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.
Security
BearerAuth
Bodyapplication/jsonrequired
service_levelstringrequired

Currently supports USPS_GROUND_ADVANTAGE only.

from_address_dataobject(ShipmentAddressData)required

Address object of the sender/recipient.

from_address_data.​phonestring

Phone number of the sender/recipient. Required for international shipments. Providing a phone number is highly recommended for all shipments to ensure accurate delivery and facilitate carrier contact if needed. For the Batch Quick Rate API, this parameter is optional.

Example: "1234567890"
from_address_data.​emailstring

Email address of the sender/recipient. May be used by the carrier for delivery notifications or issue resolution. For the Batch Quick Rate API, this parameter is optional.

Example: "support@shipsaving.com"
from_address_data.​streetstringrequired

First street line.

Example: "xxxx Castleton Street"
from_address_data.​street2string

Optional secondary address line (e.g., Apt, Suite, Unit, Floor).

Example: "STE XXX"
from_address_data.​citystringrequired
Example: "Los Angeles"
from_address_data.​statestringrequired
  • For U.S. addresses, this field must be a valid two-letter state code as defined by ISO 3166-2:US (e.g., "CA" for California, "NY" for New York).
  • For non-U.S. addresses, there is no restriction on the value.
Example: "CA"
from_address_data.​countrystringrequired

2-letter code for country. This field’s value will be an ISO 3166-1 two-digit code.

Example: "US"
from_address_data.​company_namestring
Example: "company name"
from_address_data.​first_namestringrequired

For the Batch Quick Rate API, this parameter is optional.

Example: "Alice"
from_address_data.​last_namestringrequired

For the Batch Quick Rate API, this parameter is optional.

Example: "Green"
from_address_data.​zip_codestringrequired
Example: "917XX"
from_address_data.​address_typestring

Specifies if the address is residential, which can impact the quoted shipping rate. Strongly recommended to provide this parameter.

Enum"residential""commercial"
Example: "residential"
to_address_dataobject(ShipmentAddressData)required

Address object of the sender/recipient.

to_address_data.​phonestring

Phone number of the sender/recipient. Required for international shipments. Providing a phone number is highly recommended for all shipments to ensure accurate delivery and facilitate carrier contact if needed. For the Batch Quick Rate API, this parameter is optional.

Example: "1234567890"
to_address_data.​emailstring

Email address of the sender/recipient. May be used by the carrier for delivery notifications or issue resolution. For the Batch Quick Rate API, this parameter is optional.

Example: "support@shipsaving.com"
to_address_data.​streetstringrequired

First street line.

Example: "xxxx Castleton Street"
to_address_data.​street2string

Optional secondary address line (e.g., Apt, Suite, Unit, Floor).

Example: "STE XXX"
to_address_data.​citystringrequired
Example: "Los Angeles"
to_address_data.​statestringrequired
  • For U.S. addresses, this field must be a valid two-letter state code as defined by ISO 3166-2:US (e.g., "CA" for California, "NY" for New York).
  • For non-U.S. addresses, there is no restriction on the value.
Example: "CA"
to_address_data.​countrystringrequired

2-letter code for country. This field’s value will be an ISO 3166-1 two-digit code.

Example: "US"
to_address_data.​company_namestring
Example: "company name"
to_address_data.​first_namestringrequired

For the Batch Quick Rate API, this parameter is optional.

Example: "Alice"
to_address_data.​last_namestringrequired

For the Batch Quick Rate API, this parameter is optional.

Example: "Green"
to_address_data.​zip_codestringrequired
Example: "917XX"
to_address_data.​address_typestring

Specifies if the address is residential, which can impact the quoted shipping rate. Strongly recommended to provide this parameter.

Enum"residential""commercial"
Example: "residential"
package_dataobject(ShipmentPackageData)required
package_data.​typestring

Defines the type of package being shipped.

  • my_package: Use when specifying custom package dimensions. Requires width, length, height, dimension_unit, weight, and weight_unit.
  • predefined: Use when selecting a carrier’s predefined package type. Requires carrier_package_code and weight fields only; dimension fields are ignored.
Enum"my_package""predefined"
Example: "my_package"
package_data.​lengthnumber

Length of the package in the selected unit.

Example: 10
package_data.​widthnumber

Width of the package in the selected unit.

Example: 10
package_data.​heightnumber

Height of the package in the selected unit.

Example: 10
package_data.​weightnumber

Weight of the package in the selected unit.

Example: 10
package_data.​carrier_package_codestring

carrier package code

Enum"USPS_LETTER""USPS_LARGE_ENVELOPE_OR_FLAT""USPS_THICK_ENVELOPE""USPS_SMALL_FLAT_RATE_BOX""USPS_MEDIUM_FLAT_RATE_BOX""USPS_LARGE_FLAT_RATE_BOX""USPS_FLAT_RATE_ENVELOPE""USPS_PADDED_FLAT_RATE_ENVELOPE""USPS_LEGAL_FLAT_RATE_ENVELOPE""UPS_LETTER"
Example: "USPS_LETTER"
package_data.​dimension_unitstring

Selected dimension unit.

Enum"in""cm"
Example: "in"
package_data.​weight_unitstring

Selected weight unit.

Enum"kg""lb"
Example: "lb"
custom_dataobject(ShipmentCustomData)

custom data

option_dataobject(ShipmentOptionData)required

Additional shipping options

option_data.​signaturestring

Request standard or adult signature confirmation.

Enum"signature""adult_signature"
option_data.​custom_text_on_label_1string

Customized print on label.If the label itself supports custom printing content, this field will be printed onto the label.

Example: "text1"
option_data.​custom_text_on_label_2string

Customized print on label.If the label itself supports custom printing content, this field will be printed onto the label.

Example: "text2"
option_data.​hazardous_materialsboolean

Whether this shipment contains dangerous goods or hazardous materials (USPS Ground Advantage service only). View tutorial about how to package, label and ship HAZMAT for domestic shipments.

Example: true
option_data.​additional_handingboolean

Indicates whether the package requires additional handling due to size, weight, or packaging that falls outside standard shipping guidelines. Carriers may apply extra fees when this is set to true.

Example: false
ship_datestringrequired

Timestamp in ISO 8601 format, including local time and time zone offset.

Example: "2025-07-31T00:00:00+08:00"
platform_uk_idstringrequired

A unique identifier provided by the calling party (e.g., the caller’s order number). Each platform_uk_id must correspond to exactly one shipment and cannot be reused across multiple shipments.

Example: "platformUkId175377917713"
insurance_dataobject(ShipmentInsuranceCreateRequest)

insurance data

label_print_typestringrequired

Defines the label print format. Supported types vary by carrier and may also depend on the selected service level. For example, USPS and FedEx may support qrcode, while UPS may support barcode.

Enum"common""qrcode""barcode"
Example: "common"
curl -i -X POST \
  https://x-api.shipsaving.us/api/shipment/direct_buy \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "service_level": "string",
    "from_address_data": {
      "phone": "1234567890",
      "email": "support@shipsaving.com",
      "street": "xxxx Castleton Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "country": "US",
      "company_name": "company name",
      "first_name": "Alice",
      "last_name": "Green",
      "zip_code": "917XX",
      "address_type": "residential"
    },
    "to_address_data": {
      "phone": "1234567890",
      "email": "support@shipsaving.com",
      "street": "xxxx Castleton Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "country": "US",
      "company_name": "company name",
      "first_name": "Alice",
      "last_name": "Green",
      "zip_code": "917XX",
      "address_type": "residential"
    },
    "package_data": {
      "type": "my_package",
      "length": 10,
      "width": 10,
      "height": 10,
      "weight": 10,
      "carrier_package_code": "USPS_LETTER",
      "dimension_unit": "in",
      "weight_unit": "lb"
    },
    "custom_data": {
      "signing_person": "Ray",
      "content_type": "merchandise",
      "tax_ids": [
        {
          "tax_id_type": "TIN",
          "tax_id_number": "tin2888",
          "country_code": "US"
        }
      ],
      "eel_pfc_type": "EXEMPTION_CODE",
      "eel_pfc_code": "X20250719123456",
      "undeliverable_option": "return_to_sender",
      "item_data_list": [
        {
          "description": "cloth",
          "quantity": 10,
          "origin": "US",
          "weight": 10,
          "unit_cost": 19.99,
          "weight_unit": "lb",
          "hs_tariff_number": "xx"
        }
      ]
    },
    "option_data": {
      "signature": "signature",
      "custom_text_on_label_1": "text1",
      "custom_text_on_label_2": "text2",
      "hazardous_materials": true,
      "additional_handing": false
    },
    "ship_date": "2025-07-31T00:00:00+08:00",
    "platform_uk_id": "platformUkId175377917713",
    "insurance_data": {
      "rate_id": "dc288147-f7dd-494d-9353-5ce00020c7aa"
    },
    "label_print_type": "common"
  }'

Responses

OK

Body*/*
codestring
Example: "ok"
msgstring
Example: "ok"
dataobject(CreateAndBuyData)

Void Label

Request

This endpoint allows voiding label by providing either shipment_no or platform_uk_id. Only one parameter is required to uniquely identify a shipment.

Security
BearerAuth
Bodyapplication/jsonrequired
shipment_nostring

Unique shipment number returned by the create_and_pay endpoint.

Example: "1222241586"
platform_uk_idstring

A unique identifier provided by the calling party (e.g., the caller’s order number). Each platform_uk_id must correspond to exactly one shipment and cannot be reused across multiple shipments.

Example: "platformUkId175377917713"
curl -i -X POST \
  https://x-api.shipsaving.us/api/shipment/void_label \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "shipment_no": "1222241586",
    "platform_uk_id": "platformUkId175377917713"
  }'

Responses

OK

Body*/*
codestring
Example: "ok"
msgstring
Example: "ok"
dataobject
Example: true

Query Insurance Rate

Request

Security
BearerAuth
Query
declared_valuenumberrequired

Declared value for shipment insurance, representing the insured amount in USD.

Example: declared_value=200
service_levelstringrequired

The insurance quote request must specify a service_level. Pricing varies depending on the selected service level.

Example: service_level=USPS_GROUND_ADVANTAGE
curl -i -X GET \
  'https://x-api.shipsaving.us/api/shipment/insurance/rate?declared_value=200&service_level=USPS_GROUND_ADVANTAGE' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Body*/*
codestringrequired
Example: "ok"
msgstringrequired
Example: "ok"
dataobject(InsuranceRateData)required
data.​carrierstring

Carrier code for the shipment.

Example: "usps"
data.​rate_idstring(uuid)

Unique identifier of the insurance rate, used when purchasing insurance.

Example: "f58fd5ce-10e3-4536-a4ef-68d8f476e9b4"
data.​service_levelstring

Service level code for the shipment.

Example: "USPS_GROUND_ADVANTAGE"
data.​ratenumber(float)

Insurance cost for the specified service level and declared value.

Example: 1.98
data.​declared_valuenumber(float)

Declared shipment value for insurance coverage calculation.

Example: 200

Query Shipment Tracking Status

Request

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.

Security
BearerAuth
Query
shipment_nostringrequired

Unique shipment number returned by the create_and_pay endpoint.

Example: shipment_no=1222241586
curl -i -X GET \
  'https://x-api.shipsaving.us/api/shipment/tracking?shipment_no=1222241586' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Body*/*
codestringrequired

API response code; "ok" indicates success.

Example: "ok"
msgstringrequired

Human-readable response message.

Example: "ok"
dataobject(TrackingData)required

This is the latest tracking record.

data.​scanned_timestring(date-time)

The UTC timestamp when the package was scanned, in ISO 8601 format.

Example: "2025-08-26T22:37:27Z"
data.​statusstring

Current shipment status. Possible values include:

  • created: The shipment label has been generated but not yet scanned by the carrier.
    Indicates the shipping process has not started.

  • available_for_pickup: The package has arrived at a designated location and is waiting for the recipient to collect it.
    Indicates customer action is required to retrieve the shipment.

  • in_transit: The package is in transit, moving through different facilities or checkpoints.
    Indicates the shipment is on its way but has not yet reached the destination.

  • out_for_delivery: The package has been handed over to the courier and is on its final delivery route.
    Indicates the shipment is in the last-mile delivery stage.

  • delivered: The package has been successfully delivered and signed for by the recipient.
    Indicates the shipping process is complete.

  • return_to_sender: The package is being returned to the sender due to failed delivery or other issues.
    Indicates a reverse logistics process.

  • voided: The shipping label has been voided and the package will not be processed.
    Indicates the shipment has been canceled or invalidated.

  • error: An error occurred during shipment handling.
    Indicates carrier-side issues that may require manual intervention.

  • seized_by_law_enforcement: The package was seized by law enforcement authorities.
    Indicates compliance or legal issues affecting the shipment.

  • unknown: The shipment status is unknown or no valid update is available from the carrier.
    Indicates no current tracking information.

Enum"created""available_for_pickup""in_transit""out_for_delivery""delivered""return_to_sender""voided""error""seized_by_law_enforcement""unknown"
Example: "in_transit"
data.​messagestring

Human-readable description of the status.

Example: "USPS in possession of item"
data.​locationobject(TrackingLocation)

Event location (if available).

data.​tracking_eventsArray of objects(TrackingEvent)

Query Shipment Tracking Status by `platform_uk_id`

Request

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.

Security
BearerAuth
Query
platform_uk_idstringrequired

A unique identifier provided by the calling party (e.g., the caller’s order number). Each platform_uk_id must correspond to exactly one shipment and cannot be reused across multiple shipments.

Example: platform_uk_id=platformUkId175377917713
curl -i -X GET \
  'https://x-api.shipsaving.us/api/shipment/tracking_by_platform_uk_id?platform_uk_id=platformUkId175377917713' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Body*/*
codestringrequired

API response code; "ok" indicates success.

Example: "ok"
msgstringrequired

Human-readable response message.

Example: "ok"
dataobject(TrackingData)required

This is the latest tracking record.

data.​scanned_timestring(date-time)

The UTC timestamp when the package was scanned, in ISO 8601 format.

Example: "2025-08-26T22:37:27Z"
data.​statusstring

Current shipment status. Possible values include:

  • created: The shipment label has been generated but not yet scanned by the carrier.
    Indicates the shipping process has not started.

  • available_for_pickup: The package has arrived at a designated location and is waiting for the recipient to collect it.
    Indicates customer action is required to retrieve the shipment.

  • in_transit: The package is in transit, moving through different facilities or checkpoints.
    Indicates the shipment is on its way but has not yet reached the destination.

  • out_for_delivery: The package has been handed over to the courier and is on its final delivery route.
    Indicates the shipment is in the last-mile delivery stage.

  • delivered: The package has been successfully delivered and signed for by the recipient.
    Indicates the shipping process is complete.

  • return_to_sender: The package is being returned to the sender due to failed delivery or other issues.
    Indicates a reverse logistics process.

  • voided: The shipping label has been voided and the package will not be processed.
    Indicates the shipment has been canceled or invalidated.

  • error: An error occurred during shipment handling.
    Indicates carrier-side issues that may require manual intervention.

  • seized_by_law_enforcement: The package was seized by law enforcement authorities.
    Indicates compliance or legal issues affecting the shipment.

  • unknown: The shipment status is unknown or no valid update is available from the carrier.
    Indicates no current tracking information.

Enum"created""available_for_pickup""in_transit""out_for_delivery""delivered""return_to_sender""voided""error""seized_by_law_enforcement""unknown"
Example: "in_transit"
data.​messagestring

Human-readable description of the status.

Example: "USPS in possession of item"
data.​locationobject(TrackingLocation)

Event location (if available).

data.​tracking_eventsArray of objects(TrackingEvent)

Address Validation

Request

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.

Validation Rules

  1. Non-U.S. addresses
    If country != "US", the validation process is skipped (the API is designed for U.S. domestic addresses only).

  2. Errored results
    If errored = true, the errors array is returned and should be used directly as the error message(s).

  3. Corrected without errors
    If errored = false && corrected = true, use the returned address fields (street, street2, city, state, zip, country, residential) as the standardized address.

    • The corrections array provides machine-readable codes that indicate how to improve the original input for a better match.

  4. Standardized flag
    The field standardized indicates whether the returned address differs from the original input:

    • If identical, standardized = false.
    • If different (e.g., casing, ZIP+4 adjustments, or street corrections), then standardized = true.
Security
BearerAuth
Bodyapplication/jsonrequired
streetstringrequired

Primary street line (house number + street name).

Example: "17XXX Castleton Street"
street2string or null

Secondary address line (apt, suite, unit, etc.).

Example: "STE XXX"
citystringrequired

City or locality.

Example: "City Of XXXX"
statestring= 2 charactersrequired
Example: "CA"
zipstring^\d{5}(-?\d{4})?$required

ZIP or ZIP+4 (US). Accepts 5 or 9 digits, with optional dash.

Example: "91748-5761"
countrystring= 2 charactersrequired

Two-letter country code (ISO 3166-1 alpha-2).

Example: "US"
curl -i -X POST \
  https://x-api.shipsaving.us/api/address/validate \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "street": "17XXX Castleton Street",
    "street2": "STE XXX",
    "city": "City Of XXXX",
    "state": "CA",
    "zip": "91748-5761",
    "country": "US"
  }'

Responses

OK

Bodyapplication/json
codestringrequired

Result code.

Example: "ok"
msgstringrequired

Human-readable message.

Example: "ok"
dataobject(ValidatedAddress)required
data.​streetstringrequired

Standardized primary street line.

Example: "17XXX CASTLETON ST"
data.​street2string or null

Standardized secondary line, if available.

Example: null
data.​citystringrequired

Standardized city/locality (uppercase).

Example: "CITY OF INDUSTRY"
data.​statestringrequired
Example: "CA"
data.​zipstringrequired

Standardized ZIP or ZIP+4.

Example: "91748-1749"
data.​countrystringrequired

ISO 3166-1 alpha-2 country code.

Example: "US"
data.​residentialbooleanrequired

Whether the address is classified as residential.

Example: true
data.​erroredbooleanrequired

Whether validation encountered one or more errors.

Example: true
data.​correctedbooleanrequired

Whether any components were corrected by the validator.

Example: true
data.​standardizedbooleanrequired

Whether the address is fully standardized.

Example: false
data.​errorsArray of objects(AddressIssue)required

Validation errors discovered during processing.

Example: [{"code":"ADDRESS.SECONDARY.MISSING","message":"High-rise address missing secondary number."}]
data.​errors[].​codestringrequired

Machine-readable issue code.

Example: "ADDRESS.SECONDARY.MISSING"
data.​errors[].​messagestringrequired

Human-readable description of the issue.

Example: "High-rise address missing secondary number."
data.​correctionsArray of objects(AddressIssue)required

Applied corrections or suggestions.

Example: [{"code":"ADDRESS.COMPONENT.CHANGED","message":"An address component (i.e., directional or suffix only) was changed"}]
data.​corrections[].​codestringrequired

Machine-readable issue code.

Example: "ADDRESS.SECONDARY.MISSING"
data.​corrections[].​messagestringrequired

Human-readable description of the issue.

Example: "High-rise address missing secondary number."
Response
application/json
{
  "code": "ok",
  "msg": "ok",
  "data": {
    "street": "17800 CASTLETON ST",
    "street2": null,
    "city": "CITY OF INDUSTRY",
    "state": "CA",
    "zip": "91748-1749",
    "country": "US",
    "residential": true,
    "errored": true,
    "corrected": true,
    "standardized": false,
    "errors": [ … ],
    "corrections": [ … ]
  }
}
Copyright © 2025 ShipSaving. All Rights Reserved.