Routes and Subscriptions

Understanding how shipping routes and subscriptions work in SoshiaConnect.

What are Routes?

Routes represent shipping paths between origin and destination ports, operated by various carriers. Each route contains:

• Route Information: Name, code, carrier details
• Geographic Data: Origin port, destination port, waypoints
• Schedule Details: Transit times, departure frequencies
• Service Levels: Express, standard, economy options
• Pricing Information: Base rates, surcharges
• Capacity Data: Available slots, booking status

Route Hierarchy

Routes are organized in a hierarchical structure:

Region (e.g., Asia-Pacific)
  └── Trade Lane (e.g., Asia-Europe)
      └── Route Group (e.g., China-Netherlands)
          └── Individual Routes
              └── Periods (Time-based data segments)
                  └── Reports (Specific data points)

Route Types

By Service Level:

• Express Routes: Faster transit, premium pricing
• Standard Routes: Regular service, balanced pricing
• Economy Routes: Slower transit, budget pricing

By Cargo Type:

• Container shipping
• Bulk cargo
• Ro-Ro (Roll-on/Roll-off)
• Break bulk

Accessing Route Data

Via Portal:

1. Navigate to Routes section
2. Use filters to find routes
3. View route details
4. Subscribe for access

Via API:

# List all routes
GET /route-access/all-routes

# Get specific route
GET /route-access/routes-data?id=123

# Check route access
POST /route-access/check-access

Understanding Subscriptions

Subscriptions grant you access to route data for a specified period.

Subscription Model

How It Works:

1. Choose a route you want to access
2. Select subscription term (1-12 months)
3. Complete payment
4. Gain immediate access to route data
5. Access continues until subscription expires

Subscription Terms

Available subscription durations:

Term	Discount	Best For
1 Month	0%	Trial/Testing
2 Months	5%	Short-term projects
3 Months	10%	Quarterly planning
6 Months	15%	Medium-term needs
12 Months	25%	Long-term operations

What's Included

Each subscription includes:

• API Access: Programmatic data retrieval
• Portal Access: Web-based route viewing
• Historical Data: Past periods (where available)
• Real-time Updates: Current schedule changes
• Analytics: Usage statistics and reports
• Support: Technical assistance

Subscription Status

Active

• Full access to route data
• API calls counted toward quota
• Can view in portal and API

Expiring Soon

• Within 7 days of expiration
• Renewal reminders sent
• Full access still available

Expired

• No longer able to access route data
• Historical access may be limited
• Can renew to restore access

Cancelled

• Access continues until period end
• Auto-renewal disabled
• Can resubscribe anytime

Subscription Lifecycle

1. Discovery Phase

Finding the Right Routes:

# Browse available routes
GET /route-access/all-routes

# Filter by criteria
GET /route-access/all-routes?origin=CNYTN&destination=NLRTM

Evaluating Routes:

• Review route details
• Check pricing
• Verify coverage period
• Compare alternatives

2. Purchase Phase

Price Calculation:

POST /subscriptions/calculate-single-route-price
{
  "period_id": 123,
  "subscription_term": "3_months"
}

Creating Subscription:

1. Calculate price
2. Create payment intent
3. Process payment
4. Confirm subscription activation

Payment Flow:

# Step 1: Calculate
POST /subscriptions/calculate-subscription-price

# Step 2: Create payment
POST /subscriptions/create-payment-intent

# Step 3: Confirm
POST /subscriptions/payment-success

3. Active Phase

Using Your Subscription:

# Get your active routes
GET /subscriptions/my-routes

# Access route data
GET /api-routes-data?id=123
Headers:
  X-API-Key: your_key
  X-Username: your_username

Monitoring Usage:

# View statistics
GET /subscriptions/my-stats

# Check API usage
GET /api-usage-logs

4. Renewal Phase

Auto-Renewal:

• Enabled by default
• Charges 3 days before expiration
• Email notifications sent
• Can disable in portal

Manual Renewal:

1. Receive expiration notice
2. Review pricing (may have changed)
3. Select new term
4. Complete payment

Upgrading/Downgrading:

• Can change term length during renewal
• Longer terms offer better pricing
• Prorated billing for changes

5. Expiration/Cancellation

What Happens:

• Access ends at period close
• API calls return 403 Forbidden
• Portal shows expired status
• Can resubscribe anytime

Data Retention:

• Downloaded data remains yours
• Historical analytics available
• Usage logs preserved

Pricing Structure

Base Pricing

Routes are priced based on:

Route Popularity:

• High-demand routes: Premium pricing
• Standard routes: Regular pricing
• Low-demand routes: Budget pricing

Data Freshness:

• Real-time data: Higher cost
• Daily updates: Standard cost
• Weekly updates: Lower cost

Geographic Factors:

• Major trade lanes: Variable pricing
• Regional routes: Standardized pricing
• Emerging markets: Promotional pricing

Discount Structure

Term-Based Discounts:

1 month:  No discount
2 months: 5% off
3 months: 10% off
6 months: 15% off
12 months: 25% off

Volume Discounts:

• 5-10 routes: 5% additional
• 11-20 routes: 10% additional
• 21+ routes: Custom pricing

Partner Discounts:

• Partner referrals: Commission earned
• Bulk licensing: Contact sales
• Enterprise contracts: Custom terms

Cost Optimization

Save Money By:

1. Choosing Longer Terms

   Instead of: 12 × 1-month = $1,200
   Choose: 1 × 12-month = $900
   Savings: $300 (25%)

2. Bundling Routes

   • Subscribe to multiple routes
   • Negotiate volume discounts
   • Consolidate billing

3. Annual Planning

   • Commit to yearly terms
   • Lock in pricing
   • Avoid price increases

4. Monitor Usage

   • Cancel unused subscriptions
   • Optimize API calls
   • Use caching effectively

Managing Subscriptions

Via Portal

View All Subscriptions: Dashboard → My Subscriptions

Subscription Actions:

• Renew early
• Change auto-renewal settings
• Upgrade term
• Cancel subscription
• View billing history

Via API

List Active Subscriptions:

GET /subscriptions/my-routes
Authorization: Bearer {token}

Response:

{
  "subscriptions": [
    {
      "id": 1,
      "route_name": "China-Netherlands Express",
      "subscription_term": "3_months",
      "start_date": "2025-01-01",
      "end_date": "2025-04-01",
      "status": "active",
      "auto_renew": true
    }
  ]
}

Check Expiring Subscriptions:

GET /subscriptions/upcoming-expirations
Authorization: Bearer {token}

Best Practices

Planning Subscriptions

✅ Do:

• Evaluate needs before subscribing
• Start with shorter terms for testing
• Monitor usage regularly
• Set up expiration alerts
• Budget for renewals

❌ Don't:

• Over-subscribe to unused routes
• Ignore expiration warnings
• Let critical routes expire
• Subscribe without API testing
• Forget to disable auto-renewal if not needed

Optimizing Costs

Regular Review:

Every Month:
- Check active subscriptions
- Review usage statistics
- Identify unused routes
- Plan renewals

Every Quarter:
- Evaluate ROI
- Consider term changes
- Negotiate volume discounts
- Update budget

Usage Monitoring:

# Weekly check
GET /api-usage-logs

# Analyze patterns
- Peak usage times
- Most accessed routes
- Underutilized subscriptions
- API efficiency

Access Management

Team Access:

• Create separate API keys per team
• Track usage by key
• Set permissions appropriately
• Regular access audits

Security:

• Rotate API keys regularly
• Monitor for unusual access
• Disable unused keys
• Use IP whitelisting (if available)

Subscription FAQs

Q: Can I pause a subscription? A: No, but you can disable auto-renewal and let it expire, then resubscribe when needed.

Q: What happens to my data when subscription expires? A: You retain any data you've downloaded, but can no longer access new data.

Q: Can I transfer a subscription to another account? A: No, subscriptions are non-transferable. Contact support for special cases.

Q: Do I get refunds for unused time? A: Subscriptions are non-refundable, but we offer prorated credits for annual plans in special circumstances.

Q: Can I share my subscription access? A: Each subscription is for single account use. Contact sales for multi-user licensing.

Q: How do I know which routes I need? A: Start with our free trial or contact our sales team for consultation.

Support

Need help with routes or subscriptions?

• 📧 Email: support@soshiaconnect.com
• 💬 Live chat: Available in portal
• 📞 Phone: Enterprise customers
• 📚 Documentation: API Reference

---

Related Guides:

• Portal Guide
• Quick Start
• API Best Practices