Package Types

In the Hubby API, a Bundle is the data product a traveler receives for a specific Destination — it defines the data allowance, duration, and type. Bundles come in four types, each designed for different travel scenarios. When you create a Booking, each entry in package_specifications selects a Bundle (either by specifying destination + size, or by referencing a package_id directly).

Overview

All package types support the same core parameters (destination, size, package_id) but introduce two new parameters to specify the package behavior:

• package_type: Determines how the package behaves
• package_duration: Specifies how long the package remains active (in days)

Package specification resolution: For each package specification, provide either package_id (direct reference) or other properties (destination, size, package_type, etc.). When package_id is present, the package is resolved solely by that identifier; other fields in the same specification are not used for resolution and are effectively ignored. If package_id is invalid or the package is not found, the request will fail for that spec—other fields are not used as fallback.

Starter Packages

Package Type: starter
Default Duration: 2 days

Starter packages are hybrid packages that combine both data and time limitations. They provide a maximum data allowance within a specific time period, making them ideal for users who want to try eSIM services or need connectivity for very short periods.

Characteristics

• Data Cap: Limited data allowance (typically smaller than data-limited packages)
• Time Limit: Short duration (2 days by default, configurable)
• Usage Pattern: Users have both data and time constraints
• Expiration: Package expires when either the data is exhausted OR the time limit is reached

Use Cases

• First-time users: Customers trying eSIM services for the first time
• Very short trips: Day trips or overnight stays
• Budget trials: Users who want to test connectivity before committing to larger packages
• Backup connectivity: Secondary data source for emergencies

Example Request

{
  "departure_date": "2026-01-03",
  "email": "customer@example.com",
  "package_specifications": [
    {
      "destination": "USA",
      "size": "500MB",
      "package_type": "starter",
      "package_duration": 1
    }
  ]
}

Data-Limited Packages (Default)

Package Type: data-limited
Default Duration: 365 days

Data-limited packages are the traditional eSIM packages that most users are familiar with. These packages provide a specific amount of data that can be used over an extended period.

Characteristics

• Data Cap: Fixed data allowance (e.g., 1GB, 5GB, 10GB)
• Time Limit: 365 days by default (configurable)
• Usage Pattern: Data is consumed as the user browses, streams, or uses apps
• Expiration: Package expires when either the data is exhausted OR the time limit is reached

Use Cases

• Long-term travelers: Users who need connectivity over extended periods
• Business travelers: Professionals who need reliable, predictable data usage
• Budget-conscious users: Customers who want to control their data spending
• Most common scenarios: This is the default package type for most use cases

Example Request

{
  "departure_date": "2026-01-03",
  "email": "customer@example.com",
  "package_specifications": [
    {
      "destination": "USA",
      "size": "1GB",
      "package_type": "data-limited",
      "package_duration": 365
    }
  ]
}

Unlimited Packages

Package Type: unlimited
Default Duration: Varies by destination

Unlimited packages provide unrestricted data usage for a specified duration. These packages are ideal for heavy data users who don't want to worry about data caps.

Characteristics

• Data Cap: Unlimited data (fair use policy applies)
• Time Limit: Duration-based expiration (varies by destination)
• Usage Pattern: No data consumption tracking; users can browse, stream, and download freely
• Expiration: Package expires when the time limit is reached
• Fair Use Policy: Subject to carrier fair use policies to prevent abuse

Use Cases

• Digital nomads: Remote workers who need constant connectivity
• Long-term travelers: Extended stays in a destination
• Heavy data users: Customers who stream video, attend video calls, or download large files
• Business travelers: Executives who need unrestricted access for work
• Worry-free connectivity: Users who don't want to monitor data usage

Example Request

{
  "departure_date": "2026-01-03",
  "email": "customer@example.com",
  "package_specifications": [
    {
      "destination": "USA",
      "package_type": "unlimited",
      "package_duration": 30
    }
  ]
}

Note: The size parameter is not required for unlimited packages since data is unrestricted.

Time-Limited Packages

Package Type: time-limited
Default Duration: 2 days

Time-limited packages provide full-speed data access with both a maximum data allowance and a strict time limit. These packages are perfect for short trips where users need high-speed connectivity for a defined period.

Characteristics

• Data Cap: Fixed data allowance with full-speed access (e.g., 5GB, 10GB)
• Time Limit: Short duration (2 days by default, configurable up to 30 days)
• Usage Pattern: High-speed data consumption tracked against both data and time limits
• Expiration: Package expires when either the data limit OR the time limit is reached

Use Cases

• Short business trips: Executives who need high-speed connectivity for meetings
• Weekend getaways: Travelers who need reliable, fast connectivity for a fixed period
• High-data users: Customers who need full-speed access for video streaming, video calls, or large file downloads
• Time-sensitive trips: Users who need guaranteed connectivity for a specific duration

Example Request

{
  "departure_date": "2026-01-03",
  "email": "customer@example.com",
  "package_specifications": [
    {
      "destination": "USA",
      "size": "5GB",
      "package_type": "time-limited",
      "package_duration": 3
    }
  ]
}

Package Duration Guidelines

Starter Packages

• Recommended range: 1-3 days
• Default: 2 days
• Use cases: Day trips, trials, emergency connectivity

Data-Limited Packages

• Recommended range: 30-365 days
• Default: 365 days
• Use cases: Long-term travel, business trips, extended stays

Unlimited Packages

• Recommended range: 7-30 days
• Default: Varies by destination
• Use cases: Long stays, heavy data usage, digital nomads, business travelers

Time-Limited Packages

• Recommended range: 1-7 days
• Default: 2 days
• Use cases: Short trips, weekend getaways, business meetings

Important Notes

Top-ups

All top-ups are data-limited packages, regardless of the original package type. This ensures consistent behavior when customers need additional data.

Default Behavior

• If package_type is not specified, the API defaults to data-limited
• If package_duration is not specified:
  • Data-limited packages default to 365 days
  • Time-limited and starter packages default to 2 days
  • Unlimited packages default varies by destination

Package Selection Strategy

When using destination-based package selection (i.e. when package_id is not set), the system will:

1. First look for packages matching the specified package_type
2. Apply the partner's configured strategy for size selection
3. Use the specified package_duration or default values

Best Practices

1. Default to data-limited: Use data-limited packages as your primary offering for most travelers
2. Offer time-limited for short trips: Provide time-limited options for customers on brief journeys who need full-speed access
3. Use starter packages for trials: Introduce new customers with starter packages to let them experience eSIM connectivity
4. Offer unlimited for heavy users: Provide unlimited packages for digital nomads, business travelers, and customers who stream or download frequently
5. Communicate clearly: Make sure customers understand the differences between all four package types
6. Consider use cases: Match package types to customer travel patterns and data needs

Migration from Previous Versions

If you're upgrading from API version 1.3.0 or earlier:

• Existing bookings will continue to work as data-limited packages
• New bookings will default to data-limited packages unless specified otherwise
• No breaking changes to existing integrations
• New parameters are optional and have sensible defaults