> ## 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.

# Get Shipping Rates for Order

> Fetch real-time shipping rates for an order's line items

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

## Overview

Fetch real-time shipping rates from connected carriers for a specific set of line items. Provide package dimensions, weight, and origin/destination addresses to receive available rates with pricing and estimated delivery times.

### Use Cases

* Show rate options to vendors before purchasing a label
* Compare carrier pricing for a shipment
* Integrate shipping rate selection into custom fulfillment workflows

## Request Body

<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="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.
</ParamField>

<ParamField body="to_address.street1" type="string">
  Street address line 1.
</ParamField>

<ParamField body="to_address.street2" type="string">
  Street address line 2.
</ParamField>

<ParamField body="to_address.country" type="string">
  Country code (e.g. `US`, `GB`).
</ParamField>

<ParamField body="to_address.zip" type="string">
  Postal / ZIP code.
</ParamField>

<ParamField body="to_address.city" type="string">
  City name.
</ParamField>

<ParamField body="to_address.phone" type="string">
  Phone number.
</ParamField>

<ParamField body="to_address.state" type="string">
  State or province.
</ParamField>

<ParamField body="to_address.name" type="string">
  Recipient name.
</ParamField>

<ParamField body="to_address.email" type="string">
  Recipient email.
</ParamField>

<ParamField body="from_address" type="object">
  Origin address. Same fields as `to_address`.
</ParamField>

<ParamField body="from_address.street1" type="string">
  Street address line 1.
</ParamField>

<ParamField body="from_address.street2" type="string">
  Street address line 2.
</ParamField>

<ParamField body="from_address.country" type="string">
  Country code.
</ParamField>

<ParamField body="from_address.zip" type="string">
  Postal / ZIP code.
</ParamField>

<ParamField body="from_address.city" type="string">
  City name.
</ParamField>

<ParamField body="from_address.phone" type="string">
  Phone number.
</ParamField>

<ParamField body="from_address.state" type="string">
  State or province.
</ParamField>

<ParamField body="from_address.name" type="string">
  Sender name.
</ParamField>

<ParamField body="from_address.email" type="string">
  Sender email.
</ParamField>

## Response

```json 200 theme={null}
{
  "success": true,
  "data": {
    "rates": [
      {
        "provider": "shippo",
        "service": "usps_priority",
        "serviceName": "USPS Priority Mail",
        "amount": 7.49,
        "currency": "USD",
        "estimatedDays": 3,
        "carrierCode": "usps"
      },
      {
        "provider": "shippo",
        "service": "ups_ground",
        "serviceName": "UPS Ground",
        "amount": 9.15,
        "currency": "USD",
        "estimatedDays": 5,
        "carrierCode": "ups"
      }
    ]
  }
}
```

## Example

```bash theme={null}
curl -X POST "https://staging-api.puppetvendors.com/shipping/get-rates" \
  -H "x-access-token: YOUR_VENDOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderNumber": "1042",
    "vendorId": "507f1f77bcf86cd799439011",
    "lineItems": ["660a1b2e3d98f0001a2b3c01"],
    "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

**International shipment rates**

```bash theme={null}
curl -X POST "https://staging-api.puppetvendors.com/shipping/get-rates" \
  -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",
    "from_address": {
      "street1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "country": "US",
      "zip": "10001"
    },
    "to_address": {
      "street1": "10 Downing St",
      "city": "London",
      "country": "GB",
      "zip": "SW1A 2AA"
    }
  }'
```