batch-shipping — Claude Code skill: bulk labels and setup
batch-shipping is a Claude Code skill that processes CSV shipments through the Shippo API, buys batch labels after approval, and creates end-of-day manifests.
MIT 1 installs ★ 3 updated 2026-10-09
npx skills add goshippo/ai --skill batch-shipping -a claude-codeWhat batch-shipping does
The skill parses a CSV, checks required columns and row fields, then builds a shipment batch in Shippo. It identifies international shipments and prepares customs declarations for them. Before buying labels, the agent reports the shipment count, carrier and service, estimated total, and domestic versus international counts, then waits for explicit approval.
After purchase, the skill retrieves each shipment’s tracking number and label URL through GetTransaction. It can also create a daily PDF manifest with CreateManifest, using a carrier_account, shipment date, and pickup address. Purchases charge the authorized Shippo account, so approval is required. The guide recommends splitting batches above 500 shipments because validation takes longer and individual failures are harder to diagnose.
What it helps with
- validate required CSV fields before creating shipments
- prepare customs declarations for international orders
- purchase labels for an approved shipment batch
- retrieve tracking numbers and individual label URLs
- create a Shippo end-of-day manifest
Example prompts for the agent
- Process
shipments.csvthrough Shippo, validate the rows, and show the estimated cost before asking me to approve label purchases. - Check this Shippo batch for invalid shipments and explain what needs fixing before purchase.
- Create today’s Shippo manifest for these transactions.
How to install batch-shipping
1Skills CLI (Vercel)
npx skills add goshippo/ai --skill batch-shipping -a claude-code2Manually: put the files in place
~/.claude/skills/batch-shipping/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/batch-shipping/
1Skills CLI (Vercel)
npx skills add goshippo/ai --skill batch-shipping -a codex2Manually: put the files in place
.agents/skills/batch-shipping/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add goshippo/ai --skill batch-shipping -a cursor2Manually: put the files in place
.cursor/skills/batch-shipping/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install goshippo/ai skills/batch-shipping2Manually: put the files in place
.github/skills/batch-shipping/SKILL.md1Skills CLI (Vercel)
npx skills add goshippo/ai --skill batch-shipping -a gemini-cli2Platform CLI
gemini skills install https://github.com/goshippo/ai --path skills/batch-shippingManually: put the files in place
.devin/skills/batch-shipping/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add goshippo/ai --skill batch-shipping -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 batch-shipping
How do I install batch-shipping in Claude Code?
Run npx skills add goshippo/ai --skill batch-shipping -a claude-code. The skill file is at ~/.claude/skills/batch-shipping/SKILL.md.
What does batch-shipping do?
It validates CSV shipment data, creates a Shippo batch, and buys labels after the user approves the purchase. It can also retrieve label details and create manifests.
Why does label purchasing need explicit approval?
Purchases charge the authorized Shippo account. Before proceeding, the agent must present shipment counts, carrier and service, estimated cost, and domestic versus international totals.
Source text
SKILL.md · MIT
--- name: batch-shipping description: Process bulk shipments from CSV files, create and purchase batch labels, and generate end-of-day manifests via the Shippo API --- # Batch Shipping ## Purchases Are Live Batch purchases charge the authorized Shippo account for real. Before `PurchaseBatch`, show the shipment count, carrier/service, and estimated total cost, and require explicit user confirmation. --- ## Purchase Confirmation Gate Before every call to `PurchaseBatch`, summarize the following and ask the user for explicit confirmation: - Total number of shipments to be purchased - Carrier and service level (or selection rule if varied) - Estimated total cost - Number of domestic vs international shipments **Do not proceed without explicit user confirmation.** --- ## CSV Batch Processing See `shippo/references/csv-format.md` for the column specification. 1. Read and parse the CSV. Validate required columns are present. Report row count. 2. Validate each row for non-empty required fields. Report invalid rows with reasons. 3. Detect international rows (sender_country != recipient_country). Create customs declarations for those rows. See `shippo/references/customs-guide.md`. Use correct customs enum values: `RETURN_MERCHANDISE` (not `RETURN`) for returned goods, `HUMANITARIAN_DONATION` (not `HUMANITARIAN`) for charitable donations. 4. Build the `batch_shipments` array with inline address and parcel objects per row. 5. Call `CreateBatch` with the array. 6. Poll `GetBatch` until status is `VALID` or `INVALID`. See Polling Intervals below. 7. If the status is `INVALID`, some batch shipments failed validation: see "Fixing an INVALID batch" below, fix them, and re-poll until `VALID`. Report per-shipment failures either way before proceeding. 8. **Confirm purchase** (see Purchase Confirmation Gate above). 9. Call `PurchaseBatch` to buy labels for all valid shipments. 10. Poll `GetBatch` until status changes from `PURCHASING` to `PURCHASED`. See Polling Intervals below. 11. Report: total attempted, succeeded, failed. For successes: tracking_number and label_url (complete URL). For failures: error messages. ### Retrieving batch labels A purchased batch does not put each label URL inline on the batch object. Each entry in `batch_shipments[]` carries a `transaction` field, which is a Transaction object_id. Call `GetTransaction` on it to get that shipment's `label_url` and `tracking_number`. The batch-level `label_url` is a merged multi-label PDF (up to 100 labels per file) and cannot be split per order. ### Batch Size Guidance For batches over 500 shipments, consider splitting into multiple batches. Large batches take longer to validate and purchase, and a single failure can be harder to diagnose. --- ## Polling Intervals - For batches under 100 shipments: poll every 3-5 seconds. - For batches with 100+ shipments: poll every 5-10 seconds. - Report progress to the user every 30 seconds. - Stop after 60 retries and suggest the user check back later using `GetBatch` with the batch object_id. --- ## Batch with Rate Shopping 1. Call `CreateShipment` per shipment to get rate quotes (see Rate Shopping). 2. Present rates. User picks a service level rule (e.g., "cheapest for each" or a specific carrier/service). 3. Build `batch_shipments` with `servicelevel_token` per item. 4. Create, validate, **confirm purchase**, purchase, report as above. --- ## Managing an Existing Batch - Add shipments: `AddShipmentsToBatch` (before purchase only). Note: adding an invalid shipment will change the entire batch status to `INVALID`. Check per-shipment statuses after adding. - Remove shipments: `RemoveShipmentsFromBatch` (before purchase only). --- ## Fixing an INVALID batch If `GetBatch` returns status `INVALID`, one or more batch shipments failed validation and the batch cannot be purchased until they are fixed. 1. **Find the failures.** Call `GetBatch` with `object_results=creation_failed` to return only the failed shipments (paginate with `?page=` if there are many), or read each `batch_shipments[].status` (`VALID` / `INVALID` / `INCOMPLETE` / `TRANSACTION_FAILED`) and its `messages` for the reason. The batch-level `errors` array collects the same per-shipment failures in one place. 2. **Fix them,** either: - Remove: `RemoveShipmentsFromBatch` with the failed batch-shipment `object_id`s (from `batch_shipments[].object_id`, not the shipment object_id) to drop them, or - Correct and re-add: `AddShipmentsToBatch` with corrected shipment objects (fixed address, parcel, or servicelevel). 3. **Re-poll `GetBatch`** until status is `VALID`. 4. Then **confirm purchase** (see Purchase Confirmation Gate) and `PurchaseBatch`. --- ## End-of-Day Manifest 1. Collect: `carrier_account` (object_id), `shipment_date` (YYYY-MM-DD, default today), `address_from` (pickup address). 2. Optionally collect specific transaction object_ids to scope the manifest. You must pass specific transaction object_ids -- there is no auto-include for a date range. 3. Call `CreateManifest`. 4. Poll `GetManifest` until status is `SUCCESS` or `ERROR`. 5. Return the manifest PDF URL(s) and shipment count. --- ## Quick Reference **CSV batch:** Parse CSV -> `CreateCustomsDeclaration` (international rows) -> `CreateBatch` -> poll `GetBatch` -> confirm -> `PurchaseBatch` -> poll `GetBatch` **Manifest:** `CreateManifest` (with transaction object_ids) -> poll `GetManifest`
© goshippo · MIT · goshippo/ai