label-purchase — Claude Code skill: ship labels via Shippo
label-purchase — a skill for creating and purchasing shipping labels through the Shippo API. Handles domestic and international shipments, customs declarations, return labels, and label refunds.
MIT 1 installs ★ 3 updated 2026-10-09
npx skills add goshippo/ai --skill label-purchase -a claude-codeWhat label-purchase does
This skill connects Shippo's API to your code editor and lets you purchase shipping labels programmatically. Before each purchase, it requires explicit user confirmation, displaying the carrier, service level, cost, and delivery timeline. It proceeds only after acknowledgement.
For domestic shipments, the skill validates addresses, creates a shipment, presents available rates for your choice, confirms the purchase, and buys the label. For international shipments, it adds a customs step where you specify content type (merchandise, gift, sample, return, or documents), create a declaration with item details and duty rules, then follow the standard flow. Return labels are generated by swapping the sender and recipient.
The response includes a tracking number and label URL. For S3-hosted labels, the complete URL must be preserved—truncated links break. If the order enters a queue instead of completing instantly, the skill waits for resolution automatically.
What it helps with
- purchase a shipping label for domestic delivery via API
- complete an international shipment with customs paperwork
- generate a return label for a customer
- void and refund a purchased shipping label
- review rates and delivery times before committing to a purchase
Example prompts for the agent
- Generate a label shipping a 500-gram parcel from New York to Los Angeles
- Set up an international shipment of a gift to Germany and let me pick the cheapest option
- Create a return label so the customer can send the item back to our warehouse
How to install label-purchase
1Skills CLI (Vercel)
npx skills add goshippo/ai --skill label-purchase -a claude-code2Manually: put the files in place
~/.claude/skills/label-purchase/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/label-purchase/
1Skills CLI (Vercel)
npx skills add goshippo/ai --skill label-purchase -a codex2Manually: put the files in place
.agents/skills/label-purchase/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add goshippo/ai --skill label-purchase -a cursor2Manually: put the files in place
.cursor/skills/label-purchase/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install goshippo/ai skills/label-purchase2Manually: put the files in place
.github/skills/label-purchase/SKILL.md1Skills CLI (Vercel)
npx skills add goshippo/ai --skill label-purchase -a gemini-cli2Platform CLI
gemini skills install https://github.com/goshippo/ai --path skills/label-purchaseManually: put the files in place
.devin/skills/label-purchase/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add goshippo/ai --skill label-purchase -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about label-purchase
How do I install label-purchase in Claude Code?
Run npx skills add goshippo/ai --skill label-purchase -a claude-code. After installation, check ~/.claude/skills/label-purchase/SKILL.md to verify the setup.
What does the label-purchase skill do?
It lets you purchase shipping labels through Shippo's API directly from your code editor. You can handle domestic and international shipments, manage customs declarations, create return labels, and cancel purchases for a refund.
Do I need a Shippo account?
Yes, the skill works with your Shippo account and charges it for each label purchased. Every purchase requires your explicit confirmation first.
Source text
SKILL.md · MIT
---
name: label-purchase
description: Purchase domestic and international shipping labels, handle customs declarations, return labels, and void/refund labels via the Shippo API
---
# Label Purchase
## Purchases Are Live
Label purchases charge the authorized Shippo account for real. **Before purchasing, explicitly state "this will charge your Shippo account" with the carrier, service, and cost, and require the user to acknowledge.** Do not purchase without that confirmation.
---
## Purchase Confirmation Gate
Before every call to `CreateTransaction`, summarize the following and ask the user for explicit confirmation:
- Carrier and service level
- Estimated cost
- Estimated delivery time
- Origin and destination
**Do not proceed without explicit user confirmation.**
---
## Domestic Label
1. Optionally validate both addresses with `ValidateAddress` (see Address Validation).
2. Call `CreateShipment` with `address_from`, `address_to` (as inline address objects using v1 field names -- `street1`, `city`, `state`, `zip`, `country`), `parcels`, and `async: false`.
3. Present rates to the user. Let them choose.
4. **Confirm purchase** (see Purchase Confirmation Gate above).
5. Call `CreateTransaction` with: `rate` (selected rate object_id), `label_file_type` (default `PDF_4x6`), `async: false`.
6. Check response `status`:
- `SUCCESS`: return `tracking_number`, `label_url` (display the COMPLETE URL -- S3 signed URLs break if truncated), and `tracking_url_provider`.
- `QUEUED`/`WAITING`: poll `GetTransaction` until resolved.
- `ERROR`: report messages from the `messages` array.
---
## International Label
All domestic steps apply, plus customs handling before shipment creation. See `shippo/references/customs-guide.md` for the full customs workflow.
1. Optionally validate addresses with `ValidateAddress`. Sender must include `email` and `phone`. Ask if missing.
2. Create customs items: call `CreateCustomsItem` per item (description, quantity, net_weight, mass_unit, value_amount, value_currency, origin_country, tariff_number). Alternatively, you can skip this step and pass inline item objects directly in the declaration (step 3).
3. Create the customs declaration: call `CreateCustomsDeclaration` with contents_type, non_delivery_option, certify: true, certify_signer, and the items (either object_ids from step 2, or inline item objects). See `shippo/references/customs-guide.md` for field details.
4. Call `CreateShipment` with all standard fields plus `customs_declaration` (the declaration object_id).
5. Present rates, **confirm purchase** (see Purchase Confirmation Gate), then purchase label and return results as in the domestic flow.
### Contents Type Decision Tree
Use this to determine the correct `contents_type` value:
| Scenario | Value |
|---|---|
| Selling to the recipient (commercial sale) | `MERCHANDISE` |
| Sending a free gift | `GIFT` |
| Sending a product sample | `SAMPLE` |
| Paper documents only | `DOCUMENTS` |
| Customer returning a purchased item | `RETURN_MERCHANDISE` |
| Charitable donation | `HUMANITARIAN_DONATION` |
| None of the above | `OTHER` (requires `contents_explanation`) |
### Incoterms Decision Logic
The `incoterm` field on the customs declaration controls who pays duties and taxes:
- **B2C / e-commerce (default):** Use `DDU` (Delivered Duty Unpaid) -- recipient pays duties at delivery.
- **Seller prepays duties:** Use `DDP` (Delivered Duty Paid) -- seller covers all duties and taxes.
- **FedEx/DHL only:** `FCA` (Free Carrier) is available for advanced trade scenarios.
If the user does not specify, default to `DDU` for standard e-commerce shipments.
---
## Return Labels
To generate a return label, swap `address_from` and `address_to` so the original recipient becomes the sender and the original sender becomes the recipient. All other steps (shipment creation, rate selection, label purchase) remain the same.
---
## Label Format Options
Default to `PDF_4x6` unless the user specifies otherwise. Supported formats: `PDF_4x6`, `PDF_4x8`, `PDF_A4`, `PDF_A5`, `PDF_A6`, `PDF`, `PDF_2.3x7.5`, `PNG`, `PNG_2.3x7.5`, `ZPLII`.
---
## Label Customization Options
When purchasing a label via `CreateTransaction`, the following options may be set on the shipment or rate:
- **Signature confirmation**: set `signature_confirmation` on the shipment's `extra` field. Values: `STANDARD`, `ADULT`, `CERTIFIED`, `INDIRECT`, `CARRIER_CONFIRMATION`.
- **Insurance**: set `insurance` on the shipment's `extra` field with `amount`, `currency`, and `provider`.
- **Saturday delivery**: set `saturday_delivery` to `true` in the shipment's `extra` field. Only supported by certain carriers and service levels.
- **Reference fields**: pass `metadata` on the transaction for order numbers or internal references.
---
## Label from Existing Rate
If the user already has a rate object_id: optionally call `GetRate` to confirm details, then **confirm purchase** (see Purchase Confirmation Gate), then call `CreateTransaction` directly.
---
## Voiding a Label
Call `CreateRefund` with the transaction object_id.
**Refund limitations:** Void/refund eligibility depends on carrier and timing. Not all labels can be refunded after purchase. If `CreateRefund` fails, advise the user to contact Shippo support.
---
## Quick Reference
**Domestic label:**
(optional) `ValidateAddress` (x2) -> `CreateShipment` (with inline addresses) -> user picks rate -> confirm -> `CreateTransaction`
**International label:**
(optional) `ValidateAddress` (x2) -> `CreateCustomsItem` (per item) -> `CreateCustomsDeclaration` -> `CreateShipment` (with inline addresses + customs_declaration) -> user picks rate -> confirm -> `CreateTransaction`
**Return label:**
Same as domestic/international, but swap `address_from` and `address_to`.
**Order-to-label:**
`CreateOrder` -> `CreateShipment` (using order address/item data) -> user picks rate -> confirm -> `CreateTransaction` -> packing slip (REST fallback, see below)
---
## Orders and Packing Slips
Use orders to represent e-commerce fulfillment requests. An order captures the shipping address, line items, and totals -- then feeds into the standard label purchase workflow.
### Tools
- **`CreateOrder`**: Create an order with line items, shipping address, and order details.
- **`GetOrder`**: Retrieve an order by its object_id.
- **`ListOrders`**: List all orders.
- **Packing slip (known gap):** Generate a packing slip PDF for an order. There is no packing-slip tool in the MCP catalog. The underlying REST endpoint exists at `GET /orders/{ORDER_ID}/packingslip/` (returns a 24-hour S3 PDF link). Fall back to a direct REST call, or advise the user to use the Shippo dashboard until the MCP gap is closed.
### Workflow
1. Call `CreateOrder` with the shipping address, line items (title, quantity, sku, total_price, etc.), and order-level fields.
2. Use the order's address and item data to call `CreateShipment`, then follow the standard label purchase flow (rate selection, confirmation, `CreateTransaction`).
3. After purchasing the label, generate a packing slip via the REST fallback (see Tools above for the known MCP gap).
© goshippo · MIT · goshippo/ai