{"openapi":"3.1.0","info":{"title":"Purch","version":"1.0.0","description":"Search and buy products on Amazon and Shopify, and track shipments across 3,400+ carriers. All endpoints are payable via the x402 protocol (USDC on Solana).","guidance":"Purch lets AI agents search for products and purchase them using x402 micropayments (USDC on Solana).\n\n## Quick Start\n1. Search for products: GET /x402/search?q=headphones\n2. Or use natural language: POST /x402/shop with {\"message\": \"comfortable running shoes under $150\"}\n3. Buy a product: POST /x402/buy with the ASIN or product URL, shipping address, and email\n\n## Payment\nAll endpoints require x402 payment. On first request you'll receive a 402 response with payment details.\nYour x402 client handles payment automatically — no wallet setup or transaction signing needed.\n\n## Pricing\n- Search endpoint (GET /x402/search): $0.01 per call\n- AI shopping assistant (POST /x402/shop): $0.10 per call\n- Product purchases (POST /x402/buy): dynamic — equals the product total (including tax/shipping)\n\n## Product Identification\n- Amazon products: use \"asin\" (e.g. \"B0CXYZ1234\") or \"productUrl\" (e.g. \"https://amazon.com/dp/B0CXYZ1234\")\n- Shopify products: use \"productUrl\" + \"variantId\"","contact":{"name":"Purch Support","url":"https://purch.xyz"}},"servers":[{"url":"https://api.purch.xyz","description":"Production"}],"tags":[{"name":"Search","description":"Product search endpoints"},{"name":"Shop","description":"AI-powered shopping assistant"},{"name":"Buy","description":"Checkout and order management"},{"name":"Track","description":"Shipment tracking across 3,400+ carriers"}],"components":{"schemas":{"Product":{"type":"object","properties":{"asin":{"type":"string","example":"B0CXYZ1234"},"title":{"type":"string","example":"Wireless Bluetooth Headphones"},"price":{"type":"number","nullable":true,"example":79.99},"currency":{"type":"string","example":"USD"},"rating":{"type":"number","nullable":true,"example":4.5},"reviewCount":{"type":"number","nullable":true,"example":1250},"imageUrl":{"type":"string","nullable":true,"format":"uri","example":"https://m.media-amazon.com/images/I/example.jpg"},"productUrl":{"type":"string","nullable":true,"format":"uri","example":"https://amazon.com/dp/B0CXYZ1234"},"source":{"type":"string","enum":["amazon","shopify"],"example":"amazon"}},"required":["asin","title","price","currency","rating","reviewCount","imageUrl","productUrl","source"]},"SearchResponse":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"totalResults":{"type":"number","example":150},"page":{"type":"number","example":1},"hasMore":{"type":"boolean","example":true}},"required":["products","totalResults","page","hasMore"]},"ApiError":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid request parameters"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["code","message"]},"PaymentRequired":{"type":"object","properties":{"x402Version":{"type":"number","example":1},"error":{"type":"string","example":"X-PAYMENT header is required"},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"solana"},"maxAmountRequired":{"type":"string","example":"100000"},"resource":{"type":"string","example":"https://api.purch.xyz/shop"},"description":{"type":"string","example":"AI-powered product search"},"mimeType":{"type":"string","example":"application/json"},"maxTimeoutSeconds":{"type":"number","example":60},"asset":{"type":"string","example":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"},"payTo":{"type":"string","example":"DSfjMYRmxsJRxkygD4Z6yhg5XLGyFiNkkZpjFNX2ZEEC"},"extra":{"type":"object","additionalProperties":{"nullable":true}},"outputSchema":{"type":"object","additionalProperties":{"nullable":true}}},"required":["scheme","network","maxAmountRequired","resource","description","mimeType","maxTimeoutSeconds","asset","payTo"]}}},"required":["x402Version","error","accepts"]},"ShopResponse":{"type":"object","properties":{"reply":{"type":"string","description":"AI assistant response message","example":"I found some great running shoes for you! Here are my top recommendations based on comfort and arch support..."},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"},"description":"Recommended products based on the conversation"}},"required":["reply","products"]},"ShopRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":1000,"description":"Natural language shopping request","example":"I need comfortable running shoes under $150 with good arch support"},"context":{"type":"object","properties":{"priceRange":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}}},"preferences":{"type":"array","items":{"type":"string"},"description":"Style or feature preferences","example":["eco-friendly","minimalist"]}},"description":"Optional context to guide the AI assistant"}},"required":["message"]},"X402BuyResponse":{"type":"object","properties":{"orderId":{"type":"string","example":"550e8400-e29b-41d4-a716-446655440000"},"status":{"type":"string","description":"Order status after payment","example":"processing"},"product":{"type":"object","properties":{"title":{"type":"string"},"imageUrl":{"type":"string","format":"uri"},"price":{"type":"object","properties":{"amount":{"type":"string"},"currency":{"type":"string"}},"required":["amount","currency"]}}},"totalPrice":{"type":"object","properties":{"amount":{"type":"string","example":"84.99"},"currency":{"type":"string","example":"USD"}},"required":["amount","currency"]}},"required":["orderId","status","product","totalPrice"]},"ShippingAddress":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"John Doe"},"line1":{"type":"string","minLength":1,"example":"123 Main Street"},"line2":{"type":"string","example":"Apt 4B"},"city":{"type":"string","minLength":1,"example":"San Francisco"},"state":{"type":"string","minLength":1,"example":"CA"},"postalCode":{"type":"string","minLength":1,"example":"94102"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2","example":"US"},"phone":{"type":"string","example":"+1-555-123-4567"}},"required":["name","line1","city","state","postalCode","country"]},"X402BuyRequest":{"type":"object","properties":{"productUrl":{"type":"string","format":"uri","description":"Product URL. For Amazon: https://amazon.com/dp/ASIN. For Shopify: https://store.com/products/item-name (requires variantId)","example":"https://amazon.com/dp/B0CXYZ1234"},"asin":{"type":"string","description":"Amazon ASIN (10-character code). Use this OR productUrl for Amazon products","example":"B0CXYZ1234"},"shippingAddress":{"$ref":"#/components/schemas/ShippingAddress"},"email":{"type":"string","format":"email","description":"Email for order confirmation and tracking","example":"john@example.com"},"variantId":{"type":"string","description":"Required for Shopify products. The specific variant ID from the product","example":"41913945718867"}},"required":["shippingAddress","email"]},"TrackCarrier":{"type":"object","properties":{"code":{"type":"number","nullable":true,"example":100002},"name":{"type":"string","nullable":true,"example":"UPS"},"homepage":{"type":"string","nullable":true,"example":"https://www.ups.com"},"country":{"type":"string","nullable":true,"example":"US"}},"required":["code","name","homepage","country"]},"TrackingEvent":{"type":"object","nullable":true,"properties":{"time":{"type":"string","nullable":true,"description":"ISO 8601 with the carrier's local offset","example":"2026-07-20T14:32:00-07:00"},"description":{"type":"string","nullable":true,"example":"Arrived at facility"},"location":{"type":"string","nullable":true,"example":"OAKLAND, CA, US"},"stage":{"type":"string","nullable":true,"example":"InTransit"}},"required":["time","description","location","stage"]},"TrackMilestone":{"type":"object","properties":{"stage":{"type":"string","description":"One of InfoReceived, PickedUp, Departure, Arrival, AvailableForPickup, OutForDelivery, Delivered, Returning, Returned","example":"PickedUp"},"time":{"type":"string","nullable":true,"example":"2026-07-15T08:46:00-05:00"}},"required":["stage","time"]},"TrackResult":{"type":"object","properties":{"number":{"type":"string","example":"1ZA1234E0205271688"},"status":{"type":"string","enum":["NotFound","InfoReceived","InTransit","Expired","AvailableForPickup","OutForDelivery","DeliveryFailure","Delivered","Exception"],"description":"Normalized shipment status","example":"InTransit"},"subStatus":{"type":"string","nullable":true,"example":"InTransit_CustomsProcessing"},"statusDescription":{"type":"string","nullable":true,"description":"Carrier elaboration on the sub-status, when provided","example":null},"delivered":{"type":"boolean","example":false},"found":{"type":"boolean","description":"False when no carrier data exists yet","example":true},"carrier":{"$ref":"#/components/schemas/TrackCarrier"},"lastMileCarrier":{"type":"object","nullable":true,"properties":{"code":{"type":"number","nullable":true,"example":21051},"name":{"type":"string","nullable":true,"example":"USPS"}},"required":["code","name"],"description":"Final-mile carrier on postal handoffs, else null"},"origin":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2","example":"CN"},"destination":{"type":"string","nullable":true,"example":"US"},"latestEvent":{"$ref":"#/components/schemas/TrackingEvent"},"events":{"type":"array","items":{"$ref":"#/components/schemas/TrackingEvent"},"description":"Full history, newest first, deduped across carriers"},"milestones":{"type":"array","items":{"$ref":"#/components/schemas/TrackMilestone"},"description":"Stages the package has reached, in shipping order"},"pickedUpAt":{"type":"string","nullable":true,"example":"2026-07-15T08:46:00-05:00"},"deliveredAt":{"type":"string","nullable":true,"example":null},"daysInTransit":{"type":"number","nullable":true,"example":6},"daysSinceLastUpdate":{"type":"number","nullable":true,"description":"Days since the carrier last reported — use to judge staleness","example":1},"estimatedDelivery":{"type":"object","nullable":true,"properties":{"from":{"type":"string","nullable":true,"example":"2026-07-28T08:00:00-05:00"},"to":{"type":"string","nullable":true,"example":"2026-07-30T13:00:00-05:00"},"source":{"type":"string","nullable":true,"description":"\"Official\" (from the carrier) or \"17TRACK\" (estimated)","example":"Official"}},"required":["from","to","source"]},"serviceType":{"type":"string","nullable":true,"example":"UPS Worldwide Express"},"weightKg":{"type":"string","nullable":true,"example":"1.1"},"carrierNotice":{"type":"string","nullable":true,"description":"Official carrier notice, often explaining a tracking problem","example":null},"trackingPageUrl":{"type":"string","description":"Human-readable tracking page for the same number","example":"https://t.17track.net/en#nums=1ZA1234E0205271688"}},"required":["number","status","subStatus","statusDescription","delivered","found","carrier","lastMileCarrier","origin","destination","latestEvent","events","milestones","pickedUpAt","deliveredAt","daysInTransit","daysSinceLastUpdate","estimatedDelivery","serviceType","weightKg","carrierNotice","trackingPageUrl"]}},"parameters":{},"securitySchemes":{"x402":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE"}}},"paths":{"/x402/search":{"get":{"tags":["Search"],"summary":"Search products","description":"Search for products using structured filters. Returns paginated results from Amazon and Shopify.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Search query","example":"wireless headphones"},"required":true,"name":"q","in":"query"},{"schema":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Minimum price filter","example":20},"required":false,"name":"priceMin","in":"query"},{"schema":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Maximum price filter","example":200},"required":false,"name":"priceMax","in":"query"},{"schema":{"type":"string","description":"Filter by brand","example":"Sony"},"required":false,"name":"brand","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1,"description":"Page number for pagination","example":1},"required":false,"name":"page","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}},"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.01"},"security":[{"x402":[]}],"extensions":{"bazaar":{"schema":{"properties":{"input":{"type":"object","properties":{"q":{"type":"string","minLength":1,"description":"Search query","example":"wireless headphones"},"priceMin":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Minimum price filter","example":20},"priceMax":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Maximum price filter","example":200},"brand":{"type":"string","description":"Filter by brand","example":"Sony"},"page":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1,"description":"Page number for pagination","example":1}},"required":["q"]},"output":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"totalResults":{"type":"number","example":150},"page":{"type":"number","example":1},"hasMore":{"type":"boolean","example":true}},"required":["products","totalResults","page","hasMore"]}}}}}}},"/x402/shop":{"post":{"tags":["Shop"],"summary":"AI shopping assistant","description":"Natural language product search powered by AI. Describe what you're looking for and get personalized recommendations.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopRequest"}}}},"responses":{"200":{"description":"AI response with product recommendations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}},"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.10"},"security":[{"x402":[]}],"extensions":{"bazaar":{"schema":{"properties":{"input":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":1000,"description":"Natural language shopping request","example":"I need comfortable running shoes under $150 with good arch support"},"context":{"type":"object","properties":{"priceRange":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}}},"preferences":{"type":"array","items":{"type":"string"},"description":"Style or feature preferences","example":["eco-friendly","minimalist"]}},"description":"Optional context to guide the AI assistant"}},"required":["message"]},"output":{"type":"object","properties":{"reply":{"type":"string","description":"AI assistant response message","example":"I found some great running shoes for you! Here are my top recommendations based on comfort and arch support..."},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"},"description":"Recommended products based on the conversation"}},"required":["reply","products"]}}}}}}},"/x402/buy":{"post":{"tags":["Buy"],"summary":"Purchase a product (x402 dynamic pricing)","description":"Purchase a product with x402 dynamic pricing. The x402 payment amount equals the product's total price (including tax and shipping).\n\n## How it works\n1. Send your request — you'll receive a 402 response with the exact product price\n2. Your x402 client handles payment automatically (USDC on Solana)\n3. On successful payment, the order is fulfilled and you receive confirmation\n\n## Amazon Products\nUse **either**:\n- `asin` - The Amazon ASIN (e.g., `B0CXYZ1234`)\n- `productUrl` - Amazon product URL (e.g., `https://amazon.com/dp/B0CXYZ1234`)\n\n## Shopify Products\nUse **both**:\n- `productUrl` - Shopify product URL (e.g., `https://store.com/products/item-name`)\n- `variantId` - The specific variant ID (e.g., `41913945718867`)\n\n## Response\nReturns order confirmation with status and product details. No transaction signing needed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402BuyRequest"}}}},"responses":{"200":{"description":"Order created and paid successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402BuyResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Payment Required — price equals the product total","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}},"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"quote"},"security":[{"x402":[]}],"extensions":{"bazaar":{"schema":{"properties":{"input":{"type":"object","properties":{"productUrl":{"type":"string","format":"uri","description":"Product URL. For Amazon: https://amazon.com/dp/ASIN. For Shopify: https://store.com/products/item-name (requires variantId)","example":"https://amazon.com/dp/B0CXYZ1234"},"asin":{"type":"string","description":"Amazon ASIN (10-character code). Use this OR productUrl for Amazon products","example":"B0CXYZ1234"},"shippingAddress":{"$ref":"#/components/schemas/ShippingAddress"},"email":{"type":"string","format":"email","description":"Email for order confirmation and tracking","example":"john@example.com"},"variantId":{"type":"string","description":"Required for Shopify products. The specific variant ID from the product","example":"41913945718867"}},"required":["shippingAddress","email"]},"output":{"type":"object","properties":{"orderId":{"type":"string","example":"550e8400-e29b-41d4-a716-446655440000"},"status":{"type":"string","description":"Order status after payment","example":"processing"},"product":{"type":"object","properties":{"title":{"type":"string"},"imageUrl":{"type":"string","format":"uri"},"price":{"type":"object","properties":{"amount":{"type":"string"},"currency":{"type":"string"}},"required":["amount","currency"]}}},"totalPrice":{"type":"object","properties":{"amount":{"type":"string","example":"84.99"},"currency":{"type":"string","example":"USD"}},"required":["amount","currency"]}},"required":["orderId","status","product","totalPrice"]}}}}}}},"/x402/track":{"get":{"tags":["Track"],"summary":"Track a shipment","description":"Look up live shipment status for any tracking number across 3,400+ carriers (UPS, USPS, FedEx, DHL, Royal Mail, China Post, Cainiao, and most regional/cross-border couriers). **Only `number` is required** — the carrier is auto-detected from the number format. Returns a normalized status, milestone timeline, and the full event history newest-first. Works with any tracking number; it does not have to be a Purch order.\n\nFreshness: the carrier is re-polled every 6–12 hours (24h once delivered), so check `daysSinceLastUpdate` to judge staleness.","parameters":[{"schema":{"type":"string","minLength":5,"maxLength":50,"pattern":"^[A-Za-z0-9-]+$","description":"Tracking number from any of 3,400+ supported carriers","example":"1ZA1234E0205271688"},"required":true,"name":"number","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Optional 17TRACK numeric carrier code. Omit it and the carrier is auto-detected — only supply it for ambiguous numbers, or after a CARRIER_NOT_DETECTED response. Codes: https://res.17track.net/asset/carrier/info/apicarrier.all.json","example":100002},"required":false,"name":"carrier","in":"query"},{"schema":{"type":"string","maxLength":20,"description":"Only needed if a lookup returns ADDITIONAL_FIELD_REQUIRED naming a postal code","example":"94102"},"required":false,"name":"destinationPostalCode","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2. Paired with destinationPostalCode by some carriers.","example":"US"},"required":false,"name":"destinationCountry","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Ship date (YYYY-MM-DD). Only needed if a lookup returns ADDITIONAL_FIELD_REQUIRED naming a date.","example":"2026-07-14"},"required":false,"name":"shipDate","in":"query"},{"schema":{"type":"string","maxLength":30,"description":"Only needed if a lookup returns ADDITIONAL_FIELD_REQUIRED naming a phone number","example":"+15551234567"},"required":false,"name":"phone","in":"query"},{"schema":{"type":"string","maxLength":20,"description":"Brazilian CPF/CNPJ, required by some Brazilian carriers","example":"12345678901"},"required":false,"name":"cpfOrCnpj","in":"query"}],"responses":{"200":{"description":"Shipment status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackResult"}}}},"400":{"description":"Invalid tracking number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"404":{"description":"No tracking information available for this number yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"`CARRIER_NOT_DETECTED` — retry with an explicit `carrier`; or `ADDITIONAL_FIELD_REQUIRED` — the carrier needs a postal code, phone, or ship date (the message names which)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Tracking provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Tracking provider unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.52"},"security":[{"x402":[]}],"extensions":{"bazaar":{"schema":{"properties":{"input":{"type":"object","properties":{"number":{"type":"string","minLength":5,"maxLength":50,"pattern":"^[A-Za-z0-9-]+$","description":"Tracking number from any of 3,400+ supported carriers","example":"1ZA1234E0205271688"},"carrier":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Optional 17TRACK numeric carrier code. Omit it and the carrier is auto-detected — only supply it for ambiguous numbers, or after a CARRIER_NOT_DETECTED response. Codes: https://res.17track.net/asset/carrier/info/apicarrier.all.json","example":100002},"destinationPostalCode":{"type":"string","maxLength":20,"description":"Only needed if a lookup returns ADDITIONAL_FIELD_REQUIRED naming a postal code","example":"94102"},"destinationCountry":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2. Paired with destinationPostalCode by some carriers.","example":"US"},"shipDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Ship date (YYYY-MM-DD). Only needed if a lookup returns ADDITIONAL_FIELD_REQUIRED naming a date.","example":"2026-07-14"},"phone":{"type":"string","maxLength":30,"description":"Only needed if a lookup returns ADDITIONAL_FIELD_REQUIRED naming a phone number","example":"+15551234567"},"cpfOrCnpj":{"type":"string","maxLength":20,"description":"Brazilian CPF/CNPJ, required by some Brazilian carriers","example":"12345678901"}},"required":["number"]},"output":{"type":"object","properties":{"number":{"type":"string","example":"1ZA1234E0205271688"},"status":{"type":"string","enum":["NotFound","InfoReceived","InTransit","Expired","AvailableForPickup","OutForDelivery","DeliveryFailure","Delivered","Exception"],"description":"Normalized shipment status","example":"InTransit"},"subStatus":{"type":"string","nullable":true,"example":"InTransit_CustomsProcessing"},"statusDescription":{"type":"string","nullable":true,"description":"Carrier elaboration on the sub-status, when provided","example":null},"delivered":{"type":"boolean","example":false},"found":{"type":"boolean","description":"False when no carrier data exists yet","example":true},"carrier":{"$ref":"#/components/schemas/TrackCarrier"},"lastMileCarrier":{"type":"object","nullable":true,"properties":{"code":{"type":"number","nullable":true,"example":21051},"name":{"type":"string","nullable":true,"example":"USPS"}},"required":["code","name"],"description":"Final-mile carrier on postal handoffs, else null"},"origin":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2","example":"CN"},"destination":{"type":"string","nullable":true,"example":"US"},"latestEvent":{"$ref":"#/components/schemas/TrackingEvent"},"events":{"type":"array","items":{"$ref":"#/components/schemas/TrackingEvent"},"description":"Full history, newest first, deduped across carriers"},"milestones":{"type":"array","items":{"$ref":"#/components/schemas/TrackMilestone"},"description":"Stages the package has reached, in shipping order"},"pickedUpAt":{"type":"string","nullable":true,"example":"2026-07-15T08:46:00-05:00"},"deliveredAt":{"type":"string","nullable":true,"example":null},"daysInTransit":{"type":"number","nullable":true,"example":6},"daysSinceLastUpdate":{"type":"number","nullable":true,"description":"Days since the carrier last reported — use to judge staleness","example":1},"estimatedDelivery":{"type":"object","nullable":true,"properties":{"from":{"type":"string","nullable":true,"example":"2026-07-28T08:00:00-05:00"},"to":{"type":"string","nullable":true,"example":"2026-07-30T13:00:00-05:00"},"source":{"type":"string","nullable":true,"description":"\"Official\" (from the carrier) or \"17TRACK\" (estimated)","example":"Official"}},"required":["from","to","source"]},"serviceType":{"type":"string","nullable":true,"example":"UPS Worldwide Express"},"weightKg":{"type":"string","nullable":true,"example":"1.1"},"carrierNotice":{"type":"string","nullable":true,"description":"Official carrier notice, often explaining a tracking problem","example":null},"trackingPageUrl":{"type":"string","description":"Human-readable tracking page for the same number","example":"https://t.17track.net/en#nums=1ZA1234E0205271688"}},"required":["number","status","subStatus","statusDescription","delivered","found","carrier","lastMileCarrier","origin","destination","latestEvent","events","milestones","pickedUpAt","deliveredAt","daysInTransit","daysSinceLastUpdate","estimatedDelivery","serviceType","weightKg","carrierNotice","trackingPageUrl"]}}}}}}}}}