> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fype.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Catalog

# 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

```mermaid theme={null}
graph TD
    Merchant[Merchant Account] -->|owns| ProductFamily[Product Family e.g., SaaS Pro]
    ProductFamily -->|contains| Product[Product e.g., Core API Access]
    Product -->|has plan| Plan[Plan e.g., Monthly Plan]
    Plan -->|dictates| Price[Price e.g., ₹9,900 / month]
    Price -->|maps to| ProviderPrice[Gateway Plan Reference]
```

### 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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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
  }'
```