label-purchase

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.