# Directly Buy Label

Purchases a shipping label directly without comparing multiple carrier options. This endpoint is applicable only when there is a single carrier configured for each carrier type in the user's account. If multiple carriers of the same type exist, use the Get Rate API to retrieve options, then call the Buy Label API to complete the purchase.  Rate limit: 600 requests per minute.

Endpoint: POST /api/rates/buy-label
Version: v1
Security: ApiTokenAuth

## Request fields (application/json):

  - `request_id` (string)
    Unique identifier for this API request. Used for tracking, debugging, and issue resolution. Must be a string up to 64 characters.
    Example: "req_20251024_abcd1234ef567890"

  - `carrier` (object)
    Carrier information

  - `carrier.carrier_token` (string)
    Please refer to your ShipSaving account Carrier Accounts -> Token
    Example: "ca_36f49ebbe91d4006a6583e17ceeec500"

  - `from` (object, required)
    Shipper's address

  - `from.name` (string, required)
    Example: "full name"

  - `from.company` (string)
    Example: "company name"

  - `from.email` (string)
    Example: "xxx@gmail.com"

  - `from.phone` (string)
    Shipper's phone number. Required for international shipments.
    Example: 1237771234

  - `from.street` (string, required)
    Example: "xxx Grand Ave"

  - `from.street2` (string)
    Optional secondary address line (e.g., Apt, Suite, Unit, Floor).
    Example: "Apt 5B"

  - `from.city` (string, required)
    Example: "Los Angeles"

  - `from.state` (string, required)
    Example: "CA"

  - `from.zip` (string, required)
    Example: 90018

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

  - `to` (object, required)
    Recipient's address

  - `to.phone` (string)
    Recipient's phone number. Required for international shipments.
    Example: 1237771234

  - `to.residential` (boolean)
    Specifies if the address is residential, which can impact the quoted shipping rate.
    Example: true

  - `shipments` (array, required)
    List of shipments

  - `shipments.length` (number, required)
    Package length (inch)
    Example: 6

  - `shipments.width` (number, required)
    Package width (inch)
    Example: 6

  - `shipments.height` (number, required)
    Package height (inch)
    Example: 6

  - `shipments.weight` (number, required)
    Package weight (pound)
    Example: 1

  - `shipments.packages` (array)
    This field accepts carrier predefined packages.  Please refer to the [Predefined Carrier Packages Table](appendix.md) for supported values.
    Example: ["usps_small_flat_rate_box"]

  - `shipments.insurance_amount` (number)
    Amount for insured shipment. Must be used in conjunction with insurance_provider.
    Example: 120

  - `shipments.custom_print1` (string)
    Customized print on label.If the label itself supports custom printing content, this field will be printed onto the label.
    Example: "custom print1"

  - `shipments.custom_print2` (string)
    Customized print on label.If the label itself supports custom printing content, this field will be printed onto the label.
    Example: "custom print2"

  - `shipments.contents` (array)
    List of items filed for customs (*required for international)

  - `shipments.contents.weight` (number, required)
    Weight of the item in lbs.
    Example: 1

  - `shipments.contents.description` (string, required)
    Description of the item being shipped. Provide accurate and clear details for customs clearance.
    Example: "T-shirt"

  - `shipments.contents.quantity` (integer, required)
    Total number of identical items in this shipment entry.
    Example: 2

  - `shipments.contents.value` (number, required)
    Declared value of the item in USD.
    Example: 29.99

  - `shipments.contents.hs_tariff_number` (string)
    Harmonized System (HS) tariff code of the item.
    Example: "610910"

  - `shipments.contents.origin_country` (string, required)
    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"

  - `order` (object)
    Order information

  - `order.warehouse_name` (string, required)
    Pre-existing warehouse name in ShipSaving system. (Please refer to your ShipSaving account Warehouses -> Name)
    Example: "WH"

  - `order.store_name` (string)
    Pre-existing store name in ShipSaving system. (Please refer to your ShipSaving account Stores -> Stores Nickname. If you use order_number, then the store_name of the order is required)

  - `order.order_number` (string)
    Pre-existing order number in ShipSaving system. If you need to check label price or buy a label for an order which already existed in our system, then this field is required.

  - `order.status` (string)
    Used with order_number; sets order status (awaiting, hold, or shipped) after label purchase. Defaults to awaiting if omitted.
    Enum: "awaiting", "hold", "shipped"

  - `order.service_type` (string)
    Please refer to the [Carrier Service Types Table](appendix.md) for supported values.
    Example: "usps_ground_advantage"

  - `order.signature` (string)
    Enum: "NO_SIGNATURE", "SIGNATURE", "ADULT_SIGNATURE"

  - `order.insurance_provider` (string)
    Used with the field insurance_amount.
    Enum: "SHIPSURANCE", "CARRIER"

  - `order.contents_type` (string)
    Enum: "GIFT", "MERCHANDISE", "SAMPLE", "RETURNED_GOODS", "DOCUMENTS"

  - `order.non_delivery_option` (string)
    Defines the action to take for undeliverable shipments.
    Enum: "RETURN", "ABANDON"

  - `order.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"

  - `order.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.
    Example: "X20250627012345"

  - `order.tax_ids` (array)
    recipient‘s taxid

  - `order.tax_ids.tax_id_type` (string)
    Enum: "TIN", "EIN", "SSN", "VAT", "EORI", "IOSS", "PAN", "VOEC"

  - `order.tax_ids.tax_id_number` (string)
    The value corresponding to the tax ID type

  - `order.tax_ids.tax_id_country` (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"

  - `options` (object)
    Additional shipping options

  - `options.ship_date` (string)
    Timestamp in ISO 8601 format, including local time and time zone offset.
    Example: "2024-02-07T10:55:56-08:00"

  - `options.require_saturday_delivery` (boolean)
    Whether this shipment requires Saturday delivery

  - `options.require_hazmat` (boolean)
    Whether this shipment contains dangerous goods or hazardous materials (USPS Ground Advantage service only). View [tutorial](https://www.uspsdelivers.com/hazmat-shipping-safety/) about how to package, label and ship HAZMAT for domestic shipments.

  - `options.hazmat_code` (string)
    Specifies the type of hazardous material for DHL eCommerce shipments. This parameter must be used in conjunction with options.require_hazmat to take effect.
    Enum: "dhlecs_lithium_metal_alloy_contained", "dhlecs_lithium_metal_alloy_packed", "dhlecs_lithium_metal_alloy_standalone", "dhlecs_lithium_ion_contained", "dhlecs_lithium_ion_packed", "dhlecs_lithium_ion_standalone", "dhlecs_limited_quantity", "dhlecs_small_quantity_provision", "dhlecs_limited_quantities_plt"

  - `options.label_type` (string)
    The possible values are "pdf" or "png". If this parameter is not provided, the default value is "png".
    Enum: "png", "pdf"

  - `options.require_qr_code` (boolean)
    Indicates whether the shipping label should be generated as a normal label, QR code or barcode.   Set to true to request a paperless label (e.g., QR code or barcode).   Note: Availability of paperless labels depends on the carrier's support.

  - `recipient_tax_ids` (array)
    Recipient's tax information

  - `recipient_tax_ids.tax_id_number` (string)
    recipient_tax_ids parameter

## Response 200 fields (application/json):

  - `packing_slip_number` (integer)
    Example: 109169

  - `master_tracking_code` (string)

  - `prefix_tracking_code` (string)

  - `tracking_code` (string)
    Example: "1ZY50G652000880500"

  - `label_size` (string)
    Example: "4x6"

  - `label_type` (string)
    Example: "label"

  - `length` (number)
    Example: 12

  - `width` (number)
    Example: 12

  - `height` (number)
    Example: 7

  - `weight` (number)
    Example: 14.99

  - `insurance` (number)

  - `insurance_fee` (number)

  - `signature` (string)
    Example: "NO_SIGNATURE"

  - `custom_print1` (string)

  - `custom_print2` (string)

  - `delivery_days` (string)
    Example: "1"

  - `service_fee` (number)
    Example: 0.05

  - `rate` (number)
    Example: 10.87

  - `rebate` (number)

  - `from_name` (string)
    Sender's name
    Example: "sender name"

  - `from_company` (string)
    Sender's company
    Example: "ShipSaving, LLC"

  - `from_phone` (string)
    Sender's phone

  - `from_street` (string)
    Sender's address line 1
    Example: "769 Broadview Avenue"

  - `from_street2` (string)
    Sender's address line 2

  - `from_city` (string)
    Sender's city
    Example: "Toronto"

  - `from_state` (string)
    Sender's state or province
    Example: "ON"

  - `from_zip` (string)
    Sender's postal code
    Example: "M4K 2P7"

  - `from_country` (string)
    Sender's country code
    Example: "CA"

  - `to_name` (string)
    Recipient's name
    Example: "ShipSaving"

  - `to_company` (string)
    Recipient's company
    Example: "UPS Plus"

  - `to_phone` (string)
    Recipient's phone

  - `to_street` (string)
    Recipient's address line 1
    Example: "961 Broadview Avenue"

  - `to_street2` (string)
    Recipient's address line 2

  - `to_city` (string)
    Recipient's city
    Example: "Toronto"

  - `to_state` (string)
    Recipient's state or province
    Example: "ON"

  - `to_zip` (string)
    Recipient's postal code
    Example: "M4K 2P7"

  - `to_country` (string)
    Recipient's country code
    Example: "CA"

  - `label_status` (string)
    Example: "completed"

  - `shipment_id` (integer)
    Example: 1245627

  - `warehouse_name` (string)
    Example: "WH"

  - `store_name` (string)

  - `order_number` (string)

  - `provider` (string)
    Example: "shipsaving"

  - `carrier` (string)
    Example: "UPS"

  - `service` (string)
    Example: "UPS_GROUND"

  - `package` (string)
    Example: "PACKAGE"

  - `published_rate` (number)
    Example: 34.53

  - `label_url` (array)
    Example: ["https://...../labels/2025-06-30/0231b055b64044e6b7e027874e915361_0.pdf"]

  - `commercial_invoice_url` (string,null)