batch-shipping

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.