Channel Package Management¶

Channel packages are groups of TV channels bundled together for selling to subscribers. Packages allow you to create various pricing plans and monetize your IPTV service.

What is a Channel Package¶

A channel package in Catena is a named group of TV channels that can be assigned to subscribers. Packages allow you to:

Create pricing plans — group channels by themes (sports, movies, news) or access levels (basic, premium)
Monetize the service — sell access to channel packages to subscribers
Manage access — provide different subscribers with access to different sets of channels
Simplify administration — assign packages instead of managing access to each channel individually

Important concept: A channel by itself is not accessible to subscribers. Access to a channel is provided only through packages that the subscriber is subscribed to.

Main Package Parameters¶

Technical Parameters¶

Package ID

Automatically generated when creating a package
Format: base64-encoded Snowflake ID with +/= replaced by -_.
Example: aKl9SW3AAAE.
Used for programmatic access via API
Not editable after creation

Package Name (Name)

Unique technical package name within the portal
Used in the system to identify the package
Requirements:
Only Latin letters, digits, hyphen and underscore: [a-zA-Z0-9_-]
Length from 2 to 20 characters
Must be unique within your portal
Examples: basic, premium, sport-pack, movies_hd

Portal ID

Identifier of the portal the package belongs to
Automatically set upon creation

Display Parameters¶

Description

Text description of the package for administrators
Can contain information about package content, pricing, target audience
Not a required field
Examples: "Basic package of 30 channels", "Premium sports channels in HD quality"

Package Content¶

Channel List (Channels)

Read-only field
Contains names of all channels included in the package
Automatically updated when adding/removing channels via relationship management API
Example: ["sport1", "sport2", "news", "movies-hd"]

Creating a Package¶

Via Web Interface¶

Open the "Packages" section in the Catena control panel
Click the "Create Package" button
Fill in required fields:
Name — technical package name (in Latin)
Description — package description (optional)
Save the package
Add channels to the package through the composition management section

After creation, the package will receive a unique ID and will be available for assignment to subscribers.

Via Management API¶

curl -X POST https://your-catena-domain.com/tv-management/api/v1/packages \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "premium",
    "description": "Premium package with HD channels"
  }'

Response:

{
  "packageId": "pKl9SW3AAAE.",
  "portalId": "portal123",
  "name": "premium",
  "description": "Premium package with HD channels",
  "channels": []
}

Viewing Package List¶

Via Web Interface¶

The "Packages" section displays a table with all portal packages:

Name — package name (Name)
Description — text package description
Channel Count — how many channels are in the package
Subscribers — number of subscribers with this package
Actions — edit and delete buttons

Via Management API¶

Get list of all packages:

curl -X GET https://your-catena-domain.com/tv-management/api/v1/packages \
  -H "X-Auth-Token: your-api-key"

Response:

{
  "packages": [
    {
      "packageId": "pKl9SW3AAAE.",
      "portalId": "portal123",
      "name": "premium",
      "description": "Premium package with HD channels",
      "channels": ["sport1", "sport2", "news-hd", "movies-4k"]
    },
    {
      "packageId": "bKl9SW3AAAE.",
      "portalId": "portal123",
      "name": "basic",
      "description": "Basic channel package",
      "channels": ["news", "general"]
    }
  ],
  "next": "cursor-for-next-page"
}

Pagination:

To get the next page, use the cursor parameter:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/packages?cursor=cursor-for-next-page" \
  -H "X-Auth-Token: your-api-key"

Getting Package Information¶

Via Management API¶

Get package by ID:

curl -X GET https://your-catena-domain.com/tv-management/api/v1/packages/pKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key"

Response:

{
  "packageId": "pKl9SW3AAAE.",
  "portalId": "portal123",
  "name": "premium",
  "description": "Premium package with HD channels",
  "channels": ["sport1", "sport2", "news-hd", "movies-4k"]
}

Editing a Package¶

Via Web Interface¶

Open the package list
Find the needed package and click the "Edit" button
Change parameters:
Name — technical name (better not to change after creation)
Description — package description
Save changes

Note: Changing the channel composition of a package is done separately through channel-package relationship management.

Via Management API¶

curl -X PUT https://your-catena-domain.com/tv-management/api/v1/packages/pKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "premium",
    "description": "Premium package with HD and 4K channels"
  }'

Deleting a Package¶

Via Web Interface¶

Open the package list
Find the package to delete
Click the "Delete" button
Confirm deletion

Warning: When deleting a package:

All subscribers will lose access to channels from this package (if they don't have other packages with these channels)
Relationships between the package and channels will be removed
Relationships between the package and subscribers will be removed

Via Management API¶

curl -X DELETE https://your-catena-domain.com/tv-management/api/v1/packages/pKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key"

Managing Package Composition¶

Adding a Channel to Package¶

Via Management API:

curl -X POST https://your-catena-domain.com/tv-management/api/v1/channels-packages \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "cKl9SW3AAAE.",
    "packageId": "pKl9SW3AAAE.",
    "portalId": "portal123"
  }'

Response:

{
  "channelId": "cKl9SW3AAAE.",
  "packageId": "pKl9SW3AAAE.",
  "portalId": "portal123"
}

After adding:

The channel will be displayed in the package's channels field
The package will be displayed in the channel's packages field
All subscribers with this package will receive access to the added channel

Removing a Channel from Package¶

Via Management API:

curl -X DELETE https://your-catena-domain.com/tv-management/api/v1/channels-packages \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "cKl9SW3AAAE.",
    "packageId": "pKl9SW3AAAE.",
    "portalId": "portal123"
  }'

Important: Removing a channel from a package does not delete the channel itself from the system, only breaks the relationship between the channel and package.

Bulk Channel Management¶

To add multiple channels to a package, use sequential API calls:

# Add channel 1
curl -X POST https://your-catena-domain.com/tv-management/api/v1/channels-packages \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"channelId": "channel1", "packageId": "premium", "portalId": "portal123"}'

# Add channel 2
curl -X POST https://your-catena-domain.com/tv-management/api/v1/channels-packages \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"channelId": "channel2", "packageId": "premium", "portalId": "portal123"}'

Assigning Packages to Subscribers¶

For more details on assigning packages to subscribers, see the Subscription Management section.

Adding a Package to Subscriber¶

curl -X POST https://your-catena-domain.com/tv-management/api/v1/packages-subscribers \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "packageId": "pKl9SW3AAAE.",
    "subscriberId": "sKl9SW3AAAE.",
    "portalId": "portal123"
  }'

After assigning a package to a subscriber:

The subscriber will receive access to all channels from this package
The package will appear in the subscriber's package list
Access will be provided in all client applications

Removing a Package from Subscriber¶

curl -X DELETE https://your-catena-domain.com/tv-management/api/v1/packages-subscribers \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "packageId": "pKl9SW3AAAE.",
    "subscriberId": "sKl9SW3AAAE.",
    "portalId": "portal123"
  }'

Free Packages¶

Free packages are packages that are automatically available to all portal subscribers without the need for explicit assignment.

How It Works¶

Free packages are configured at the portal level:

Administrator adds a package to the portal's free packages list
All subscribers automatically receive access to channels from free packages
No explicit assignment of the package to each subscriber is required

Typical Usage:

Trial period — provide a basic set of channels to all new subscribers
Free channels — open channels available to everyone (news, public channels)
Demo content — show service capabilities before purchasing a subscription

Adding Package to Free List¶

curl -X POST https://your-catena-domain.com/tv-management/api/v1/portal/free-packages/pKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key"

After adding to the free list:

All existing and new subscribers will receive access to channels from this package
The package will be displayed as free in the portal settings

Removing Package from Free List¶

curl -X DELETE https://your-catena-domain.com/tv-management/api/v1/portal/free-packages/pKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key"

Important: Removing a package from free packages does not delete the package itself, only removes automatic access for all subscribers.

Typical Use Cases¶

Creating Basic Pricing Grid¶

Task: Create three subscription levels: Basic, Standard, Premium

Steps:

Create three packages:
basic — 30 basic channels
standard — 50 channels (basic + entertainment)
premium — 80 channels (all + sports and movies in HD)
Fill packages with channels:
Basic: news, general, music
Standard: basic + series, documentaries
Premium: standard + sports HD, movies 4K, exclusive
Set up free package:
Create a trial package with 5 open channels
Add it to the portal's free packages list
Assign packages to subscribers depending on their subscription

Thematic Packages¶

Task: Create thematic add-on packages

Package Examples:

sport-package — all sports channels
kids-package — children's channels
movies-package — movie channels
news-package — news channels

Advantages:

Subscriber can purchase topics of interest in addition to basic subscription
More flexible monetization
Personalized offering

Regional Packages¶

Task: Provide different sets of channels for different regions

Solution:

Create regional packages:
region-moscow — Moscow regional channels
region-spb — St. Petersburg channels
region-south — southern Russia channels
Assign the appropriate regional package when registering a subscriber
Subscriber will receive basic package + regional

Task: Conduct a promo campaign with extended access

Steps:

Create a temporary package promo-may
Add premium channels to it
Assign the package to all active subscribers
Remove the package from all subscribers at the end of the campaign

Best Practices¶

Planning Package Structure¶

Naming Recommendations:

Use clear technical names: basic, premium, sport-hd
Avoid using versions in the name: not premium-v2, but create a new package
Use prefixes for grouping: addon-sport, addon-kids, addon-movies

Pricing Grid Structure:

Basic level — minimum set to start using the service
Mid-level — optimal price/channel count ratio
Premium level — maximum set with all available channels
Add-on packages — thematic add-ons to main packages

Change Management¶

When changing package composition:

Inform subscribers about adding new channels
Warn in advance about removing channels from the package
Maintain documentation on each package composition
Keep history of changes for analytics

When changing pricing:

Don't change the technical package name when changing price
Use the billing system to manage prices
Ensure smooth transition for existing subscribers

Monitoring and Analytics¶

Track metrics:

Number of subscribers on each package
Channel popularity within packages
Conversion from free package to paid
Subscriber churn when changing package composition

Use data for optimization:

Form packages based on channel popularity
Test different channel combinations
Adjust package composition based on analytics results

Billing Integration¶

Recommendations:

Use technical package name (name) as identifier in billing system
Synchronize package assignment/removal with payments via API
Automate access blocking on non-payment
Set up webhooks for subscription change notifications

Troubleshooting¶

Subscriber Doesn't See Channels from Package¶

Possible causes:

Package is not assigned to subscriber
Package has no channels (empty package)
Data synchronization issues in client application

Solution:

Check subscriber's package list via API
Make sure the package contains channels
Verify that channels are properly configured on streaming server
Restart client application to update data

Channels Are Duplicated in Subscriber's List¶

Cause: Channel is included in multiple packages assigned to the subscriber

This is normal behavior:

Subscriber can have multiple packages
Channel can be included in multiple packages simultaneously
Client application should deduplicate channel list

Solution: Make sure the client application correctly handles duplicates.

Error Adding Channel to Package¶

Possible causes:

Incorrect channelId or packageId
Channel is already in this package
Channel or package belong to a different portal

Solution:

Check channel and package existence
Make sure portalId matches for channel, package and request
Check if this channel is already added to the package

Package Won't Delete¶

Possible causes:

Package is assigned to subscribers
Package is in the portal's free packages list
Insufficient permissions for deletion

Solution:

First remove the package from all subscribers
Remove package from free list (if it's there)
Then delete the package itself

Free Package Not Working¶

Possible causes:

Package is not added to portal's free packages list
Subscriber is explicitly blocked or not activated
Package is empty (contains no channels)

Solution:

Check the free packages list in portal settings
Make sure the subscriber is active
Verify the presence of channels in the package

Channel Package Management¶

What is a Channel Package¶

Main Package Parameters¶

Technical Parameters¶

Display Parameters¶

Package Content¶

Creating a Package¶

Via Web Interface¶

Via Management API¶

Viewing Package List¶

Via Web Interface¶

Via Management API¶

Getting Package Information¶

Via Management API¶

Editing a Package¶

Via Web Interface¶

Via Management API¶

Deleting a Package¶

Via Web Interface¶

Via Management API¶

Managing Package Composition¶

Adding a Channel to Package¶

Removing a Channel from Package¶

Bulk Channel Management¶

Assigning Packages to Subscribers¶

Adding a Package to Subscriber¶

Removing a Package from Subscriber¶

Free Packages¶

How It Works¶

Adding Package to Free List¶

Removing Package from Free List¶

Typical Use Cases¶

Creating Basic Pricing Grid¶

Thematic Packages¶

Regional Packages¶

Temporary Promotions¶

Best Practices¶

Planning Package Structure¶

Change Management¶

Monitoring and Analytics¶

Billing Integration¶

Troubleshooting¶

Subscriber Doesn't See Channels from Package¶

Channels Are Duplicated in Subscriber's List¶

Error Adding Channel to Package¶

Package Won't Delete¶

Free Package Not Working¶

See Also¶