API Reference

The fype API is organized around REST. All requests should be made to https://api.fype.dev/v1.

Payments

Create a Payment

POST /payments Create a new payment and generate a hosted checkout URL. Request Body

Field	Type	Required	Description
`amount`	integer	Yes	Amount in subunits (e.g., 50000 for ₹500.00). Min 100.
`currency`	string	Yes	3-letter ISO currency code. Default `INR`.
`customer_email`	string	Yes	Email address of the customer.
`customer_phone`	string	No	Phone number of the customer.
`customer_name`	string	No	Full name of the customer.
`reference_id`	string	No	Your internal order/transaction ID.
`success_url`	string	Yes	URL to redirect to after successful payment. Supports `{CHECKOUT_SESSION_ID}` and `{PAYMENT_ID}` placeholders.
`cancel_url`	string	Yes	URL to redirect to if the customer cancels.
`provider`	string	No	Explicitly choose a payment gateway (`razorpay` or `cashfree`). If omitted, Fype uses the default gateway routing logic.
`metadata`	object	No	Key-value pairs for your own tracking.

Headers

Authorization: Bearer <API_KEY>
Idempotency-Key: <UNIQUE_STRING> (Optional but recommended)

Retrieve a Payment

GET /payments/{payment_id} Get the current status and details of a payment.

List Payments

GET /payments List all payments for your merchant account. Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Number of results to return.
`cursor`	string	null	Cursor for pagination.

Refunds

Create a Refund

POST /payments/{payment_id}/refund Initiate a full or partial refund for a successful payment. Request Body

Field	Type	Required	Description
`amount`	integer	No	Amount to refund. If omitted, a full refund is processed.

Webhook Endpoints

Create Endpoint

POST /webhooks/endpoints Request Body

Field	Type	Required	Description
`url`	string	Yes	The URL where fype should send events.
`mode`	string	Yes	`test` or `live`.

List Endpoints

GET /webhooks/endpoints

Delete Endpoint

DELETE /webhooks/endpoints/{endpoint_id}

Toggle Endpoint

POST /webhooks/endpoints/{endpoint_id}/toggle Enable or disable a webhook endpoint.

List Deliveries

GET /webhooks/deliveries List recent webhook delivery attempts and their statuses.

Trigger Test Webhook

POST /webhooks/trigger-test Trigger a simulated payment.succeeded event to your test endpoints.

Providers

Connect Provider

POST /providers/connections Connect a payment gateway (Razorpay or Cashfree) to your account. Request Body

Field	Type	Required	Description
`provider`	string	Yes	`razorpay` or `cashfree`.
`mode`	string	Yes	`test` or `live`.
`credentials`	object	Yes	Key-value pairs of gateway-specific credentials.

List Connections

GET /providers/connections

Delete Connection

DELETE /providers/connections/{connection_id}

Products & Catalog

Create Product

POST /products Create a new product in the merchant’s catalog. Request Body

Field	Type	Required	Description
`name`	string	Yes	The product’s name (min 2, max 255 chars).
`description`	string	No	Optional description of the product.
`type`	string	No	Either `subscription` or `one_time`. Default is `subscription`.
`status`	string	No	`active` or `inactive`. Default is `active`.
`product_family_id`	string (UUID)	No	Optional ID linking to a product family.
`metadata_json`	object	No	Optional key-value pairs of metadata.

List Products

GET /products Retrieve all products in your catalog, along with their nested plans and default prices.

Retrieve Product

GET /products/{id} Retrieve details for a single product.

Create Plan

POST /products/{id}/plans Create a billing plan (billing cadence/intervals) under a specific product. Request Body

Field	Type	Required	Description
`name`	string	Yes	Plan name (min 2, max 255 chars).
`description`	string	No	Optional description of the plan.
`billing_frequency`	string	No	Recurrence unit: `daily`, `weekly`, `monthly`, `yearly`. Default is `monthly`.
`billing_interval`	integer	No	Recurrence frequency interval (e.g., 3 with monthly = quarterly). Default is `1`.
`trial_period_days`	integer	No	Free trial period duration in days (min 0). Default is `0`.
`trial_end_action`	string	No	Action on trial end (e.g. `start_subscription`). Default is `start_subscription`.
`status`	string	No	`active` or `inactive`. Default is `active`.
`metadata_json`	object	No	Optional metadata.

Retrieve Plan

GET /plans/{id} Retrieve details of a single billing plan.

Create Price

POST /plans/{id}/prices Configure a price point for a specific billing plan. Request Body

Field	Type	Required	Description
`currency`	string	No	3-letter currency code. Default is `INR`.
`amount`	integer	Yes	Price amount in subunits (e.g., 99900 for ₹999.00).
`setup_fee`	integer	No	One-time setup fee in subunits. Default is `0`.
`is_default`	boolean	No	Whether this is the default price for the plan. Default is `false`.
`provider_price_ids`	object	No	Mapping of third-party gateway specific plan/price IDs.

Create Entitlement

POST /entitlements Create a feature authorization gate. Request Body

Field	Type	Required	Description
`identifier`	string	Yes	Unique URL-safe identifier/slug (e.g., `premium_analytics`).
`name`	string	Yes	Descriptive name of the entitlement.
`description`	string	No	Optional description.
`metadata_json`	object	No	Optional metadata.

List Entitlements

GET /entitlements

Link Entitlement to Product

POST /entitlements/{id}/products Link a feature gate to a product. Request Body

Field	Type	Required	Description
`product_id`	string (UUID)	Yes	The ID of the product to link this entitlement to.

Subscriptions

Create Subscription

POST /subscriptions Creates a new subscription locally, registers it lazily at the payment provider gateway, and registers a checkout session returning the mandate hosted checkout URL. Headers

Authorization: Bearer <API_KEY>
Idempotency-Key: <UNIQUE_STRING> (Optional but recommended to prevent double-mandating)

Request Body

Field	Type	Required	Description
`customer_email`	string	Yes	Customer’s email address.
`customer_name`	string	No	Customer’s full name.
`customer_phone`	string	No	Customer’s phone number.
`plan_id`	string (UUID)	Yes	Plan ID to subscribe to.
`price_id`	string (UUID)	Yes	Price ID to subscribe to.
`quantity`	integer	No	Quantity of plans (for seat-based billing). Default is `1`.
`provider`	string	No	The target gateway (`razorpay`, `cashfree`, or `simulator`). Default is `simulator`.
`success_url`	string	Yes	Redirect URL after successful checkout session mandate authorization. Supports `{CHECKOUT_SESSION_ID}` and `{SUBSCRIPTION_ID}`.
`cancel_url`	string	Yes	Redirect URL when checkout session is cancelled/abandoned.
`metadata`	object	No	Key-value pairs for your tracking.

Retrieve Subscription

GET /subscriptions/{id} Retrieve the current details, billing periods, trial info, and provider references for a single subscription.

List Subscriptions

GET /subscriptions Retrieve paginated subscriptions with cursor pagination. Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Number of results to return. Default is `20`.
`cursor`	string	No	Pagination cursor returned from previous responses.
`customer_id`	string (UUID)	No	Filter subscriptions by customer ID.

Pause Subscription

POST /subscriptions/{id}/pause Temporarily pause an active subscription. Deactivates recurring charging.

Resume Subscription

POST /subscriptions/{id}/resume Resume charging on a paused subscription.

Cancel Subscription

POST /subscriptions/{id}/cancel Cancel a subscription. Query Parameters

Parameter	Type	Required	Description
`cancel_at_period_end`	boolean	No	If `true`, schedules cancellation at current period end. If `false`, cancels immediately. Default is `false`.

Change Subscription Plan (Upgrade/Downgrade)

POST /subscriptions/{id}/change-plan Upgrade or downgrade a subscription mid-cycle. Calculates proration credits and debits, issues an adjustment invoice/credit-note, and synchronizes the plan with the gateway. Request Body

Field	Type	Required	Description
`plan_id`	string (UUID)	Yes	The target plan ID.
`price_id`	string (UUID)	Yes	The target price ID.

Retrieve Subscription Events

GET /subscriptions/{id}/events Retrieve the state transition history of a subscription.

Retrieve Customer Entitlements

GET /subscriptions/customer/{customer_id}/entitlements Evaluate and retrieve all active feature gates (entitlements) for a customer across all their active or trialing subscriptions. Response Body

{
 "customer_id": "d80b62e4-9d33-4f9e-a0e2-88229b4fb712",
 "active_entitlements": ["api_access", "dashboard_visuals"]
}

Offerings & Paywalls

Create Offering

POST /offerings Request Body

Field	Type	Required	Description
`identifier`	string	Yes	Unique ID for the offering (e.g., `winter_sale`).
`description`	string	No	Description.
`is_default`	boolean	No	Default offering flag.
`targeting_rules`	object	No	Key-value targeting conditions.
`status`	string	No	`active` or `inactive`.

Attach Package to Offering

POST /offerings/{id}/packages Request Body

Field	Type	Required	Description
`package_id`	string (UUID)	Yes	The ID of the package.
`display_order`	integer	No	Ordering value. Default is `0`.

Create Package

POST /packages Request Body

Field	Type	Required	Description
`identifier`	string	Yes	Unique bundle identifier (e.g., `pro_monthly_bundle`).
`package_type`	string	Yes	`monthly`, `yearly`, or `lifetime`.
`description`	string	No	Description.

Link Product to Package

POST /packages/{id}/products Request Body

Field	Type	Required	Description
`product_id`	string (UUID)	Yes	The ID of the product to link.

Create Paywall

POST /paywalls Request Body

Field	Type	Required	Description
`name`	string	Yes	Descriptive name of paywall layout.
`template_type`	string	No	`simple`, `feature_comparison`, or `sliding_cards`.
`configuration`	object	Yes	Visual parameters and styling.
`offering_id`	string (UUID)	No	Mapped offering ID.

Coupons & Discounts

Create Coupon

POST /coupons Request Body

Field	Type	Required	Description
`code`	string	Yes	Promo code (e.g. `SAVE20`).
`type`	string	Yes	Discount type: `percentage` or `fixed`.
`value`	integer	Yes	Percentage or fixed amount in subunits.
`duration`	string	No	`once`, `forever`, `repeating`.
`max_redemptions`	integer	No	Limit on coupon uses.

Validate Coupon

POST /coupons/validate Request Body

Field	Type	Required	Description
`code`	string	Yes	Promo code to validate.
`price_id`	string (UUID)	No	Optional targeted price ID.

Metered Billing (Usage)

Report Usage Event

POST /usage/events Submit consumption event. Request Body

Field	Type	Required	Description
`subscription_id`	string (UUID)	Yes	Targeted subscription.
`event_type`	string	Yes	Metric unit (e.g., `api_tokens`).
`quantity`	float	Yes	Quantity consumed.
`unit`	string	No	Metric name (e.g., `tokens`).

Retrieve Usage Summary

GET /usage/summary Retrieve aggregated consumption metrics. Query Parameters

Parameter	Type	Required	Description
`subscription_id`	string (UUID)	Yes	Mapped subscription ID.

Growth & Experiments

Create Experiment

POST /experiments Request Body

Field	Type	Required	Description
`name`	string	Yes	Name of experiment.
`type`	string	No	`paywall`, `pricing`, `catalog`.
`variants`	list	Yes	Cohort variants with allocations summing to 100%.
`targeting_conditions`	object	No	Mapped rules for bucketing.

Start / Stop Experiment

POST /experiments/{id}/start POST /experiments/{id}/stop Toggle running status of A/B test.

Retrieve Experiment Results

GET /experiments/{id}/results Fetches visitors, conversions, and Bayesian Chance to Win scores.

Resolve Dynamic Offering

POST /offerings/resolve Resolves the customized paywall and offering matching targeted attributes and bucketing enrollments. Request Body

Field	Type	Required	Description
`customer_id`	string (UUID)	Yes	Mapped customer profile.
`attributes`	object	No	Targeting attributes dictionary.

Customers

List Customers

GET /customers Retrieve paginated customer directories for the merchant. Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Number of results to return. Default is `20`.
`cursor`	string	No	Pagination cursor returned from previous responses.
`search`	string	No	Search query to filter customers by name or email.

Retrieve Customer

GET /customers/{id} Retrieve detailed information about a single customer, including active subscription counts and total lifetime revenue.

Invoices

List Invoices

GET /invoices Retrieve paginated invoices for the merchant. Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Number of results to return. Default is `20`.
`cursor`	string	No	Pagination cursor returned from previous responses.
`customer_id`	string (UUID)	No	Filter invoices by customer ID.
`subscription_id`	string (UUID)	No	Filter invoices by subscription ID.
`status`	string	No	Filter invoices by status (e.g. `paid`, `open`, `draft`, etc.).

Retrieve Invoice

GET /invoices/{id} Retrieve detailed information about a single invoice, including CGST, SGST, IGST, and line-item breakdowns.

Billing & Subscription Analytics

Retrieve MRR Metrics

GET /analytics/mrr Retrieve Monthly Recurring Revenue (MRR) summaries, including active MRR breakdown, upgrades, downgrades, churn, and new additions.

Retrieve Churn Metrics

GET /analytics/churn Retrieve subscription churn metrics and customer churn rates for current billing periods.

Retrieve Cohort Retention Analysis

GET /analytics/cohorts Retrieve cohort user retention matrices and heatmaps based on subscription activation dates.

Retrieve Customer LTV Metrics

GET /analytics/ltv Retrieve customer Lifetime Value (LTV) analytics, average revenue per user (ARPU), and lifetime projections.

Retrieve Quick Ratio

GET /analytics/quick-ratio Retrieve SaaS Quick Ratio metrics measuring monthly revenue growth efficiency.

Retrieve Autopay Analytics

GET /analytics/autopay Retrieve success rates and analytics for auto-debit payments and recurring payment mandates. |

​API Reference

​Payments

​Create a Payment

​Retrieve a Payment

​List Payments

​Refunds

​Create a Refund

​Webhook Endpoints

​Create Endpoint

​List Endpoints

​Delete Endpoint

​Toggle Endpoint

​List Deliveries

​Trigger Test Webhook

​Providers

​Connect Provider

​List Connections

​Delete Connection

​Products & Catalog

​Create Product

​List Products

​Retrieve Product

​Create Plan

​Retrieve Plan

​Create Price

​Create Entitlement

​List Entitlements

​Link Entitlement to Product

​Subscriptions

​Create Subscription

​Retrieve Subscription

​List Subscriptions

​Pause Subscription

​Resume Subscription

​Cancel Subscription

​Change Subscription Plan (Upgrade/Downgrade)

​Retrieve Subscription Events

​Retrieve Customer Entitlements

​Offerings & Paywalls

​Create Offering

​Attach Package to Offering

​Create Package

​Link Product to Package

​Create Paywall

​Coupons & Discounts

​Create Coupon

​Validate Coupon

​Metered Billing (Usage)

​Report Usage Event

​Retrieve Usage Summary

​Growth & Experiments

​Create Experiment

​Start / Stop Experiment

​Retrieve Experiment Results

​Resolve Dynamic Offering

​Customers

​List Customers

​Retrieve Customer

​Invoices

​List Invoices

​Retrieve Invoice

​Billing & Subscription Analytics

​Retrieve MRR Metrics

​Retrieve Churn Metrics

​Retrieve Cohort Retention Analysis

​Retrieve Customer LTV Metrics

​Retrieve Quick Ratio

​Retrieve Autopay Analytics