Create Plans (API)

Create and configure subscription plans programmatically using the Flintn API.

Prerequisites

An API key with the subscription_plan.write permission. See Authentication.

API Endpoints

Method	Endpoint	Description
POST	/v1/subscription-plans	Create a new plan
GET	/v1/subscription-plans/{id}	Retrieve a single plan
GET	/v1/subscription-plans	List all plans
PUT	/v1/subscription-plans/{id}	Update a plan
DELETE	/v1/subscription-plans/{id}	Delete a plan (soft delete)
POST	/v1/subscription-plans/{id}/activate	Activate a draft plan
POST	/v1/subscription-plans/{id}/deactivate	Deactivate an active plan
POST	/v1/subscription-plans/search	Search plans with filters
GET	/v1/subscription-plans/product-urls	Get available product URLs

Request Fields

Field	Type	Required	Description
type	string	Yes	Plan type (see below)
name	string	Yes	Display name (max 50 characters, must be unique per merchant)
description	string	No	Plan description (max 500 characters)
website_url	string	Yes	Associated website URL (select from available product URLs)
currency	string	Yes	Three-letter currency code (USD, EUR, GBP)
full_price_amount	number	Yes	Regular billing amount (max 2 decimal places)
billing_frequency_value	integer	Yes*	Number of time units between billings (1-999)
billing_frequency_unit	string	Yes*	Time unit: DAYS, WEEKS, MONTHS
trial_price_amount	number	No	Amount for paid trials
trial_period_value	integer	No	Length of trial period
trial_period_unit	string	No	Trial unit: DAYS, WEEKS, MONTHS
settlement_interval_hours	integer	Yes	Hours before auto-capture (see limits below)
trial_settlement_interval_hours	integer	Yes**	Hours before trial payment capture (max 239)
retry_strategy_id	integer	No	Retry strategy ID (valid range: 1-23)
status	string	No	DRAFT (default) or ACTIVE

*Required for subscription types, not for ONE_TIME.

**Required for SUBSCRIPTION_PAID_TRIAL type only.

Settlement Interval Limits

Plan Type	Max Settlement Hours	Transaction Type
ONE_TIME	239	CIT (Customer Initiated)
SUBSCRIPTION_NO_TRIAL	119	MIT (Merchant Initiated)
SUBSCRIPTION_FREE_TRIAL	119	MIT (Merchant Initiated)
SUBSCRIPTION_PAID_TRIAL	119 (regular), 239 (trial)	MIT/CIT

Plan Types

Type	Description
ONE_TIME	Single purchase
SUBSCRIPTION_NO_TRIAL	Immediate billing
SUBSCRIPTION_FREE_TRIAL	Free trial first
SUBSCRIPTION_PAID_TRIAL	Discounted trial first

Response Fields

Field	Type	Description
id	string (UUID)	Unique plan identifier
type	string	Plan type
name	string	Display name
description	string	Plan description
website_url	string	Associated website URL
currency	string	Three-letter currency code
full_price_amount	number	Regular billing amount
billing_frequency_value	integer	Billing frequency value
billing_frequency_unit	string	Billing frequency unit
trial_price_amount	number	Trial price (if applicable)
trial_period_value	integer	Trial period value
trial_period_unit	string	Trial period unit
settlement_interval_hours	integer	Settlement interval
trial_settlement_interval_hours	integer	Trial settlement interval (paid trial only)
retry_strategy_id	integer	Retry strategy ID
status	string	Plan status
active_subscriptions_count	integer	Number of active subscriptions
created_at	string	ISO 8601 timestamp
created_by	string	User who created the plan
updated_at	string	ISO 8601 timestamp
updated_by	string	User who last updated the plan

Examples

Monthly Subscription (No Trial)

curl -X POST https://api.flintn.com/v1/subscription-plans \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SUBSCRIPTION_NO_TRIAL",
    "name": "Monthly Pro",
    "description": "Full access to all Pro features",
    "website_url": "https://example.com",
    "currency": "USD",
    "full_price_amount": 29.99,
    "billing_frequency_value": 1,
    "billing_frequency_unit": "MONTHS",
    "settlement_interval_hours": 48,
    "retry_strategy_id": 5,
    "status": "ACTIVE"
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "SUBSCRIPTION_NO_TRIAL",
  "name": "Monthly Pro",
  "description": "Full access to all Pro features",
  "website_url": "https://example.com",
  "currency": "USD",
  "full_price_amount": 29.99,
  "billing_frequency_value": 1,
  "billing_frequency_unit": "MONTHS",
  "settlement_interval_hours": 48,
  "retry_strategy_id": 5,
  "status": "ACTIVE",
  "active_subscriptions_count": 0,
  "created_at": "2024-01-15T10:30:00Z",
  "created_by": "[e-mail]",
  "updated_at": "2024-01-15T10:30:00Z",
  "updated_by": "[e-mail]"
}

Monthly Subscription with Free Trial

curl -X POST https://api.flintn.com/v1/subscription-plans \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SUBSCRIPTION_FREE_TRIAL",
    "name": "Premium with Trial",
    "description": "Premium features with 14-day free trial",
    "website_url": "https://example.com",
    "currency": "USD",
    "full_price_amount": 49.99,
    "billing_frequency_value": 1,
    "billing_frequency_unit": "MONTHS",
    "trial_period_value": 14,
    "trial_period_unit": "DAYS",
    "settlement_interval_hours": 72,
    "retry_strategy_id": 9,
    "status": "ACTIVE"
  }'

Monthly Subscription with Paid Trial

curl -X POST https://api.flintn.com/v1/subscription-plans \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SUBSCRIPTION_PAID_TRIAL",
    "name": "Premium Monthly",
    "description": "Try premium for $1 for the first month",
    "website_url": "https://example.com",
    "currency": "USD",
    "full_price_amount": 49.99,
    "trial_price_amount": 1.00,
    "billing_frequency_value": 1,
    "billing_frequency_unit": "MONTHS",
    "trial_period_value": 1,
    "trial_period_unit": "MONTHS",
    "settlement_interval_hours": 72,
    "trial_settlement_interval_hours": 120,
    "retry_strategy_id": 5,
    "status": "ACTIVE"
  }'

One-Time Purchase

curl -X POST https://api.flintn.com/v1/subscription-plans \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ONE_TIME",
    "name": "Lifetime Access",
    "description": "One-time purchase for lifetime access",
    "website_url": "https://example.com",
    "currency": "USD",
    "full_price_amount": 499.00,
    "settlement_interval_hours": 120,
    "status": "ACTIVE"
  }'

Weekly Billing

curl -X POST https://api.flintn.com/v1/subscription-plans \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SUBSCRIPTION_NO_TRIAL",
    "name": "Weekly Basic",
    "website_url": "https://example.com",
    "currency": "USD",
    "full_price_amount": 9.99,
    "billing_frequency_value": 1,
    "billing_frequency_unit": "WEEKS",
    "settlement_interval_hours": 24,
    "retry_strategy_id": 1,
    "status": "ACTIVE"
  }'

Retrieving Plans

Get a Single Plan

curl -X GET https://api.flintn.com/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

List All Plans

curl -X GET "https://api.flintn.com/v1/subscription-plans?page=0&size=10" \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Pagination Parameters

Parameter	Type	Default	Description
page	integer	0	Page number (zero-based)
size	integer	10	Items per page (max 100)

Search Plans

curl -X POST https://api.flintn.com/v1/subscription-plans/search \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ACTIVE",
    "type": "SUBSCRIPTION_NO_TRIAL"
  }'

Get Available Product URLs

curl -X GET https://api.flintn.com/v1/subscription-plans/product-urls \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Updating Plans

Use PUT to update an existing plan:

curl -X PUT https://api.flintn.com/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SUBSCRIPTION_NO_TRIAL",
    "name": "Monthly Pro (Updated)",
    "description": "Updated description",
    "website_url": "https://example.com",
    "currency": "USD",
    "full_price_amount": 29.99,
    "billing_frequency_value": 1,
    "billing_frequency_unit": "MONTHS",
    "settlement_interval_hours": 48,
    "retry_strategy_id": 5
  }'

Edit Restrictions

Plan Status	Editable Fields
DRAFT	All fields
ACTIVE (no subscriptions)	All fields except type
ACTIVE (with subscriptions)	name, description, retry_strategy_id only

Activating and Deactivating Plans

Activate a Draft Plan

curl -X POST https://api.flintn.com/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440000/activate \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Deactivate a Plan

curl -X POST https://api.flintn.com/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440000/deactivate \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Note: Deactivating a plan stops new subscriptions but does not affect existing subscriptions.

Deleting Plans

Soft delete a plan (can only delete plans with no active subscriptions):

curl -X DELETE https://api.flintn.com/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Error Responses

400 Bad Request

Invalid request body or missing required fields:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "/v1/subscription-plans",
  "message": "Validation failed: website_url is required",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.123456Z",
  "errors": [
    {
      "field": "website_url",
      "message": "website_url is required"
    }
  ]
}

403 Forbidden

API key lacks subscription_plan.write permission:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "/v1/subscription-plans",
  "message": "Insufficient permissions for this operation",
  "code": "FORBIDDEN",
  "timestamp": "2024-01-15T10:30:00.123456Z"
}

404 Not Found

Plan does not exist:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440000",
  "message": "Subscription plan not found",
  "code": "NOT_FOUND",
  "timestamp": "2024-01-15T10:30:00.123456Z"
}

409 Conflict

Duplicate plan name:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "/v1/subscription-plans",
  "message": "A subscription plan with this name already exists",
  "code": "CONFLICT",
  "timestamp": "2024-01-15T10:30:00.123456Z"
}

Next Steps

• Create Plans via Dashboard - Visual plan creation

• Subscription Plans Concept - Understand plan configuration

• Retry Strategies - Choose the right retry strategy

• Subscription Payments Quickstart - Use your plan