04 plans

Plans are reusable subscription templates. Create a plan once, share its payment link, and let anyone subscribe.

How Plans Work

1. Merchant creates Plan → Gets shareable payment URL
2. Anyone visits URL → Enters email → Selects chain/currency
3. Subscriber approves token spending → Subscription created
4. Billing runs automatically based on plan settings

Plan vs Subscription

Concept	Description
Plan	Template (product definition) — reusable
Subscription	Instance (customer relationship) — one per subscriber

Example: One "Pro Monthly $29" plan can have 1,000 subscriptions.

---

Create Plan

POST /plans

Request

{
  "name": "Pro Monthly",
  "description": "Full access to all features",
  "amount": 29.99,
  "interval": "monthly",
  "interval_count": 1,
  "chains": ["solana", "base"],
  "currencies": ["USDC", "USDT"],
  "buffer_hours": 24,
  "trial_days": 14,
  "splits": [
    {
      "address": "partner_wallet_address",
      "chain": "solana",
      "percentage": 1000,
      "label": "Partner"
    }
  ],
  "metadata": {
    "features": ["api_access", "priority_support"]
  }
}

Parameters

Field	Type	Required	Description
name	string	✓	Plan name (max 100 chars)
description	string		Plan description (max 500 chars)
amount	number	✓	Price per billing cycle
interval	string	✓	weekly, monthly, yearly
interval_count	number		Every N intervals (default: 1)
chains	string[]		Accepted chains (default: all)
currencies	string[]		Accepted currencies (default: all)
buffer_hours	number		Escrow buffer 0-168 (default: 24)
trial_days	number		Free trial period 0-90 (default: 0)
splits	array		Revenue sharing (max 5, max 50% total)
metadata	object		Custom data

Response

{
  "success": true,
  "data": {
    "plan_id": "plan_abc123def456",
    "name": "Pro Monthly",
    "amount": 29.99,
    "interval": "monthly",
    "chains": ["solana", "base"],
    "currencies": ["USDC", "USDT"],
    "payment_url": "https://pay.stablix.xyz/subscribe/plan_abc123def456",
    "created_at": "2024-01-15T11:00:00Z"
  }
}

---

Get Plan

GET /plans/:planId

Response

{
  "success": true,
  "data": {
    "plan_id": "plan_abc123def456",
    "merchant_id": "mer_xyz789",
    "name": "Pro Monthly",
    "description": "Full access to all features",
    "amount": 29.99,
    "interval": "monthly",
    "interval_count": 1,
    "chains": ["solana", "base"],
    "currencies": ["USDC", "USDT"],
    "buffer_hours": 24,
    "trial_days": 14,
    "splits": [
      {
        "address": "partner_wallet",
        "chain": "solana",
        "percentage": 1000,
        "label": "Partner"
      }
    ],
    "is_active": true,
    "subscriber_count": 150,
    "total_revenue": 4499.50,
    "payment_url": "https://pay.stablix.xyz/subscribe/plan_abc123def456",
    "created_at": "2024-01-15T11:00:00Z"
  }
}

---

Get Plan (Public)

For embedding on your website. No authentication required.

GET /plans/public/:planId

Response

{
  "success": true,
  "data": {
    "plan_id": "plan_abc123def456",
    "name": "Pro Monthly",
    "description": "Full access to all features",
    "amount": 29.99,
    "interval": "monthly",
    "interval_count": 1,
    "chains": ["solana", "base"],
    "currencies": ["USDC", "USDT"],
    "trial_days": 14,
    "merchant": {
      "business_name": "My SaaS"
    }
  }
}

---

List Plans

GET /plans

Query Parameters

Parameter	Type	Description
is_active	boolean	Filter by active status
interval	string	Filter by interval
page	number	Page number
limit	number	Items per page (max 100)

Response

{
  "success": true,
  "data": [
    {
      "plan_id": "plan_abc123",
      "name": "Pro Monthly",
      "amount": 29.99,
      "interval": "monthly",
      "is_active": true,
      "subscriber_count": 150
    },
    {
      "plan_id": "plan_def456",
      "name": "Enterprise Yearly",
      "amount": 999.00,
      "interval": "yearly",
      "is_active": true,
      "subscriber_count": 25
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5
  }
}

---

Update Plan

Only certain fields can be updated. Pricing changes require a new plan.

PATCH /plans/:planId

Request

{
  "name": "Pro Monthly (Updated)",
  "description": "New description",
  "is_active": true,
  "metadata": { "updated": true }
}

Updatable Fields

Field	Description
name	Plan display name
description	Plan description
is_active	Enable/disable plan
metadata	Custom data

Note: Cannot update amount, interval, chains, currencies, or splits. Create a new plan instead.

Response

{
  "success": true,
  "message": "Plan updated",
  "data": {
    "plan_id": "plan_abc123",
    "name": "Pro Monthly (Updated)",
    "is_active": true
  }
}

---

Archive Plan

Deactivate a plan. Existing subscriptions continue, but no new subscriptions can be created.

POST /plans/:planId/archive

Response

{
  "success": true,
  "message": "Plan archived",
  "data": {
    "plan_id": "plan_abc123",
    "archived_at": "2024-03-01T11:00:00Z"
  }
}

---

Get Plan Stats

GET /plans/stats

Response

{
  "success": true,
  "data": {
    "total_plans": 5,
    "active_plans": 4,
    "total_subscribers": 350,
    "total_revenue": 15499.50
  }
}

---

Revenue Splits

Split revenue automatically with partners, affiliates, or team members.

Split Configuration

{
  "splits": [
    {
      "address": "partner_solana_wallet",
      "chain": "solana",
      "percentage": 1000,
      "label": "Partner (10%)"
    },
    {
      "address": "affiliate_base_wallet",
      "chain": "base",
      "percentage": 500,
      "label": "Affiliate (5%)"
    }
  ]
}

Rules

• Maximum 5 splits per plan

• Total percentage cannot exceed 50% (5000 basis points)

• Percentage in basis points: 100 = 1%, 1000 = 10%

• Split address must match the chain it's configured for

• Splits are paid on each charge release

Split Execution

When a charge is released:

$29.99 charge
├── Partner (10%): $2.999 → partner_solana_wallet
├── Affiliate (5%): $1.499 → affiliate_base_wallet
├── Platform fee (1%): $0.299 → Stablix
└── Merchant: $25.19 → merchant_wallet

---

Embedding Plans

Payment Link

Share directly or embed in buttons:

https://pay.stablix.xyz/subscribe/plan_abc123def456

Custom Button

<a href="https://pay.stablix.xyz/subscribe/plan_abc123def456" 
   class="subscribe-button">
  Subscribe for $29.99/month
</a>

Fetch Plan Details

// Fetch plan info for custom UI
const response = await fetch(
  'https://api.stablix.xyz/api/v1/plans/public/plan_abc123'
);
const { data: plan } = await response.json();

// Display
document.getElementById('plan-name').textContent = plan.name;
document.getElementById('plan-price').textContent = `$${plan.amount}/${plan.interval}`;

---

Plan Webhooks

Event	Description
plan.created	New plan created
plan.updated	Plan details updated
plan.archived	Plan archived

Example Payload

{
  "event": "plan.created",
  "data": {
    "plan_id": "plan_abc123",
    "name": "Pro Monthly",
    "amount": 29.99,
    "interval": "monthly"
  },
  "timestamp": "2024-01-15T11:00:00Z"
}

---

Best Practices

1. Create separate plans for pricing tiers — Don't update amounts, create new plans.

2. Use descriptive names — "Pro Monthly $29" is clearer than "Plan A".

3. Set appropriate trial periods — 7-14 days is typical for SaaS.

4. Configure buffer hours based on delivery — Digital: 24h, Physical: 48-168h.

5. Archive instead of delete — Keeps historical data for existing subscriptions.

6. Use metadata for internal tracking — Store feature flags, internal IDs, etc.