05 subscriptions

Create recurring payment plans using token approval model. Subscribers approve a spending limit, and Stablix charges them automatically on each billing cycle.

How Subscriptions Work

1

Merchant creates subscription

Stablix generates an approval page.

2

Subscriber connects wallet

Subscriber connects their wallet and approves token spending limit.

3

Each billing cycle

Stablix charges from the approved allowance.

4

Allowance depleted or cancelled

Subscription ends.

Subscription Lifecycle

pending_approval → active → cancelled
                        ↘ paused → active
                        ↘ past_due → active
                                  ↘ cancelled
                 → expired (approval timeout)

Status	Description
pending_approval	Awaiting subscriber wallet approval
active	Subscription is running
paused	Temporarily paused by merchant
past_due	Charge failed, retrying
cancelled	Subscription ended
expired	Approval never completed

---

Create Subscription

POST /subscriptions

Request

{
  "amount": 29.99,
  "currency": "USDC",
  "chain": "solana",
  "interval": "monthly",
  "interval_count": 1,
  "subscriber_wallet": "buyer_wallet_address",
  "subscriber_email": "[email protected]",
  "trial_days": 14,
  "billing_cycles": 12,
  "external_id": "sub_customer_123",
  "metadata": {
    "plan": "Pro",
    "customer_id": "cust_456"
  }
}

Parameters

Field	Type	Required	Description
amount	number	✓	Charge amount per cycle
currency	string	✓	USDC or USDT
chain	string	✓	solana or base
interval	string	✓	daily, weekly, monthly, yearly
interval_count	number		Every N intervals (default: 1)
subscriber_wallet	string	✓	Subscriber's wallet address
subscriber_email	string		Email for notifications
trial_days	number		Free trial period
billing_cycles	number		Max charges (null = unlimited)
external_id	string		Your internal subscription ID
metadata	object		Custom data

Response

{
  "success": true,
  "data": {
    "subscription_id": "sub_abc123def456",
    "amount": 29.99,
    "currency": "USDC",
    "chain": "solana",
    "interval": "monthly",
    "status": "pending_approval",
    "approval_url": "https://subscribe.stablix.xyz/sub_abc123def456",
    "approval_amount": 359.88,
    "approval_expires_at": "2024-01-16T11:00:00Z",
    "trial_ends_at": "2024-01-29T11:00:00Z",
    "created_at": "2024-01-15T11:00:00Z"
  }
}

Note: approval_amount is calculated as amount × 12 months to minimize approval requests.

---

Approval Flow

Step 1: Redirect Subscriber

Send your subscriber to the approval_url:

https://subscribe.stablix.xyz/sub_abc123def456

Step 2: Subscriber Connects Wallet

The subscriber connects their wallet (Phantom for Solana, MetaMask for Base).

Step 3: Subscriber Approves Spending

The subscriber signs a token approval transaction allowing Stablix to charge up to approval_amount.

Step 4: Confirmation

After approval, call the confirm endpoint:

POST /subscriptions/public/:subscriptionId/confirm

{
  "approval_tx_hash": "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp..."
}

Step 5: Subscription Activates

Once confirmed, the subscription becomes active and billing begins after any trial period.

---

Get Subscription

GET /subscriptions/:subscriptionId

Response

{
  "success": true,
  "data": {
    "subscription_id": "sub_abc123def456",
    "merchant_id": "mer_xyz789",
    "amount": 29.99,
    "currency": "USDC",
    "chain": "solana",
    "interval": "monthly",
    "status": "active",
    "subscriber": {
      "wallet": "buyer_wallet_address",
      "email": "[email protected]"
    },
    "billing": {
      "current_period_start": "2024-02-15T11:00:00Z",
      "current_period_end": "2024-03-15T11:00:00Z",
      "next_billing_date": "2024-03-15T11:00:00Z",
      "cycles_completed": 2,
      "cycles_remaining": 10,
      "total_charged": 59.98
    },
    "approval": {
      "amount": 359.88,
      "remaining": 299.90,
      "tx_hash": "approval_tx_hash..."
    },
    "trial_ends_at": null,
    "created_at": "2024-01-15T11:00:00Z"
  }
}

---

List Subscriptions

GET /subscriptions

Query Parameters

Parameter	Type	Description
status	string	Filter by status
subscriber_wallet	string	Filter by subscriber
page	number	Page number
limit	number	Items per page

Response

{
  "success": true,
  "data": [
    {
      "subscription_id": "sub_abc123",
      "amount": 29.99,
      "currency": "USDC",
      "interval": "monthly",
      "status": "active",
      "subscriber": {
        "wallet": "buyer_wallet_address"
      },
      "billing": {
        "next_billing_date": "2024-03-15T11:00:00Z"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50
  }
}

---

Pause Subscription

Temporarily stop billing. The subscriber keeps their approval.

POST /subscriptions/:subscriptionId/pause

Response

{
  "success": true,
  "message": "Subscription paused",
  "data": {
    "subscription_id": "sub_abc123",
    "status": "paused",
    "paused_at": "2024-02-01T11:00:00Z"
  }
}

---

Resume Subscription

Resume a paused subscription.

POST /subscriptions/:subscriptionId/resume

Response

{
  "success": true,
  "message": "Subscription resumed",
  "data": {
    "subscription_id": "sub_abc123",
    "status": "active",
    "resumed_at": "2024-02-15T11:00:00Z",
    "next_billing_date": "2024-03-15T11:00:00Z"
  }
}

---

Cancel Subscription

POST /subscriptions/:subscriptionId/cancel

Request

{
  "reason": "Customer requested cancellation",
  "immediate": false
}

Field	Type	Description
reason	string	Cancellation reason
immediate	boolean	Cancel now vs. end of period

Response

{
  "success": true,
  "message": "Subscription cancelled",
  "data": {
    "subscription_id": "sub_abc123",
    "status": "cancelled",
    "cancelled_at": "2024-02-01T11:00:00Z",
    "effective_at": "2024-03-15T11:00:00Z"
  }
}

---

Get Public Subscription

For approval pages. No authentication required.

GET /subscriptions/public/:subscriptionId

Response

{
  "success": true,
  "data": {
    "subscription_id": "sub_abc123",
    "merchant": {
      "business_name": "My SaaS"
    },
    "amount": 29.99,
    "currency": "USDC",
    "chain": "solana",
    "interval": "monthly",
    "status": "pending_approval",
    "approval_amount": 359.88,
    "trial_days": 14
  }
}

---

Subscription Webhooks

Stablix sends webhooks for subscription events:

Event	Description
subscription.created	Subscription created
subscription.approved	Subscriber approved spending
subscription.activated	Subscription activated
subscription.charged	Successful charge
subscription.charge_failed	Charge failed
subscription.paused	Subscription paused
subscription.resumed	Subscription resumed
subscription.cancelled	Subscription cancelled
subscription.expired	Approval expired

Example Webhook Payload

{
  "event": "subscription.charged",
  "data": {
    "subscription_id": "sub_abc123",
    "amount": 29.99,
    "currency": "USDC",
    "tx_hash": "charge_tx_hash...",
    "billing_cycle": 3,
    "next_billing_date": "2024-04-15T11:00:00Z"
  },
  "timestamp": "2024-03-15T11:00:00Z"
}

---

Handling Failed Charges

1

Subscription moves to past_due.

2

Stablix retries 3 times over 7 days.

3

After 3 failures, subscription is cancelled.

4

You receive subscription.charge_failed webhooks.

Retry Schedule

Attempt	Timing
1	Immediately
2	3 days later
3	7 days later

---

Best Practices

1

Handle approval expiration — Approvals expire in 24 hours. Send reminders.

2

Request sufficient approval — Default is 12× monthly amount. Adjust for your billing cycle.

3

Monitor failed charges — Set up alerts for subscription.charge_failed events.

4

Communicate clearly — Tell subscribers exactly what they're approving.

5

Offer trial periods — Use trial_days to reduce friction.