# Directly Buy Label

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.

Endpoint: POST /api/shipment/direct_buy
Version: v2
Security: BearerAuth

## Request fields (application/json):

  - `platform_uk_id` (string, 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_code` (string, required)
    Carrier code identifier.
    Enum: "USPS", "UPS", "FEDEX", "DHL_EXPRESS", "SWIFTX", "GOFO_EXPRESS", "UPS_CANADA"

  - `service_level` (string, required)
    Carrier service level. See [Appendix - Carrier Service Types](../../../../appendix.md) 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", "UPS_GROUND_SAVER", "UPS_NEXT_DAY_AIR", "UPS_NEXT_DAY_AIR_SAVER", "UPS_NEXT_DAY_AIR_EARLY", "UPS_2ND_DAY_AIR", "UPS_2ND_DAY_AIR_AM", "UPS_3_DAY_SELECT", "UPS_STANDARD", "UPS_WORLDWIDE_SAVER", "UPS_WORLDWIDE_EXPRESS", "UPS_WORLDWIDE_EXPRESS_PLUS", "UPS_WORLDWIDE_EXPEDITED", "UPS_SUREPOST_LESS_THAN_1_LB", "UPS_SUREPOST_1_LB_OR_GREATER", "FEDEX_GROUND", "FEDEX_2_DAY", "FEDEX_2_DAY_AM", "FEDEX_EXPRESS_SAVER", "FEDEX_STANDARD_OVERNIGHT", "FEDEX_FIRST_OVERNIGHT", "FEDEX_PRIORITY_OVERNIGHT", "FEDEX_INTERNATIONAL_ECONOMY", "FEDEX_INTERNATIONAL_FIRST", "FEDEX_INTERNATIONAL_PRIORITY", "FEDEX_HOME_DELIVERY", "FEDEX_SMARTPOST", "FEDEX_STANDARD_OVERNIGHT_EXTRA_HOURS", "FEDEX_FIRST_OVERNIGHT_EXTRA_HOURS", "FEDEX_PRIORITY_OVERNIGHT_EXTRA_HOURS", "FEDEX_INTERNATIONAL_PRIORITY_EXPRESS", "FEDEX_INTERNATIONAL_CONNECT_PLUS", "FEDEX_DATE_CERTAIN_HOME_DELIVERY", "FEDEX_EVENING_HOME_DELIVERY", "FEDEX_APPOINTMENT_HOME_DELIVERY", "FEDEX_INTERNATIONAL_PRIORITY_PR", "DHL_EXPRESS_WORLDWIDE_B2C", "DHL_EXPRESS_WORLDWIDE_B2C_NONDOC", "DHL_EXPRESS_JET_LINE_NONDOC", "DHL_EXPRESS_SPRINT_LINE", "DHL_EXPRESS_EURO_PACK_DOC", "DHL_EXPRESS_BREAK_BULK_EXPRESS", "DHL_EXPRESS_MEDICAL_EXPRESS", "DHL_EXPRESS_WORLDWIDE_DOC", "DHL_EXPRESS_0900_NONDOC", "DHL_EXPRESS_FREIGHT_WORLDWIDE_NONDOC", "DHL_EXPRESS_DOMESTIC_ECONOMY_SELECT", "DHL_EXPRESS_ECONOMY_SELECT_NONDOC", "DHL_EXPRESS_DOMESTIC_EXPRESS_0900", "DHL_EXPRESS_JUMBO_BOX_NONDOC", "DHL_EXPRESS_0900", "DHL_EXPRESS_1030", "DHL_EXPRESS_1030_NONDOC", "DHL_EXPRESS_DOMESTIC_EXPRESS", "DHL_EXPRESS_DOMESTIC_EXPRESS_1030", "DHL_EXPRESS_WORLDWIDE_NONDOC", "DHL_EXPRESS_MEDICAL_EXPRESS_NODOC", "DHL_EXPRESS_GLOBAL_MAIL_BUSINESS", "DHL_EXPRESS_SAME_DAY", "DHL_EXPRESS_1200_DOC", "DHL_EXPRESS_WORLDWIDE_ECX", "DHL_EXPRESS_EURO_PACK_NONDOC", "DHL_EXPRESS_ECONOMY_SELECT", "DHL_EXPRESS_ENVELOPE", "DHL_EXPRESS_1200_NONDOC", "DHL_EXPRESS_DOMESTIC_EXPRESS_1200", "GOFO_EXPRESS_ECO", "SWIFTX_EXP", "UPS_CANADA_EXPEDITED", "UPS_CANADA_EXPRESS_EARLY", "UPS_CANADA_EXPRESS_SAVER", "UPS_CANADA_EXPRESS", "UPS_CANADA_STANDARD", "UPS_CANADA_3_DAY_SELECT", "UPS_CANADA_EXPRESS_EARLY_SM", "UPS_CANADA_WORLDWIDE_EXPEDITED_SM", "UPS_CANADA_WORLDWIDE_EXPRESS_PLUS_SM", "UPS_CANADA_WORLDWIDE_EXPRESS_SM", "UPS_CANADA_EXPRESS_SAVER_SM"

  - `return_address_data` (object)
    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.

  - `return_address_data.first_name` (string, required)
    First Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.
    Example: "Alice"

  - `return_address_data.last_name` (string, required)
    Last Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.
    Example: "Green"

  - `return_address_data.company_name` (string)
    Firm/business name corresponding to the address.
    Example: "ShipSaving"

  - `return_address_data.phone` (string)
    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

  - `return_address_data.email` (string)
    Email address of the sender/recipient. May be used by the carrier for delivery notifications or issue resolution.
    Example: "support@shipsaving.com"

  - `return_address_data.street` (string, required)
    The number of a building along with the name of the road or street on which it is located.
    Example: "xxxx Olive Street"

  - `return_address_data.street2` (string)
    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"

  - `return_address_data.city` (string, required)
    This is the city name of the address.
    Example: "Los Angeles"

  - `return_address_data.state` (string, required)
    - 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"

  - `return_address_data.zip_code` (string, required)
    Postal code of an Address.
    Example: "021XX"

  - `return_address_data.country` (string, required)
    2-letter code for country. This field’s value will be an [ISO 3166-1 two-digit code](https://en.wikipedia.org/wiki/ISO_3166-1).
    Example: "US"

  - `from_address_data` (object, required)

  - `to_address_data` (object, required)

  - `to_address_data.address_type` (string, required)
    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"

  - `package_data` (object, required)

  - `package_data.type` (string)
    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"

  - `package_data.length` (number)
    Length of the package in the selected unit.
    Example: 10

  - `package_data.width` (number)
    Width of the package in the selected unit.
    Example: 10

  - `package_data.height` (number)
    Height of the package in the selected unit.
    Example: 10

  - `package_data.weight` (number)
    Weight of the package in the selected unit.
    Example: 10

  - `package_data.carrier_package_code` (string)
    Carrier package code identifier. See [Appendix - Carrier Package Codes](../../../../appendix.md) 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", "UPS_25KG_BOX", "UPS_10KG_BOX", "UPS_TUBE", "UPS_PAK", "UPS_EXPRESS_BOX_SMALL", "UPS_EXPRESS_BOX_MEDIUM", "UPS_EXPRESS_BOX_LARGE", "FEDEX_ENVELOPE", "FEDEX_PAK", "FEDEX_TUBE", "FEDEX_EXTRA_SMALL_BOX", "FEDEX_SMALL_BOX", "FEDEX_MEDIUM_BOX", "FEDEX_LARGE_BOX", "FEDEX_EXTRA_LARGE_BOX", "FEDEX_BOX", "FEDEX_10KG_BOX", "FEDEX_25KG_BOX", "UPS_CANADA_LETTER", "UPS_CANADA_25KG_BOX", "UPS_CANADA_10KG_BOX", "UPS_CANADA_TUBE", "UPS_CANADA_PAK", "UPS_CANADA_EXPRESS_BOX_SMALL", "UPS_CANADA_EXPRESS_BOX_MEDIUM", "UPS_CANADA_EXPRESS_BOX_LARGE", "UPS_CANADA_EXPRESS_BOX"

  - `package_data.dimension_unit` (string)
    Selected dimension unit.
    Enum: "in", "cm"

  - `package_data.weight_unit` (string)
    Selected weight unit.
    Enum: "lb", "oz", "kg", "g"

  - `option_data` (object)
    Additional shipping options

  - `option_data.signature` (string)
    Request standard or adult signature confirmation.
    Enum: "signature", "adult_signature"

  - `option_data.custom_text_on_label_1` (string)
    Customized print on label.If the label itself supports custom printing content, this field will be printed onto the label.
    Example: "Please put the package in the locker."

  - `option_data.custom_text_on_label_2` (string)
    Customized print on label.If the label itself supports custom printing content, this field will be printed onto the label.
    Example: "Please put the package in the locker."

  - `option_data.hazardous_materials` (boolean)
    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_handling` (boolean)
    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.

  - `option_data.require_saturday_delivery` (boolean)
    When true, only returns rate quotes that support Saturday delivery. If false or omitted, all available rate quotes are returned regardless of Saturday delivery support.

Note: 
- Actual Saturday delivery availability depends on the carrier and service level — some carriers or services may not support it. 
- Enabling this preference may result in additional carrier surcharges or higher shipping costs if the selected service level applies extra fees for Saturday delivery.

  - `ship_date` (string, required)
    Timestamp in ISO 8601 format, including local time and time zone offset.
    Example: "2025-07-31T00:00:00+08:00"

  - `custom_data` (object)
    custom data

  - `custom_data.signing_person` (string)
    Name of the individual signing the customs form, typically the sender or an authorized agent, confirming that all declared information is accurate and compliant with applicable customs regulations.
    Example: "Ray"

  - `custom_data.content_type` (string)
    Enum: "merchandise", "documents", "return_merchandise", "sample", "gift"

  - `custom_data.tax_ids` (array)
    Sender's tax information

  - `custom_data.tax_ids.tax_id_type` (string)
    tax id type
    Enum: "TIN", "EIN", "SSN", "VAT", "EORI", "IOSS", "PAN"

  - `custom_data.tax_ids.tax_id_number` (string)
    tax id number
    Example: "tin2888"

  - `custom_data.tax_ids.country_code` (string)
    2-letter code for country. This field’s value will be an [ISO 3166-1 two-digit code](https://en.wikipedia.org/wiki/ISO_3166-1).
    Example: "US"

  - `custom_data.eel_pfc_type` (string)
    Indicates the Electronic Export Information (EEI) filing method for this shipment.
- Use ITN if an Internal Transaction Number was issued after AES filing.
- Use EXEMPTION_CODE if the shipment qualifies for an EEI filing exemption.
    Enum: "ITN", "EXEMPTION_CODE"

  - `custom_data.eel_pfc_code` (string)
    EEI filing identifier for this shipment. Provide either the Internal Transaction Number (ITN) received from AES, or the exemption code if EEI filing is not required. Please refer to [Appendix – Exemption Code Name Table](../../../appendix.md).
    Example: "X20250719123456"

  - `custom_data.undeliverable_option` (string)
    Defines the action to take for undeliverable shipments.
    Enum: "return_to_sender", "abandon"

  - `custom_data.item_data_list` (array)

  - `custom_data.item_data_list.description` (string)
    Description of the item being shipped. Provide accurate and clear details for customs clearance.
    Example: "cloth"

  - `custom_data.item_data_list.quantity` (integer)
    Total number of identical items in this shipment entry.
    Example: 10

  - `custom_data.item_data_list.origin` (string)
    2-letter code for origin country. This field’s value will be an [ISO 3166-1 two-digit code](https://en.wikipedia.org/wiki/ISO_3166-1).
    Example: "US"

  - `custom_data.item_data_list.weight` (number)
    Weight of the item in the selected unit.
    Example: 10

  - `custom_data.item_data_list.unit_cost` (number)
    Declared value of the item in USD. Refers to the unit price of the item.
    Example: 19.99

  - `custom_data.item_data_list.hs_tariff_number` (string)
    Harmonized System (HS) tariff code of the item. [Find My Harmonization Number.](https://uscensus.prod.3ceonline.com/ui/)
    Example: "xx"

  - `insurance_data` (object)

  - `insurance_data.rate_id` (string)
    The unique identifier of an insurance rate returned by the /api/shipment/insurance/rate endpoint. Use this value to purchase insurance for a shipment.
    Example: "dc288147-f7dd-494d-9353-5ce00020c7aa"

  - `label_print_type` (string, 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"

  - `is_return_label` (boolean)
    Indicates whether the label is for a return shipment.

  - `is_exchange_label` (boolean)
    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.

## Response 200 fields (application/json):

  - `code` (string)
    Example: "ok"

  - `msg` (string)
    Example: "ok"

  - `data` (object)

  - `data.zone` (string)
    Example: "1"

  - `data.currency` (string)
    Example: "USD"

  - `data.shipment_no` (string)
    Unique identifier of the created shipment.
    Example: 1222243159

  - `data.tracking_no` (string)
    The carrier-specific tracking number that can be used to track the Shipment. A value will only be returned if the Rate is for a trackable Shipment and if the Transactions has been processed successfully.
    Example: "9234690381085700XXXXX"

  - `data.total_fee` (number)
    Total amount charged (label + insurance, if applicable).
    Example: 39.39

  - `data.label_fee` (number)
    Amount charged for the shipping label.
    Example: 39.39

  - `data.insurance_fee` (number,null)
    Amount charged for insurance; null if not purchased.

  - `data.label_urls` (array)
    List of label file URLs (PNG) for download/printing.
    Example: ["https://xxxxxx.amazonaws.com/labels/2025-08-11/b0dd99909e2e7b03_0.png"]

  - `data.qrcode_urls` (array)
    List of PNG URLs for downloading or printing the QR-code label. Optional field, only used for USPS QR-code labels.
    Example: ["https://xxxxxx.amazonaws.com/labels/2025-08-11/b0dd99909e2e7b03_0.png"]

  - `data.commercial_urls` (array,null)
    List of commercial invoice URLs; null if not applicable.

  - `data.duplicate_label` (boolean,null)
    Example: true

  - `data.label_print_type` (string)
    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"