Skip to content
/
Integration
Last updated

Introduction

The ShipSaving API offers two integration modes for creating shipping labels:

  1. Two-step integration – Ideal when you want to review and select a service level before purchasing.
  • Step 1: Request all available rates.
  • Step 2: Purchase a label using the chosen rate.
  1. Single-step integration – Ideal for fully automated workflows, combining rate retrieval and label purchase into a single API call.

Two-step integration

To obtain all available shipping rates and purchase a label for a selected rate, follow these steps:

Step 1 – Retrieve rates

Call the /api/shipment/get_rates endpoint to create a shipment and retrieve rate options. The request body must include:

  • Two address objects: from_address_data and to_address_data

  • package_data object

  • Optional: custom_data

  • Optional: option_data

  • Optional: shipment_rate_carrier_data — Allows you to filter rates by carrier and service level for faster queries:

    • Specify one or more carriers using provider_id

    • Specify one or more service levels using the service_levels array

    • Example:

      "shipment_rate_carrier_data": [
  {
      "provider_id": "USPS_B",
      "service_levels": ["USPS_GROUND_ADVANTAGE"]
  }
]
      INFO

      Filtering by specific carriers and service levels can improve performance by reducing the number of rate lookups.

Example request:

curl --location 'https://x-api.shipsaving.us/api/shipment/get_rates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiIxIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJTU19MSVZFX2RYbzNPeTlXRXFLWTRmcHVDT013Q3pDX1BqcElEd3VKc1dDZiIsImF1ZCI6IlNTX0xJVkVfZFhvM095OVdFcUtZNGZwdUNPTXdDekNfUGpwSUR3dUpzV0NmIiwibmJmIjoxNzU0OTQ2MDc3LCJjb21wYW55X2lkIjoiMTgxOCIsInVzZXJfaWQiOiIyNDAyIiwic2NvcGUiOlsiQVBJIl0sImlzX3ZhbGlkIjp0cnVlLCJpc3MiOiJodHRwczovL3gtYXBpLnNoaXBzYXZpbmcudXMiLCJleHAiOjE3NTQ5NDc4NzcsImlhdCI6MTc1NDk0NjA3NywidGVzdF9tb2RlbCI6ZmFsc2V9.ZZTr3HBLjlrKMck2YeQmpkh-6c8r7Z9aqLLVRLioKkcD7c3M41GMDx3qb-LG3XvAJicJe-BYX64pcJ0heCpP7uG6sSq0P7pLR--VdysbinCRB4Bz1VIWRjFkmsMtab2Gi3YToPR4JRV99zVWFI6cKqmaqWIBLyVkWmgAUMIi4PTmFgMUyouqo_GJ6FFmwKb-Av1JrrUe8t5DhDMBuXRl8Da-eLqZSRsQyQ1WV5-uLP7ESYM0k0h5R6I7u-7uT8vf8NR8U8jUYIkzcMb47PuWUxsaWn5ngFLTq03H28g1QV10gxFkBMFgzKEPumxadzzttfDbFXtSd7ALzvC7pXigxA' \
--data-raw '{
    "to_address_data": {
        "city": "City Of Industry",
        "country": "US",
        "state": "CA",
        "street": "17XXX Castleton Street",
        "street2": "STE 500",
        "zip_code": "91XXX",
        "first_name": "Alice",
        "last_name": "Li",
        "phone": "1234567890",
        "email": "support@shipsaving.com"
    },
    "from_address_data": {
        "city": "City Of Industry",
        "country": "US",
        "state": "CA",
        "street": "17XXX Castleton Street",
        "street2": "STE 500",
        "zip_code": "91XXX",
        "first_name": "Alice",
        "last_name": "Li",
        "phone": "1234567890",
        "email": "support@shipsaving.com"
    },
    "package_data": {
        "width": 3,
        "length": 6,
        "height": 0.25,
        "dimension_unit": "in",
        "weight": 2,
        "weight_unit": "oz",
        "type": "my_package" 
    },
    "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": "NOEEI 30.37(a)",
        "undeliverable_option": "return_to_sender",
        "item_data_list": [
            {
                "description": "cloth",
                "quantity": 1,
                "origin": "CN",
                "weight": 1,
                "unit_cost": 10.1,
                "weight_unit": "lb"
            }
        ]
    },
    "option_data": {
        "signature": null,
        "custom_text_on_label_1": "",
        "custom_text_on_label_2": "",
        "hazardous_materials": false,
        "additional_handing": false
    },
    "shipment_rate_carrier_data": [
        {
            "provider_id": "UPS_SS_DNI",
            "service_levels": ["UPS_GROUND"]
        }
    ],
    "ship_date": "2025-08-15T00:00:00+08:00"
}'

The /api/shipment/get_rates response contains:

  • Quotes from all active carriers and service levels linked to your account
  • Sorting by fastest, cheapest, and other criteria
  • error_info for carriers or services that could not provide a rate

Example response:

{
    "code": "ok",
    "msg": "ok",
    "data": {
        "fastest": null,
        "cheapest": {
            "zone": "1",
            "currency": "USD",
            "priceDetails": null,
            "cubic": false,
            "rate_id": "f3bfa0b5-3dde-4ccb-822f-f995d7e512c6",
            "account_id": 7152,
            "carrier_code": "GOFO_EXPRESS",
            "provider_id": "GOFO_EXPRESS_A",
            "service_name": "Gofo Express ECO",
            "service_level": "GOFO_EXPRESS_ECO",
            "service_level_desc": "ECO",
            "returned_package_code": "my_package",
            "delivery_days": "2-3",
            "delivery_date": null,
            "delivery_weekday": null,
            "service_detail": "ECO",
            "price": 2.75,
            "origin_price": null,
            "retail_price": null,
            "discount_text": null,
            "insurance_info": null,
            "ship_date": "2025-08-08T00:00:00+08:00",
            "saturday_delivery": false,
            "one_rate": false
        },
        "shipment_rate_data": [
            {
                "zone": "1",
                "currency": "USD",
                "priceDetails": null,
                "cubic": false,
                "rate_id": "5d73c5d9-3379-44b3-94b0-79c0d17c87e5",
                "account_id": 7148,
                "carrier_code": "USPS",
                "provider_id": "USPS_B",
                "service_name": "USPS Media Mail",
                "service_level": "USPS_MEDIA_MAIL",
                "service_level_desc": "A cost-effective way to send eligible books, media, and educational materials.",
                "returned_package_code": "my_package",
                "delivery_days": "4",
                "delivery_date": null,
                "delivery_weekday": null,
                "service_detail": "A cost-effective way to send eligible books, media, and educational materials.",
                "price": 4.47,
                "origin_price": null,
                "retail_price": 4.47,
                "discount_text": null,
                "insurance_info": null,
                "ship_date": "2025-08-08T00:00:00+08:00",
                "saturday_delivery": false,
                "one_rate": false
            },
            {
                "zone": "1",
                "currency": "USD",
                "priceDetails": null,
                "cubic": false,
                "rate_id": "f1ed77b3-4525-47f9-b536-8964a8681251",
                "account_id": 7148,
                "carrier_code": "USPS",
                "provider_id": "USPS_B",
                "service_name": "USPS Ground Advantage",
                "service_level": "USPS_GROUND_ADVANTAGE",
                "service_level_desc": "Low rates for packages with expected delivery in 2-5 business days.",
                "returned_package_code": "my_package",
                "delivery_days": "2",
                "delivery_date": null,
                "delivery_weekday": null,
                "service_detail": "Low rates for packages with expected delivery in 2-5 business days.",
                "price": 5.91,
                "origin_price": null,
                "retail_price": 8.70,
                "discount_text": null,
                "insurance_info": null,
                "ship_date": "2025-08-08T00:00:00+08:00",
                "saturday_delivery": false,
                "one_rate": false
            }
        ],
        "fastest_and_cheapest": null,
        "error_info": {
            "USPS": [
                {
                    "code": "invalid_request_params",
                    "message": "cannot be in the past or more than 30 days in the future"
                }
            ]
        }
    }
}

Step 2 – Purchase label

After selecting a rate_id from the /api/shipment/get_rates response, call the /api/shipment/create_and_buy endpoint to purchase the shipping label. You may also include insurance_data if applicable.

Example request:

curl --location 'https://x-api.shipsaving.us/api/shipment/create_and_pay' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiIxIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJTU19MSVZFX2RYbzNPeTlXRXFLWTRmcHVDT013Q3pDX1BqcElEd3VKc1dDZiIsImF1ZCI6IlNTX0xJVkVfZFhvM095OVdFcUtZNGZwdUNPTXdDekNfUGpwSUR3dUpzV0NmIiwibmJmIjoxNzU0NzAxNjA4LCJjb21wYW55X2lkIjoiMTgxOCIsInVzZXJfaWQiOiIyNDAyIiwic2NvcGUiOlsiQVBJIl0sImlzX3ZhbGlkIjp0cnVlLCJpc3MiOiJodHRwczovL3gtYXBpLnNoaXBzYXZpbmcudXMiLCJleHAiOjE3NTQ3MDM0MDgsImlhdCI6MTc1NDcwMTYwOCwidGVzdF9tb2RlbCI6ZmFsc2V9.oi14AMVCn_yGYEDCnBaYeci5FDRfAiO-VKSG_pMRCJEwM7zBJ93m0_-uUS1xmrFV7f3f4OPNeiHzSmNLhS0L2YYn5NXwU8PxMgpVhPGZgCWu31B6VIMaX2nnE5bB26sOrHDObE5wQeB1Yp0geG4KZ_2H5wwrK9fGfRWEH48GbOduQKgS5llIGDilUY0zvFKyeB7HTjDY0kO-hR0F7g0x77PVEk5PVvkBWiN1rOUlT7tAmMdtP-xHpM28U8xKQPOplcbdn4A8t9K2l3TZE84YvsJCzrtmQjr5Qj9m_uadmUNhSyzw5p3KvpI0-l_FWxHC3stkD2Q8CAoCs2Kb3Ur6bg' \
--data '{
    "platform_uk_id": "c_eDQCbv=2YVGw)7#$v_aCI9%ynJEa2O",
    "rate_id": "d9437e43-5283-4289-9ed3-5ef306bb50dd",
    "insurance_data": {
        "rate_id": "50c4685e-5045-4f85-aadc-1a58ff24e147"
    },
    "label_print_type": "common"
}'

Example response:

{
    "code": "ok",
    "msg": "ok",
    "data": {
        "shipment_no": "1222243143",
        "tracking_no": "1ZXXXXXXXXXXXXXXXX",
        "total_fee": 34.81,
        "label_fee": 34.81,
        "insurance_fee": null,
        "label_urls": [
            "https://xxx.amazonaws.com/labels/2025-08-11/8f6558b8fbb44fd2bdf826c645c9778e_0.png"
        ],
        "commercial_urls": null,
        "label_print_type": "common"
    }
}

Single-step integration

Ideal for fully automated workflows, this mode combines rate retrieval and label purchase into a single API call to /api/shipment/direct_buy. You provide all required shipment details together with the service_level field to specify the exact service to purchase, eliminating the separate rate selection step. You may also include the insurance_data object in the same request to purchase shipment insurance along with the label. This approach reduces the number of API calls and simplifies integration when the service level is predetermined.

Example request:

{
  "service_level": "USPS_GROUND_ADVANTAGE",
  "from_address_data": {
    "phone": "7819991234",
    "email": null,
    "street": "xxxx Castleton Street",
    "street2": "xxxxx",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "company_name": "Shipsaving02",
    "first_name": "Alice",
    "last_name": "Green",
    "zip_code": "91xxx",
    "address_type": "residential"
  },
  "to_address_data": {
    "first_name": "GU",
    "last_name": "GU",
    "country": "US",
    "phone": "9898912324",
    "street": "1328 Pale San Vitores Road, Tumon",
    "city": "Tamuning",
    "state": "GU",
    "zip_code": "96913",
    "save_address": true,
    "verified": false,
    "street2": ""
  },
  "package_data": {
    "type": "my_package",
    "length": 12,
    "width": 11,
    "height": 5,
    "weight": 1,
    "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": "ITN",
    "eel_pfc_code": "X20250719123456",
    "undeliverable_option": "return_to_sender",
    "item_data_list": [
      {
        "description": "Dazy Plus Plus Size Retro French Fashion Plaid 2 Pieces Set, Chic Outfit For Summer",
        "quantity": 1,
        "origin": "CN",
        "weight": 10,
        "unit_cost": 14.4,
        "weight_unit": "oz",
        "hs_tariff_number": "10.1234"
      }
    ]
  },
  "option_data": {
    "signature": null,
    "custom_text_on_label_1": "text1",
    "custom_text_on_label_2": "text2",
    "hazardous_materials": true,
    "additional_handing": false
  },
  "ship_date": "2025-08-15T00:00:00+08:00",
  "platform_uk_id": "platform_2344343535353",
  "insurance_data": {
    "rate_id": "57e8c472-e699-4900-9e0b-673b2b2034a5"
  },
  "label_print_type": "common"
}
Previous page
Next page
Copyright © 2025 ShipSaving. All Rights Reserved.