## Integration 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: ```json "shipment_rate_carrier_data": [ { "provider_id": "USPS_B", "service_levels": ["USPS_GROUND_ADVANTAGE"] } ] ``` Filtering by specific carriers and service levels can improve performance by reducing the number of rate lookups. Example request: ```curl 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: ```json { "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 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: ```json { "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: ```json { "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" } ```