Subscriptions Catalog: Products, Families, Plans & Prices

The catalog structure in Fype allows you to separate the marketing structure of your offering from its pricing and feature authorization.

Catalog Hierarchy Model

1. Product Families

A Product Family represents a category of related products or business lines (e.g., “Developer Suite”, “Enterprise Addons”).

Purpose: Groups products to organize offerings and prevent entitlement overlaps.

2. Products

A Product represents a sellable entity in your application (e.g., “Pro Tier”, “Premium Support”).

Attributes:
- name: Marketing name displayed during checkout.
- type: subscription (recurring) or one_time (non-recurring).
- status: active or inactive.

3. Plans

A Plan defines the recurrence rules, intervals, and trial periods for a subscription product.

Attributes:
- billing_frequency: Cadence unit (daily, weekly, monthly, yearly).
- billing_interval: Number of cadences between charges (e.g., 3 months = quarterly).
- trial_period_days: Free trial period duration in days (default: 0).
- trial_end_action: The action to take when the trial ends (e.g., start_subscription).

4. Prices

A Price represents the currency, amount, and gateway mapping details for a specific billing Plan.

Attributes:
- currency: 3-letter currency code (e.g., INR).
- amount: Charged amount in the smallest currency subunits (e.g., Paise for INR: 99900 = ₹999.00).
- setup_fee: One-time setup fee in subunits (default: 0).
- is_default: Flag indicating the primary default price.
- provider_price_ids: Dictionary caching the registered gateway IDs (e.g., {"razorpay": "plan_Nz9823hJ", "cashfree": "cf_plan_8a123"}).

Lazy Gateway Plan Synchronization

When you create a subscription, Fype automatically checks if the targeted Plan and Price have already been registered on the payment gateway (e.g. Razorpay or Cashfree). If the plan does not exist on the gateway yet, Fype automatically registers it on-the-fly (lazy registration) before initiating the checkout session. This lazy synchronization provides several benefits:

Zero Pre-registration Overhead: Define plans in the Fype dashboard or via API once. Fype handles gateway-specific API registrations automatically when the first customer chooses that plan.
Subunit Safety: Converts billing amounts to the gateway’s expected subunit structure (e.g. Paise for INR) automatically.

API Examples

Create a Product

curl -X POST https://api.fype.dev/v1/products \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Developer Pro Suite",
    "description": "Access to advanced developer tools & metrics API",
    "type": "subscription"
  }'

Create a Plan under the Product

curl -X POST https://api.fype.dev/v1/products/{product_uuid}/plans \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Developer Plan",
    "billing_frequency": "monthly",
    "billing_interval": 1,
    "trial_period_days": 14
  }'

Create a Price point for the Plan

curl -X POST https://api.fype.dev/v1/plans/{plan_uuid}/prices \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "INR",
    "amount": 99900,
    "setup_fee": 10000,
    "is_default": true
  }'

​Subscriptions Catalog: Products, Families, Plans & Prices

​Catalog Hierarchy Model

​1. Product Families

​2. Products

​3. Plans

​4. Prices

​Lazy Gateway Plan Synchronization

​API Examples

​Create a Product

​Create a Plan under the Product

​Create a Price point for the Plan