Skip to main content
POST
/
shipping
/
purchase-label
Purchase Shipping Label
curl --request POST \
  --url https://staging-api.puppetvendors.com/shipping/purchase-label \
  --header 'Content-Type: application/json' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "orderNumber": {},
  "vendorId": "<string>",
  "lineItems": [
    "<string>"
  ],
  "service_code": "<string>",
  "shippingCarrier": "<string>",
  "carrierCode": "<string>",
  "length": 123,
  "width": 123,
  "height": 123,
  "weight": 123,
  "weightunit": "<string>",
  "distanceunit": "<string>",
  "to_address": {},
  "from_address": {}
}
'
V2 Preview — This endpoint is part of the V2 API preview. Breaking changes may occur.

​
Overview

Purchase a shipping label for an order after selecting a rate from the Get Shipping Rates 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, plus:
​
orderNumber
string | number
required
The Shopify order number.
​
vendorId
string
required
The vendor’s ID.
​
lineItems
string[]
required
Array of line item IDs to ship. Minimum 1 item.
​
service_code
string
required
The service code from the selected rate (e.g. usps_priority).
​
shippingCarrier
string
required
The shipping carrier provider (e.g. shippo, shipstation).
​
carrierCode
string
Carrier-specific code (e.g. usps, ups, fedex).
​
length
number
Package length. Must be a positive number.
​
width
number
Package width. Must be a positive number.
​
height
number
Package height. Must be a positive number.
​
weight
number
Package weight. Must be a positive number.
​
weightunit
string
Weight unit (e.g. lb, kg, oz, g).
​
distanceunit
string
Distance unit for dimensions (e.g. in, cm).
​
to_address
object
Destination address. See Get Shipping Rates for field details.
​
from_address
object
Origin address. See Get Shipping Rates for field details.

​
Response

200
{
  "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

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 
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"
    }
  }'