Delivery Service
Shipping rates, address validation, and package tracking
Delivery Service
CROP Delivery Services is a unified delivery management platform that integrates multiple shipping providers (UPS and Clinton Tractor) into a single RESTful API. It enables applications to get shipping rates, create and manage shipments, track packages in real-time, and validate delivery addresses.
Architecture
- Runtime: Node.js API service hosted on Google Cloud Platform
- Database: MongoDB for shipment records, rate queries, tracking history
- Updates: Webhook support for real-time status notifications from providers
- Auth: OAuth authentication for provider APIs
- Docs: Interactive Swagger/OpenAPI documentation
Key Components
| Component | Responsibility |
|---|---|
| API Service | Handles all requests -- rate quotes, shipment creation, tracking, address validation |
| Provider Integrations | Direct connections to UPS APIs and Clinton Tractor business-rule engine |
| Database | Persistent storage for shipments, rate queries, tracking events, historical data |
How It Works
1. Rate Quoting
Given origin/destination addresses and package details (weight, dimensions), the system queries all available providers and returns shipping options sorted by price.
2. Shipment Creation
Once a shipping option is selected the system creates the shipment with the chosen provider, generates a tracking number, produces shipping labels (PDF), and stores the record.
3. Tracking and Updates
After shipment creation: real-time tracking via provider webhooks, automatic status updates, delivery notifications, and complete event history with location updates.
4. Management
Address validation, pickup scheduling, location finder, shipment cancellation, and full shipment history.
Core Features
Multi-Provider Rate Quoting
Retrieves shipping rates from all available providers in a single request. Provide origin and destination addresses plus package details; the system returns all available shipping options sorted by price.
Example response set:
- UPS Ground: $15.50 (5 business days)
- Clinton Tractor Standard: $0.00 (3 business days) -- free for orders under $100 within 25 miles
- UPS 2nd Day Air: $25.00 (2 business days)
Shipment Creation and Management
Creates shipments with any provider, generates tracking numbers, and produces shipping labels in PDF format.
Shipment statuses:
| Status | Meaning |
|---|---|
| Pending | Shipment created, awaiting pickup |
| In Transit | Package is on the way |
| Delivered | Successfully delivered |
| Cancelled | Shipment cancelled |
| Failed | Delivery attempt failed |
Real-Time Package Tracking
Unified tracking across all providers. Tracking data includes current status, current location, estimated delivery date, complete event history (pickup, transit updates, delivery confirmation), and delivery location details.
Update mechanisms:
- Webhook notifications from UPS
- Real-time status synchronization
- Configurable email notifications
Address Validation
Validates delivery addresses before shipment creation.
- Validates address format and completeness
- Corrects common address errors
- Verifies postal codes match cities/states
- Suggests corrections when needed
- UPS Address Validation API for comprehensive validation; basic validation for all providers
Shipment Cancellation
Cancels shipments that have not been picked up or are still pending. Once in transit, cancellation may not be possible. Provider-specific rules apply.
Advanced Features
Time in Transit Estimation
Provides delivery time estimates for different UPS service levels: guaranteed delivery dates, business days in transit, and service availability by destination.
Pickup Scheduling
Schedules UPS pickup at a given location. Returns a pickup confirmation number and sends automatic notification.
Location Finder
Finds nearest UPS locations near any address.
Location types: UPS Access Points, The UPS Store, Drop Boxes, Customer Centers, On-Call Air Pickup Points.
Returned data: address, contact info, hours of operation, distance from search address, available services, map coordinates.
Quantum View
Bulk shipment monitoring for multiple tracking numbers or date ranges. Useful for operational reporting and identifying delivery patterns.
Paperless Documents
Uploads commercial invoices and customs documents electronically for international shipments.
Pre-Notifications
Sends advance notifications to customs or other parties before shipment arrival to expedite clearance.
Dangerous Goods Validation
Validates dangerous goods information against shipping regulations: UN numbers, proper shipping names, hazard classifications, packing groups.
Providers
UPS
Full integration with UPS shipping APIs covering domestic (all 50 US states) and international shipping.
Available Services
| Service | Delivery Time | Notes |
|---|---|---|
| UPS Ground | 1-5 business days | Most economical |
| UPS 3 Day Select | 3 business days | Guaranteed |
| UPS 2nd Day Air | 2 business days | Guaranteed |
| UPS 2nd Day Air AM | 2 business days, by 10:30 AM | Morning delivery |
| UPS Next Day Air Saver | Next business day (end of day) | Lower-cost next-day |
| UPS Next Day Air | Next business day | Standard next-day |
| UPS Next Day Air Early AM | Next business day, by 8:00 AM | Earliest delivery |
UPS Advanced Features
Address Validation, Time in Transit, Pickup Scheduling, Quantum View, Paperless Documents, Pre-Notifications, Dangerous Goods Validation, Location Finder, Real-Time Tracking (webhooks).
Clinton Tractor
Custom local/regional delivery service with distance-based pricing and special business rules. Origin location: Clinton, NY (31 Meadow St, 13323). Maximum service radius: 75 miles.
Service Options
Clinton Tractor Standard (Free Shipping)
- Conditions: order value <= $100, distance <= 25 miles, standard delivery
- Price: $0.00
- Delivery time: 5 business days
Premium Clinton Tractor Delivery
- Conditions: distance <= 75 miles
- Price: $150 flat fee
- Delivery time: ~1 day (same-day or next-day)
In-Store Pickup
- Always available, no distance restrictions
- Price: $0.00
LTL Freight (Less Than Truckload)
- Conditions: total shipment weight > 150 lbs
- Price: quoted offline (placeholder $0.00 in API response)
Business Rules
| Rule | Detail |
|---|---|
| Free standard limit | 25 miles max, order <= $100 |
| Premium limit | 75 miles max |
| Beyond 75 miles | Clinton Tractor unavailable; fall back to UPS |
| Guest discount | First-time guest customers get free shipping on first order |
Provider Comparison
| Feature | UPS | Clinton Tractor |
|---|---|---|
| Coverage | Nationwide and International | Regional (up to 75 miles) |
| Service Levels | 7+ (Ground to Next Day Early AM) | 4 (Standard, Premium, Pickup, LTL) |
| Free Shipping | No | Yes (orders <= $100, <= 25 miles) |
| Same-Day / Next-Day | Yes (Next Day Air) | Yes (Premium, within 75 miles) |
| International | Yes | No |
| Tracking | Real-time webhooks | Standard tracking |
| Address Validation | Comprehensive (UPS API) | Basic |
| Pickup Scheduling | Yes | No |
| Location Finder | Yes | No |
Data Persistence
All shipment data, rate queries, and tracking information are stored in MongoDB.
Stored records: shipments with full details, rate query history, tracking updates and events, address validation results.
Health Monitoring
System health endpoint monitors database connectivity, provider availability, and API service status.
Integration
The API is RESTful with JSON request/response format and interactive Swagger/OpenAPI documentation.
Typical integration points:
- E-commerce checkout -- calculate and display shipping options
- Order management systems -- auto-create shipments on order confirmation, sync tracking status
- Customer portals -- self-service tracking
- ERP systems -- shipping data in business operations pipeline