Skip to main content
skill CX Codex

rate-shopping — Claude Code skill: what it does, how to install

rate-shopping compares multi-carrier shipping rates via the Shippo API, filters services by delivery speed, and finds the best value option.

MIT 1 installs ★ 3 updated 2026-10-09

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add goshippo/ai --skill rate-shopping -a claude-code
Open on GitHub

What rate-shopping does

This skill guides coding assistants to prepare shipment details and query the Shippo API using CreateShipment or CreateLiveRate. Parcel dimensions and weights must be supplied strictly as string values (such as "10" instead of integers), preventing payload formatting errors. The model presents carrier rates in a clean table displaying carrier names, service tiers, prices, and transit days.

API responses do not label the best deal automatically. The assistant sorts the rates array directly to spot the cheapest quote, shortest transit window, and practical trade-offs. Duplicate options from multiple linked carrier accounts are filtered to show only the best rate per service. For international shipments, the logic checks for customs declarations and mandatory recipient phone numbers.

Retrieved rates expire strictly after 7 days. Attempting to purchase a shipping label past that window requires initiating a new shipment to get valid pricing.

What it helps with

  • compare shipping rates across carriers for a single package
  • filter carrier quotes by delivery window or overnight priority
  • calculate cart checkout shipping via CreateLiveRate
  • convert shipment quotes to a specific ISO currency code

Example prompts for the agent

  • Find the cheapest shipping option for a "12"x"8"x"6" box weighing "4" lbs from Seattle to Boston.
  • Show overnight and 2-day delivery options for this destination address.
  • Get checkout shipping rates in EUR for these line items using CreateLiveRate.

How to install rate-shopping

1Skills CLI (Vercel)

npx skills add goshippo/ai --skill rate-shopping -a claude-code

2Manually: put the files in place

~/.claude/skills/rate-shopping/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/rate-shopping/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about rate-shopping

How to install rate-shopping in Claude Code?

Run npx skills add goshippo/ai --skill rate-shopping -a claude-code in your terminal.

What does the rate-shopping skill do?

It teaches AI assistants how to query the Shippo API, validate addresses, and compare multi-carrier freight options based on price and transit time.

Why must dimensions and weights be formatted as strings?

The Shippo API rate endpoint expects dimension and weight properties wrapped in quotes, such as "10", rather than raw numbers.

Source text

SKILL.md · MIT
---
name: rate-shopping
description: Compare multi-carrier shipping rates, find cheapest/fastest options, and get shipping recommendations via the Shippo API
---

# Rate Shopping and Comparison

## Get Rates for a Shipment

1. Collect: origin address, destination address, parcel (length, width, height, distance_unit, weight, mass_unit). All dimension and weight values must be **strings** (e.g., `"10"` not `10`).
2. Optionally validate both addresses with `ValidateAddress` (see Address Validation).
3. Call `CreateShipment` with `address_from`, `address_to` (as inline address objects using v1 field names -- `street1`, `city`, `state`, `zip`, `country` -- not object IDs), and `parcels`.
4. The response `rates` array contains available options. Present a table: carrier, service level, price, estimated days.
5. Note: the same carrier may return duplicate rates from multiple carrier accounts. Present the best rate per carrier/service combination.
6. Each rate carries an `object_id`. To buy a label, pass the chosen rate's `object_id` to the purchase flow (see Label Purchase); you do not re-send the address or parcel.

---

## Rate Expiration

Rates expire after 7 days. If a user tries to purchase a rate that was retrieved more than 7 days ago, create a new shipment to get fresh rates.

---

## Filter by Speed

Map user requests: "overnight" = estimated_days 1, "2-day" = estimated_days <= 2, "within N days" = estimated_days <= N. Filter the rates array accordingly. If nothing matches, show the fastest available option.

---

## International Rates

Some carriers may return international rates without a customs declaration, but others will not. If no rates are returned, try attaching a customs declaration to the shipment. Some carriers also require a phone number on the destination address for international rate retrieval. Inform the user that customs will be required at label purchase time regardless. See `shippo/references/customs-guide.md` for customs details.

---

## Checkout Rates (Line Items)

Call `CreateLiveRate` instead of `CreateShipment`. Accepts `address_from`, `address_to`, and `line_items` (each with title, quantity, total_price, currency, weight, weight_unit).

---

## Rates in a Specific Currency

Call `ListShipmentRatesByCurrencyCode` with the preferred ISO currency code (USD, EUR, GBP, CAD, etc.).

---

## Recommendation

Identify the cheapest (lowest `amount`), fastest (lowest `estimated_days`), and best-value options from the rates array. These are not API fields -- compute them by sorting the rates array yourself. State the trade-off: "Option A is $X cheaper but takes Y more days than Option B."

---

## Troubleshooting: No Rates

- Verify both addresses passed validation (most common cause).
- Confirm parcel dimensions are reasonable (not zero, not exceeding carrier limits).
- Shippo provides managed carrier accounts by default for major carriers. If no rates are returned, the issue is more likely address validation, unsupported route, or parcel dimensions -- not missing carrier accounts. You can verify with `ListCarrierAccounts` if needed.
- Rates expire after 7 days. If stale, create a new shipment to get fresh rates.

---

## Quick Reference

**Get rates:**
(optional) `ValidateAddress` (x2) -> `CreateShipment` (with inline addresses) -> read `rates` array

© goshippo · MIT · goshippo/ai

Similar skills

All skills for Backend and APIs →

From the same set6

Project sponsors

Companies that keep this analytics open