Package Types

The Hubby API supports four different types of eSIM packages, each designed for specific use cases and customer needs. Understanding these package types will help you choose the right option for your customers.

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