# Buy Label

Creates and pays for a shipment label using the rate_id obtained from a prior get_rates call. 
This endpoint also allows purchasing shipment insurance in the same request (insurance cannot be purchased separately). 

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/create_and_pay
Version: v2
Security: BearerAuth

## Request fields (application/json):

  - `rate_id` (string, required)
    The unique identifier of a shipping rate returned by the get_rates endpoint. Use this value to reference a specific rate when purchasing a label.
    Example: "dc288147-f7dd-494d-9353-5ce00020c7aa"

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

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