Directly Buy Label

API Reference

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

to_address_dataobject(AddressTo)required

package_dataobject(ShipmentPackageData)required

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

POST

/api/shipment/direct_buy

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": "it@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": "it@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": "it@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,
      "is_lithium_battery": false,
      "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

Bodyapplication/json

codestring

Example:"ok"

msgstring

Example:"ok"

dataobject(ShipmentItem)

Response

{
  "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_processing_fee": 0.05,
    "label_urls": [ … ],
    "qrcode_urls": [ … ],
    "commercial_urls": null,
    "duplicate_label": true,
    "label_print_type": "common"
  }
}