Skip to content

ShipSaving New API (v2)

Overview
License
Languages
Servers
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.
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.

Security
BearerAuth
Bodyapplication/jsonrequired
request_unique_idstring(RequestUniqueId)required

A unique identifier generated by the requesting client to mark a single rate request within a batch. This value will be echoed back in the corresponding response, ensuring one-to-one mapping between requests.

Example: "unique_uuid_001"
from_address_dataobject(AddressFrom)required
from_address_data.​first_namestringrequired

First Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.

Example: "Alice"
from_address_data.​last_namestringrequired

Last Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.

Example: "Green"
from_address_data.​company_namestring

Firm/business name corresponding to the address.

Example: "ShipSaving"
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.

Example: 1234567890
from_address_data.​emailstring

Email address of the sender/recipient. May be used by the carrier for delivery notifications or issue resolution.

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

The number of a building along with the name of the road or street on which it is located.

Example: "xxxx Olive Street"
from_address_data.​street2string

The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building.

Example: "STE XXX"
from_address_data.​citystringrequired

This is the city name of the address.

Example: "Los Angeles"
from_address_data.​statestringrequired
  • For U.S. addresses, this field must be a valid two-letter state code (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.​zip_codestringrequired

Postal code of an Address.

Example: "021XX"
from_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_dataobject(AddressTo)required
to_address_data.​first_namestringrequired

First Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.

Example: "Alice"
to_address_data.​last_namestringrequired

Last Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.

Example: "Green"
to_address_data.​company_namestring

Firm/business name corresponding to the address.

Example: "ShipSaving"
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.

Example: 1234567890
to_address_data.​emailstring

Email address of the sender/recipient. May be used by the carrier for delivery notifications or issue resolution.

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

The number of a building along with the name of the road or street on which it is located.

Example: "xxxx Olive Street"
to_address_data.​street2string

The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building.

Example: "STE XXX"
to_address_data.​citystringrequired

This is the city name of the address.

Example: "Los Angeles"
to_address_data.​statestringrequired
  • For U.S. addresses, this field must be a valid two-letter state code (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.​zip_codestringrequired

Postal code of an Address.

Example: "021XX"
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.​address_typestringrequired

Indicates whether the destination address is residential or commercial. This flag is used to determine carrier-specific surcharges (e.g., UPS residential delivery fees).

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(CarrierPackageCodeEnum)

Carrier package code identifier. See Appendix - Carrier Package Codes for supported values in the ShipSaving New API (v2).

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_SMALL_FLAT_RATE_BOX"
package_data.​dimension_unitstring(DimensionUnitEnum)

Selected dimension unit.

Enum"in""cm"
Example: "in"
package_data.​weight_unitstring(WeightUnitEnum)

Selected weight unit.

Enum"lb""oz""kg""g"
Example: "lb"
option_dataobject(ShipmentOptionData)

Additional shipping options

ship_datestring(ShipDate)required

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

Example: "2025-07-31T00:00:00+08:00"
shipment_rate_carrier_dataArray of objects(ShipmentRateCarrierData)

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

curl -i -X POST \
  https://x-api.shipsaving.com/api/shipment/batch/quick_rate \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "request_unique_id": "unique_uuid_001",
    "from_address_data": {
      "first_name": "Alice",
      "last_name": "Green",
      "company_name": "ShipSaving",
      "phone": 1234567890,
      "email": "support@shipsaving.com",
      "street": "xxxx Olive Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "zip_code": "021XX",
      "country": "US"
    },
    "to_address_data": {
      "first_name": "Alice",
      "last_name": "Green",
      "company_name": "ShipSaving",
      "phone": 1234567890,
      "email": "support@shipsaving.com",
      "street": "xxxx Olive Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "zip_code": "021XX",
      "country": "US",
      "address_type": "residential"
    },
    "package_data": {
      "type": "my_package",
      "length": 10,
      "width": 10,
      "height": 10,
      "weight": 10,
      "carrier_package_code": "USPS_SMALL_FLAT_RATE_BOX",
      "dimension_unit": "in",
      "weight_unit": "lb"
    },
    "option_data": {
      "signature": "signature",
      "custom_text_on_label_1": "Please put the package in the locker.",
      "custom_text_on_label_2": "Please put the package in the locker.",
      "hazardous_materials": true,
      "additional_handling": false,
      "require_saturday_delivery": false
    },
    "ship_date": "2025-07-31T00:00:00+08:00",
    "shipment_rate_carrier_data": [
      {
        "provider_id": "USPS_B",
        "service_levels": [
          "USPS_GROUND_ADVANTAGE"
        ]
      }
    ]
  }'

Responses

OK

Bodyapplication/json
codestring
Example: "ok"
msgstring
Example: "ok"
dataArray of objects(BatchQuickRateItem)
Response
application/json
{ "code": "ok", "msg": "ok", "data": [ {} ] }

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
return_address_dataobject(AddressReturn)

Address where the package should be returned if undeliverable or returned to sender. Note: Only USPS supports printing a dedicated return address on the label.

from_address_dataobject(AddressFrom)required
from_address_data.​first_namestringrequired

First Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.

Example: "Alice"
from_address_data.​last_namestringrequired

Last Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.

Example: "Green"
from_address_data.​company_namestring

Firm/business name corresponding to the address.

Example: "ShipSaving"
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.

Example: 1234567890
from_address_data.​emailstring

Email address of the sender/recipient. May be used by the carrier for delivery notifications or issue resolution.

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

The number of a building along with the name of the road or street on which it is located.

Example: "xxxx Olive Street"
from_address_data.​street2string

The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building.

Example: "STE XXX"
from_address_data.​citystringrequired

This is the city name of the address.

Example: "Los Angeles"
from_address_data.​statestringrequired
  • For U.S. addresses, this field must be a valid two-letter state code (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.​zip_codestringrequired

Postal code of an Address.

Example: "021XX"
from_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_dataobject(AddressTo)required
to_address_data.​first_namestringrequired

First Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.

Example: "Alice"
to_address_data.​last_namestringrequired

Last Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.

Example: "Green"
to_address_data.​company_namestring

Firm/business name corresponding to the address.

Example: "ShipSaving"
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.

Example: 1234567890
to_address_data.​emailstring

Email address of the sender/recipient. May be used by the carrier for delivery notifications or issue resolution.

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

The number of a building along with the name of the road or street on which it is located.

Example: "xxxx Olive Street"
to_address_data.​street2string

The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building.

Example: "STE XXX"
to_address_data.​citystringrequired

This is the city name of the address.

Example: "Los Angeles"
to_address_data.​statestringrequired
  • For U.S. addresses, this field must be a valid two-letter state code (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.​zip_codestringrequired

Postal code of an Address.

Example: "021XX"
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.​address_typestringrequired

Indicates whether the destination address is residential or commercial. This flag is used to determine carrier-specific surcharges (e.g., UPS residential delivery fees).

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(CarrierPackageCodeEnum)

Carrier package code identifier. See Appendix - Carrier Package Codes for supported values in the ShipSaving New API (v2).

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_SMALL_FLAT_RATE_BOX"
package_data.​dimension_unitstring(DimensionUnitEnum)

Selected dimension unit.

Enum"in""cm"
Example: "in"
package_data.​weight_unitstring(WeightUnitEnum)

Selected weight unit.

Enum"lb""oz""kg""g"
Example: "lb"
option_dataobject(ShipmentOptionData)

Additional shipping options

ship_datestring(ShipDate)required

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

Example: "2025-07-31T00:00:00+08:00"
shipment_rate_carrier_dataArray of objects(ShipmentRateCarrierData)

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

custom_dataobject(ShipmentCustomData)

custom data

curl -i -X POST \
  https://x-api.shipsaving.com/api/shipment/get_rates \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "return_address_data": {
      "first_name": "Alice",
      "last_name": "Green",
      "company_name": "ShipSaving",
      "phone": 1234567890,
      "email": "support@shipsaving.com",
      "street": "xxxx Olive Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "zip_code": "021XX",
      "country": "US"
    },
    "from_address_data": {
      "first_name": "Alice",
      "last_name": "Green",
      "company_name": "ShipSaving",
      "phone": 1234567890,
      "email": "support@shipsaving.com",
      "street": "xxxx Olive Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "zip_code": "021XX",
      "country": "US"
    },
    "to_address_data": {
      "first_name": "Alice",
      "last_name": "Green",
      "company_name": "ShipSaving",
      "phone": 1234567890,
      "email": "support@shipsaving.com",
      "street": "xxxx Olive Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "zip_code": "021XX",
      "country": "US",
      "address_type": "residential"
    },
    "package_data": {
      "type": "my_package",
      "length": 10,
      "width": 10,
      "height": 10,
      "weight": 10,
      "carrier_package_code": "USPS_SMALL_FLAT_RATE_BOX",
      "dimension_unit": "in",
      "weight_unit": "lb"
    },
    "option_data": {
      "signature": "signature",
      "custom_text_on_label_1": "Please put the package in the locker.",
      "custom_text_on_label_2": "Please put the package in the locker.",
      "hazardous_materials": true,
      "additional_handling": false,
      "require_saturday_delivery": false
    },
    "ship_date": "2025-07-31T00:00:00+08:00",
    "shipment_rate_carrier_data": [
      {
        "provider_id": "USPS_B",
        "service_levels": [
          "USPS_GROUND_ADVANTAGE"
        ]
      }
    ],
    "custom_data": {
      "signing_person": "Ray",
      "content_type": "merchandise",
      "tax_ids": [
        {
          "tax_id_type": "TIN",
          "tax_id_number": "tin2888",
          "country_code": "US"
        }
      ],
      "eel_pfc_type": "ITN",
      "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"
        }
      ]
    }
  }'

Responses

OK

Bodyapplication/json
codestring
Example: "ok"
msgstring
Example: "ok"
dataobject
Response
application/json
{ "code": "ok", "msg": "ok", "data": { "fastest": {}, "cheapest": {}, "shipment_rate_data": [], "fastest_and_cheapest": {}, "error_info": {} } }

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_idstring(ShipmentRateId)required

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_idstring(PlatformUkId)required

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(InsuranceData)
label_print_typestring(LabelPrintTypeEnum)required

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"
is_return_labelboolean(IsReturnLabel)

Indicates whether the label is for a return shipment.

Default false
Example: false
is_exchange_labelboolean(IsExchangeLabel)

Indicates whether the shipment label belongs to a platform-specific exchange/return workflow. This field is used for certain marketplace integrations and will be stored internally in the tag field.

Default false
Example: false
curl -i -X POST \
  https://x-api.shipsaving.com/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",
    "is_return_label": false,
    "is_exchange_label": false
  }'

Responses

OK

Bodyapplication/json
codestring
Example: "ok"
msgstring
Example: "ok"
dataobject(ShipmentItem)
Response
application/json
{ "code": "ok", "msg": "ok", "data": { "zone": "1", "currency": "USD", "shipment_no": 1222243159, "tracking_no": "9234690381085700XXXXX", "total_fee": 39.39, "label_fee": 39.39, "insurance_fee": null, "label_urls": [], "qrcode_urls": [], "commercial_urls": null, "duplicate_label": true, "label_print_type": "common" } }

Directly Buy Label

Request

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.
Security
BearerAuth
Bodyapplication/jsonrequired
platform_uk_idstring(PlatformUkId)required

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"
carrier_codestring(CarrierCodeEnum)required

Carrier code identifier.

Enum"USPS""UPS""FEDEX""DHL_EXPRESS""SWIFTX""GOFO_EXPRESS""UPS_CANADA"
Example: "USPS"
service_levelstring(ServiceLevelEnum)required

Carrier service level. See Appendix - Carrier Service Types for the valid relationships between carrier_code, provider_id, and service_level.

Enum"USPS_FIRST_CLASS_MAIL""USPS_GROUND_ADVANTAGE""USPS_PRIORITY_MAIL""USPS_PRIORITY_MAIL_EXPRESS""USPS_MEDIA_MAIL""USPS_LIBRARY_MAIL""USPS_FIRST_CLASS_MAIL_INTERNATIONAL""USPS_PRIORITY_MAIL_INTERNATIONAL""USPS_PRIORITY_MAIL_EXPRESS_INTERNATIONAL""UPS_GROUND"
Example: "USPS_GROUND_ADVANTAGE"
return_address_dataobject(AddressReturn)

Address where the package should be returned if undeliverable or returned to sender. Note: Only USPS supports printing a dedicated return address on the label.

from_address_dataobject(AddressFrom)required
from_address_data.​first_namestringrequired

First Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.

Example: "Alice"
from_address_data.​last_namestringrequired

Last Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.

Example: "Green"
from_address_data.​company_namestring

Firm/business name corresponding to the address.

Example: "ShipSaving"
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.

Example: 1234567890
from_address_data.​emailstring

Email address of the sender/recipient. May be used by the carrier for delivery notifications or issue resolution.

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

The number of a building along with the name of the road or street on which it is located.

Example: "xxxx Olive Street"
from_address_data.​street2string

The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building.

Example: "STE XXX"
from_address_data.​citystringrequired

This is the city name of the address.

Example: "Los Angeles"
from_address_data.​statestringrequired
  • For U.S. addresses, this field must be a valid two-letter state code (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.​zip_codestringrequired

Postal code of an Address.

Example: "021XX"
from_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_dataobject(AddressTo)required
to_address_data.​first_namestringrequired

First Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.

Example: "Alice"
to_address_data.​last_namestringrequired

Last Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.

Example: "Green"
to_address_data.​company_namestring

Firm/business name corresponding to the address.

Example: "ShipSaving"
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.

Example: 1234567890
to_address_data.​emailstring

Email address of the sender/recipient. May be used by the carrier for delivery notifications or issue resolution.

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

The number of a building along with the name of the road or street on which it is located.

Example: "xxxx Olive Street"
to_address_data.​street2string

The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building.

Example: "STE XXX"
to_address_data.​citystringrequired

This is the city name of the address.

Example: "Los Angeles"
to_address_data.​statestringrequired
  • For U.S. addresses, this field must be a valid two-letter state code (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.​zip_codestringrequired

Postal code of an Address.

Example: "021XX"
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.​address_typestringrequired

Indicates whether the destination address is residential or commercial. This flag is used to determine carrier-specific surcharges (e.g., UPS residential delivery fees).

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(CarrierPackageCodeEnum)

Carrier package code identifier. See Appendix - Carrier Package Codes for supported values in the ShipSaving New API (v2).

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_SMALL_FLAT_RATE_BOX"
package_data.​dimension_unitstring(DimensionUnitEnum)

Selected dimension unit.

Enum"in""cm"
Example: "in"
package_data.​weight_unitstring(WeightUnitEnum)

Selected weight unit.

Enum"lb""oz""kg""g"
Example: "lb"
option_dataobject(ShipmentOptionData)

Additional shipping options

ship_datestring(ShipDate)required

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

Example: "2025-07-31T00:00:00+08:00"
custom_dataobject(ShipmentCustomData)

custom data

insurance_dataobject(InsuranceData)
label_print_typestring(LabelPrintTypeEnum)required

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"
is_return_labelboolean(IsReturnLabel)

Indicates whether the label is for a return shipment.

Default false
Example: false
is_exchange_labelboolean(IsExchangeLabel)

Indicates whether the shipment label belongs to a platform-specific exchange/return workflow. This field is used for certain marketplace integrations and will be stored internally in the tag field.

Default false
Example: false
curl -i -X POST \
  https://x-api.shipsaving.com/api/shipment/direct_buy \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "platform_uk_id": "platformUkId175377917713",
    "carrier_code": "USPS",
    "service_level": "USPS_GROUND_ADVANTAGE",
    "return_address_data": {
      "first_name": "Alice",
      "last_name": "Green",
      "company_name": "ShipSaving",
      "phone": 1234567890,
      "email": "support@shipsaving.com",
      "street": "xxxx Olive Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "zip_code": "021XX",
      "country": "US"
    },
    "from_address_data": {
      "first_name": "Alice",
      "last_name": "Green",
      "company_name": "ShipSaving",
      "phone": 1234567890,
      "email": "support@shipsaving.com",
      "street": "xxxx Olive Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "zip_code": "021XX",
      "country": "US"
    },
    "to_address_data": {
      "first_name": "Alice",
      "last_name": "Green",
      "company_name": "ShipSaving",
      "phone": 1234567890,
      "email": "support@shipsaving.com",
      "street": "xxxx Olive Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "zip_code": "021XX",
      "country": "US",
      "address_type": "residential"
    },
    "package_data": {
      "type": "my_package",
      "length": 10,
      "width": 10,
      "height": 10,
      "weight": 10,
      "carrier_package_code": "USPS_SMALL_FLAT_RATE_BOX",
      "dimension_unit": "in",
      "weight_unit": "lb"
    },
    "option_data": {
      "signature": "signature",
      "custom_text_on_label_1": "Please put the package in the locker.",
      "custom_text_on_label_2": "Please put the package in the locker.",
      "hazardous_materials": true,
      "additional_handling": false,
      "require_saturday_delivery": false
    },
    "ship_date": "2025-07-31T00:00:00+08:00",
    "custom_data": {
      "signing_person": "Ray",
      "content_type": "merchandise",
      "tax_ids": [
        {
          "tax_id_type": "TIN",
          "tax_id_number": "tin2888",
          "country_code": "US"
        }
      ],
      "eel_pfc_type": "ITN",
      "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"
        }
      ]
    },
    "insurance_data": {
      "rate_id": "dc288147-f7dd-494d-9353-5ce00020c7aa"
    },
    "label_print_type": "common",
    "is_return_label": false,
    "is_exchange_label": false
  }'

Responses

OK

Bodyapplication/json
codestring
Example: "ok"
msgstring
Example: "ok"
dataobject(ShipmentItem)
Response
application/json
{ "code": "ok", "msg": "ok", "data": { "zone": "1", "currency": "USD", "shipment_no": 1222243159, "tracking_no": "9234690381085700XXXXX", "total_fee": 39.39, "label_fee": 39.39, "insurance_fee": null, "label_urls": [], "qrcode_urls": [], "commercial_urls": null, "duplicate_label": true, "label_print_type": "common" } }

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(ShipmentNo)

Unique identifier of the created shipment.

Example: 1222243159
platform_uk_idstring(PlatformUkId)

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.com/api/shipment/void_label \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "shipment_no": 1222243159,
    "platform_uk_id": "platformUkId175377917713"
  }'

Responses

OK

Bodyapplication/json
codestring
Example: "ok"
msgstring
Example: "ok"
dataobject
Example: {}
Response
application/json
{ "code": "ok", "msg": "ok", "data": {} }

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.com/api/shipment/insurance/rate?declared_value=200&service_level=USPS_GROUND_ADVANTAGE' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Bodyapplication/json
codestring
Example: "ok"
msgstring
Example: "ok"
dataobject(InsuranceRateItem)
Response
application/json
{ "code": "ok", "msg": "ok", "data": { "carrier": "USPS", "rate_id": "dc288147-f7dd-494d-9353-5ce00020c7aa", "service_level": "USPS_GROUND_ADVANTAGE", "rate": 1.98, "declared_value": 200 } }

Tracking

Operations

Pickup

Operations

Address Validation

Operations