atoship

# atoship — Your AI Shipping Manager Imagine having a shipping manager who never sleeps, never makes data entry errors, and instantly knows the cheapest way to get your package from A to B. That's what atoship does for your AI assistant. With this skill installed, your AI becomes a fully capable shipping manager. Just tell it what you need in plain language — it handles carrier selection, rate comparison, label purchase, and tracking updates automatically. What used to take 10 minutes of clicking through carrier portals now takes one sentence. **Before atoship:** Open carrier website → enter addresses → compare rates across tabs → copy-paste tracking numbers → manually update order status. **After atoship:** *"Ship this order to John in Austin, cheapest option under 3 days."* Done. ## What you can do - **Compare shipping rates** — Get live, discounted postage rates from USPS, FedEx, and UPS side by side in seconds - **Buy shipping labels** — Purchase labels instantly at checkout; PDF, PNG, or ZPL formats supported - **Track shipments** — Real-time package tracking with full event history for any carrier - **Manage labels** — View, void, and reprint past shipping labels - **Check wallet balance** — Monitor your postage credit and shipping spend - **Validate addresses** — Verify delivery addresses before purchasing to avoid surcharges ## Getting started This is an instruction-only skill — no CLI or additional software required. Your AI assistant calls the atoship API directly using your API key. **Step 1: Create a free atoship account** Sign up at https://atoship.com (free, no credit card required to start). **Step 2: Get your API key** Go to Dashboard → Settings → API Keys and create a new key. **Step 3: Set your API key** ```bash export ATOSHIP_API_KEY=ak_live_your_key_here ``` Or configure it in your AI assistant's environment settings. **Step 4: Add funds to your wallet** Go to Dashboard → Billing to add postage credit. Labels are deducted from your wallet balance — you only pay for what you ship. > **Note on permissions:** Your API key authorizes label purchases and wallet charges. We recommend: > - Start with a small wallet balance (e.g. $20) while evaluating > - Use a test/sandbox key (`ak_test_...`) for development — test labels are free and never shipped > - Set spending alerts in Dashboard → Billing → Notifications > - Revoke and rotate keys at any time from Dashboard → Settings → API Keys ## How to use this skill Type `/atoship` and describe what you need. Examples: - *"How much does it cost to ship a 2lb box from Los Angeles to New York?"* - *"Buy a USPS Priority Mail label from 90001 to 10001, 1lb"* - *"Track my package: 9400111899223456789012"* - *"Show my recent shipping labels"* - *"What's my account balance?"* ## Shipping workflow ### Step 1 — Compare rates I'll call the atoship API to get live rates from all carriers: ``` From: ZIP code or "City, State" To: ZIP code or "City, State" Weight: e.g. 2oz, 1lb, 500g Dimensions (optional): length × width × height in inches ``` Results show each carrier's services, prices, and estimated delivery times. USPS, FedEx Ground, FedEx Express, UPS Ground, UPS 2-Day, and more. ### Step 2 — Buy a label > **IMPORTANT**: Always show the user the carrier, service, price, and full addresses, then ask for explicit confirmation (e.g. "Confirm purchase?") before calling the purchase API. Never purchase a label without user approval — this action charges their wallet. Once you pick a service, I'll collect the full addresses and purchase the label: ``` Sender: Name, Street, City, State, ZIP Recipient: Name, Street, City, State, ZIP ``` You'll get: - ✅ Tracking number - ✅ Label download link (PDF or PNG) - ✅ Cost deducted from your wallet Labels can be voided for a refund if unused within the carrier's void window (usually 28 days for USPS, 1 day for FedEx/UPS). ### Step 3 — Track a package Give me a tracking number and I'll show the full event history: ``` Status: IN TRANSIT Location: Memphis, TN ETA: Feb 19, 2026 Events: Feb 17 10:42 — Departed facility, Memphis TN Feb 17 06:15 — Arrived at USPS facility Feb 16 18:30 — Accepted at origin post office ``` ## Supported carriers | Carrier | Rates | Labels | Tracking | |---------|-------|--------|---------| | USPS | ✅ | ✅ | ✅ | | FedEx | ✅ | ✅ | ✅ | | UPS | ✅ | ✅ | ✅ | ## Common use cases **E-commerce order fulfillment** — Ship Shopify, eBay, Etsy, or Amazon orders without switching tabs. Automatically find the cheapest carrier for each order. **Small business shipping** — Compare USPS First Class vs Priority Mail vs FedEx Ground vs UPS Ground for any package size and weight. Save money on every shipment. **Dropshipping & 3PL logistics** — Integrate atoship's API into your fulfillment workflow. Generate labels programmatically and track shipments in bulk. **International shipping** — atoship supports cross-border shipping to Canada, UK, Australia, and 200+ countries via USPS International, FedEx International, and UPS Worldwide. **Returns management** — Generate prepaid return labels for customer returns with a single command. **Bulk shipping** — Use the atoship dashboard at https://atoship.com for CSV import and batch label generation. ## Tips - **Cheapest rate**: Ask "what's the cheapest way to ship X?" - **Weight units**: oz, lb, g, kg all supported - **Label formats**: PDF (default), PNG, ZPL for thermal printers - **Signature required**: Add "with signature confirmation" when buying - **Insurance**: Add "with $100 insurance" when buying - **Reference number**: Add "reference ORDER-123" to tag your label ## API Endpoint Reference Base URL: `https://atoship.com` All requests require `Authorization: Bearer YOUR_API_KEY` header. | Action | Method | Endpoint | Description | |--------|--------|----------|-------------| | Get rates | POST | `/api/v1/rates` | Compare shipping rates across carriers | | Create label | POST | `/api/v1/labels` | Create a draft shipping label | | Purchase label | POST | `/api/v1/labels/{id}/purchase` | Purchase a draft label | | Get label | GET | `/api/v1/labels/{id}` | Get label details by ID | | List labels | GET | `/api/v1/labels` | List labels with optional filters | | Void label | DELETE | `/api/v1/labels/{id}` | Void/cancel an unused label | | Track package | GET | `/api/v1/tracking/{tracking_number}` | Track a package by tracking number | | Validate address | POST | `/api/v1/addresses/validate` | Validate a shipping address | | Create order | POST | `/api/v1/orders` | Create a new order | | Get order | GET | `/api/v1/orders/{id}` | Get order details by ID | | List orders | GET | `/api/v1/orders` | List orders with optional filters | | Get account | GET | `/api/v1/account` | Get account info and balance | | List carriers | GET | `/api/v1/carrier-accounts` | List configured carrier accounts | ### Example: Track a package ```bash curl -X GET "https://atoship.com/api/v1/tracking/9400111899223456789012" \ -H "Authorization: Bearer ak_live_your_key_here" ``` ### Example: Get shipping rates ```bash curl -X POST "https://atoship.com/api/v1/rates" \ -H "Authorization: Bearer ak_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "from_address": {"name": "Sender", "street1": "123 Main St", "city": "Los Angeles", "state": "CA", "zip": "90001"}, "to_address": {"name": "Recipient", "street1": "456 Oak Ave", "city": "New York", "state": "NY", "zip": "10001"}, "parcel": {"weight": 16, "weight_unit": "oz"} }' ``` ### Example: Purchase a label ```bash # Step 1: Create draft curl -X POST "https://atoship.com/api/v1/labels" \ -H "Authorization: Bearer ak_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "from_address": {"name": "Sender", "street1": "123 Main St", "city": "Los Angeles", "state": "CA", "zip": "90001"}, "to_address": {"name": "Recipient", "street1": "456 Oak Ave", "city": "New York", "state": "NY", "zip": "10001"}, "parcel": {"weight": 16, "weight_unit": "oz"}, "carrier": "USPS", "service": "Priority Mail" }' # Step 2: Purchase the draft (use the id from step 1) curl -X POST "https://atoship.com/api/v1/labels/{id}/purchase" \ -H "Authorization: Bearer ak_live_your_key_here" ``` ## Why atoship? Shipping is one of the most time-consuming parts of running an online business. Every order means logging into carrier portals, comparing rates manually, copy-pasting addresses, downloading labels, and tracking updates one by one. For teams processing dozens or hundreds of shipments a day, this is a massive operational burden. atoship eliminates that entirely. By connecting your AI assistant to the atoship platform, you get a shipping manager that: - **Thinks in seconds, not minutes** — Rate comparisons across all carriers happen instantly - **Never makes address typos** — Structured data flow from conversation to label, zero manual re-entry - **Remembers context** — Your AI knows what you're shipping, where, and for what purpose - **Scales with your business** — Whether you ship 1 or 1,000 packages a day, the workflow is identical - **Saves real money** — Discounted carrier rates with no volume minimums, no monthly fees atoship is built for e-commerce sellers, small business owners, logistics coordinators, and developers who want to automate their shipping operations without enterprise contracts or complex integrations. **Key features:** - Discounted rates on USPS, FedEx, and UPS — no volume minimums required - Unified API for multi-carrier shipping automation - Real-time tracking and delivery event notifications - Address validation and standardization - Wallet-based billing with no monthly fees or subscriptions ## Security & API key safety This skill calls the atoship REST API (`https://atoship.com/api/v1`) on your behalf. It does **not** write files to disk, does **not** access your file system, does **not** read other environment variables, and only communicates with the single domain `atoship.com`. **Required environment variable:** - `ATOSHIP_API_KEY` — Your atoship API key (`ak_live_...` for production, `ak_test_...` for testing) **Wallet-affecting actions (require user confirmation before executing):** - `purchase_label` — deducts the label cost from your wallet balance - `void_label` — issues a refund (within carrier void window) > **Rule for AI assistants**: You MUST ask the user for explicit confirmation before calling `purchase_label` or `void_label`. Display the action summary (carrier, service, price, addresses) and wait for a "yes" or "confirm" response. Never execute wallet-affecting actions autonomously. **Read-only actions (safe to call without confirmation):** - `get_shipping_rates`, `track_package`, `list_labels`, `get_label`, `get_account`, `list_carrier_accounts`, `validate_address`, `list_orders`, `get_order`, `create_order` **Recommendations:** - Start with a test key (`ak_test_...`) — test labels are free and never shipped - Use a small wallet balance (e.g. $20) while evaluating - Set spending alerts in Dashboard → Billing → Notifications - Rotate/revoke keys at any time from Dashboard → Settings → API Keys ## Support & Contact Having trouble? We're here to help. - **Email**: support@atoship.com - **Website**: https://atoship.com - **Docs**: https://atoship.com/docs - **API Reference**: https://atoship.com/docs/api - **Dashboard**: https://atoship.com/dashboard For API key issues, billing questions, or carrier integration support, email us at support@atoship.com and we'll get back to you within one business day.