> ## Documentation Index
> Fetch the complete documentation index at: https://dev.puppetvendors.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Purchase Shipping Label

> Purchase a shipping label for an order using a selected rate

<Note>
  **V2 Preview** — This endpoint is part of the V2 API preview. Breaking changes may occur.
</Note>

## Overview

Purchase a shipping label for an order after selecting a rate from the [Get Shipping Rates](/api-reference/v2/vendor/endpoint/get-shipping-rates-op) endpoint. Provide the same shipment details plus the chosen service code and carrier.

### Use Cases

* Purchase a label after a vendor selects a rate
* Automate label generation in fulfillment workflows
* Integrate carrier label purchase into custom shipping UIs

## Request Body

Accepts the same fields as [Get Shipping Rates](/api-reference/v2/vendor/endpoint/get-shipping-rates-op), plus:

<ParamField body="orderNumber" type="string | number" required>
  The Shopify order number.
</ParamField>

<ParamField body="vendorId" type="string" required>
  The vendor's ID.
</ParamField>

<ParamField body="lineItems" type="string[]" required>
  Array of line item IDs to ship. Minimum 1 item.
</ParamField>

<ParamField body="service_code" type="string" required>
  The service code from the selected rate (e.g. `usps_priority`).
</ParamField>

<ParamField body="shippingCarrier" type="string" required>
  The shipping carrier provider (e.g. `shippo`, `shipstation`).
</ParamField>

<ParamField body="carrierCode" type="string">
  Carrier-specific code (e.g. `usps`, `ups`, `fedex`).
</ParamField>

<ParamField body="length" type="number">
  Package length. Must be a positive number.
</ParamField>

<ParamField body="width" type="number">
  Package width. Must be a positive number.
</ParamField>

<ParamField body="height" type="number">
  Package height. Must be a positive number.
</ParamField>

<ParamField body="weight" type="number">
  Package weight. Must be a positive number.
</ParamField>

<ParamField body="weightunit" type="string">
  Weight unit (e.g. `lb`, `kg`, `oz`, `g`).
</ParamField>

<ParamField body="distanceunit" type="string">
  Distance unit for dimensions (e.g. `in`, `cm`).
</ParamField>

<ParamField body="to_address" type="object">
  Destination address. See [Get Shipping Rates](/api-reference/v2/vendor/endpoint/get-shipping-rates-op) for field details.
</ParamField>

<ParamField body="from_address" type="object">
  Origin address. See [Get Shipping Rates](/api-reference/v2/vendor/endpoint/get-shipping-rates-op) for field details.
</ParamField>

## Response

```json 200 theme={null}
{
  "success": true,
  "data": {
    "trackingNumber": "9400111899223456789012",
    "trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223456789012",
    "labelUrl": "https://deliver.goshippo.com/label_abc123.pdf",
    "carrier": "USPS"
  }
}
```

## Example

```bash theme={null}
curl -X POST "https://staging-api.puppetvendors.com/shipping/purchase-label" \
  -H "x-access-token: YOUR_VENDOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderNumber": "1042",
    "vendorId": "507f1f77bcf86cd799439011",
    "lineItems": ["660a1b2e3d98f0001a2b3c01"],
    "service_code": "usps_priority",
    "shippingCarrier": "shippo",
    "carrierCode": "usps",
    "length": 12,
    "width": 8,
    "height": 6,
    "weight": 2.5,
    "weightunit": "lb",
    "distanceunit": "in",
    "to_address": {
      "street1": "456 Oak Ave",
      "city": "Portland",
      "state": "OR",
      "zip": "97201",
      "country": "US"
    },
    "from_address": {
      "street1": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "country": "US"
    }
  }'
```

### More Examples

**Purchase a USPS Priority Mail label**

```bash theme={null}
curl -X POST "https://staging-api.puppetvendors.com/shipping/purchase-label" \
  -H "x-access-token: YOUR_VENDOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderNumber": "1055",
    "vendorId": "507f1f77bcf86cd799439012",
    "lineItems": ["665a1b2c3d4e5f6a7b8c9d0e"],
    "length": 12,
    "width": 8,
    "height": 6,
    "weight": 2.5,
    "weightunit": "lb",
    "distanceunit": "in",
    "service_code": "usps_priority",
    "shippingCarrier": "USPS",
    "from_address": {
      "street1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "country": "US",
      "zip": "10001"
    },
    "to_address": {
      "street1": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "country": "US",
      "zip": "90001"
    }
  }'
```