05 subscriptions

Subscriptions are recurring payment relationships between subscribers and plans. Create a Plan once, then anyone can subscribe via the public payment link.

How Subscriptions Work

1. Merchant creates Plan (one-time)
2. Plan gets public URL → /subscribe/plan_xxx
3. Subscriber visits → Enters email → Selects chain/currency
4. Subscriber approves token spending in wallet
5. Subscription created → Billing runs automatically

Plan vs Subscription

Concept	Description
Plan	Product template — reusable, shareable
Subscription	Customer instance — one per subscriber

See Plans for creating and managing Plans.

---

Subscription Lifecycle

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

Status	Description
pending_approval	Awaiting wallet approval
trialing	In free trial period
active	Subscription is running
paused	Temporarily paused
past_due	Charge failed, retrying
cancelled	Subscription ended
expired	Approval never completed

---

Create Subscription (Merchant API)

Pre-create a subscription for a specific user.

POST /subscriptions

Request

{
  "plan_id": "plan_abc123def456",
  "subscriber_email": "[email protected]",
  "subscriber_external_id": "cust_123",
  "metadata": {
    "source": "checkout_page"
  }
}

Parameters

Field	Type	Required	Description
plan_id	string	✓	Plan to subscribe to
subscriber_email	string	✓	Subscriber's email
subscriber_external_id	string		Your internal customer ID
metadata	object		Custom data

Response

{
  "success": true,
  "data": {
    "subscription_id": "sub_xyz789abc123",
    "plan_id": "plan_abc123def456",
    "plan_name": "Pro Monthly",
    "amount": 29.99,
    "status": "pending_approval",
    "approval_url": "https://pay.stablix.xyz/subscribe/plan_abc123def456?sub=sub_xyz789abc123",
    "created_at": "2024-01-15T11:00:00Z"
  }
}

---

Public Subscribe (Self-Service)

Anyone can subscribe via the Plan's public page.

POST /subscriptions/public/plan/:planId/subscribe

Request

{
  "email": "[email protected]",
  "external_id": "optional_external_id"
}

Response

{
  "success": true,
  "data": {
    "subscription_id": "sub_xyz789abc123",
    "plan_id": "plan_abc123def456",
    "status": "pending_approval",
    "trial_end": "2024-01-29T11:00:00Z"
  }
}

---

Approval Flow

Step 1: Subscriber Enters Email

On the plan page (/subscribe/plan_xxx), subscriber enters their email.

Step 2: Select Chain & Currency

Subscriber chooses from the plan's accepted chains and currencies.

Step 3: Connect Wallet & Approve

Subscriber connects their wallet and signs a token approval transaction.

Step 4: Confirm Approval

After wallet approval, call the confirm endpoint:

POST /subscriptions/public/:subscriptionId/confirm

{
  "chain": "solana",
  "currency": "USDC",
  "wallet_address": "subscriber_wallet_address",
  "tx_hash": "approval_tx_hash...",
  "approved_amount": 359.88,
  "expires_at": "2025-01-15T11:00:00Z"
}

Step 5: Subscription Activates

{
  "success": true,
  "message": "Subscription activated",
  "data": {
    "subscription_id": "sub_xyz789abc123",
    "status": "trialing",
    "trial_end": "2024-01-29T11:00:00Z",
    "next_charge_at": "2024-01-29T11:00:00Z"
  }
}

---

Get Subscription

GET /subscriptions/:subscriptionId

Response

{
  "success": true,
  "data": {
    "subscription_id": "sub_xyz789abc123",
    "merchant_id": "mer_abc123",
    "plan_id": "plan_abc123def456",
    "plan_snapshot": {
      "name": "Pro Monthly",
      "amount": 29.99,
      "interval": "monthly",
      "interval_count": 1,
      "buffer_hours": 24
    },
    "approved_chain": "solana",
    "approved_currency": "USDC",
    "subscriber": {
      "wallet_address": "subscriber_wallet...",
      "email": "[email protected]",
      "external_id": "cust_123"
    },
    "status": "active",
    "approval": {
      "status": "approved",
      "approved_amount": 359.88,
      "remaining_allowance": 299.90,
      "expires_at": "2025-01-15T11:00:00Z"
    },
    "billing": {
      "current_period_start": "2024-02-15T11:00:00Z",
      "current_period_end": "2024-03-15T11:00:00Z",
      "next_charge_at": "2024-03-15T11:00:00Z",
      "total_charges": 2,
      "total_released": 59.98
    },
    "trial_end": null,
    "trial_used": true,
    "created_at": "2024-01-15T11:00:00Z"
  }
}

---

Get Subscription (Public)

For approval pages. No authentication required.

GET /subscriptions/public/:subscriptionId

Response

{
  "success": true,
  "data": {
    "subscription_id": "sub_xyz789abc123",
    "plan_id": "plan_abc123def456",
    "plan_snapshot": {
      "name": "Pro Monthly",
      "amount": 29.99,
      "interval": "monthly",
      "interval_count": 1,
      "buffer_hours": 24
    },
    "status": "pending_approval",
    "trial_end": "2024-01-29T11:00:00Z"
  }
}

---

List Subscriptions

GET /subscriptions

Query Parameters

Parameter	Type	Description
status	string	Filter by status
plan_id	string	Filter by plan
chain	string	Filter by approved chain
subscriber_wallet	string	Filter by wallet
subscriber_email	string	Filter by email
page	number	Page number
limit	number	Items per page

Response

{
  "success": true,
  "data": [
    {
      "subscription_id": "sub_xyz789",
      "plan_id": "plan_abc123",
      "plan_snapshot": {
        "name": "Pro Monthly",
        "amount": 29.99
      },
      "status": "active",
      "approved_chain": "solana",
      "billing": {
        "next_charge_at": "2024-03-15T11:00:00Z"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150
  }
}

---

Pause Subscription

Temporarily stop billing. The subscriber keeps their approval.

POST /subscriptions/:subscriptionId/pause

Response

{
  "success": true,
  "message": "Subscription paused",
  "data": {
    "subscription_id": "sub_xyz789",
    "status": "paused"
  }
}

---

Resume Subscription

Resume a paused subscription.

POST /subscriptions/:subscriptionId/resume

Response

{
  "success": true,
  "message": "Subscription resumed",
  "data": {
    "subscription_id": "sub_xyz789",
    "status": "active",
    "next_charge_at": "2024-03-15T11:00:00Z"
  }
}

---

Cancel Subscription

POST /subscriptions/:subscriptionId/cancel

Request

{
  "at_period_end": true,
  "reason": "Customer requested cancellation"
}

Field	Type	Description
at_period_end	boolean	Cancel at end of period (default: true)
reason	string	Cancellation reason

Response

{
  "success": true,
  "message": "Subscription will be cancelled at period end",
  "data": {
    "subscription_id": "sub_xyz789",
    "status": "active",
    "cancel_at_period_end": true,
    "cancelled_at": null
  }
}

---

List Charges

GET /subscriptions/:subscriptionId/charges

Query Parameters

Parameter	Type	Description
escrow_status	string	Filter by pending, funded, released, refunded
page	number	Page number
limit	number	Items per page

Response

{
  "success": true,
  "data": [
    {
      "charge_id": "chg_abc123",
      "amount": 29.99,
      "fee": 0.30,
      "net_amount": 29.69,
      "escrow_status": "released",
      "escrow_tx_hash": "charge_tx_hash...",
      "release_tx_hash": "release_tx_hash...",
      "period_start": "2024-02-15T11:00:00Z",
      "period_end": "2024-03-15T11:00:00Z",
      "charged_at": "2024-02-15T11:00:00Z",
      "released_at": "2024-02-16T11:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5
  }
}

---

Refund Charge

Refund a charge that's still in escrow.

POST /subscriptions/:subscriptionId/charges/:chargeId/refund

Request

{
  "reason": "Service issue - customer requested refund"
}

Response

{
  "success": true,
  "message": "Charge refunded",
  "data": {
    "subscription_id": "sub_xyz789",
    "charge_id": "chg_abc123",
    "refund_tx_hash": "refund_tx_hash..."
  }
}

---

Subscription Webhooks

Event	Description
subscription.created	Subscription created
subscription.approved	Subscriber approved spending
subscription.charged	Successful charge
subscription.charge_failed	Charge failed
subscription.charge_released	Charge released to merchant
subscription.charge_refunded	Charge refunded
subscription.paused	Subscription paused
subscription.resumed	Subscription resumed
subscription.cancelled	Subscription cancelled
subscription.low_allowance	Allowance below 2× charge amount
subscription.approval_expiring	Approval expires within 7 days

Example Payload

{
  "event": "subscription.charged",
  "data": {
    "subscription_id": "sub_xyz789",
    "plan_id": "plan_abc123",
    "charge_id": "chg_def456",
    "amount": 29.99,
    "fee": 0.30,
    "net_amount": 29.69,
    "chain": "solana",
    "currency": "USDC",
    "escrow_tx_hash": "charge_tx_hash...",
    "release_at": "2024-02-16T11:00:00Z",
    "next_charge_at": "2024-03-15T11:00:00Z"
  },
  "timestamp": "2024-02-15T11:00:00Z"
}

---

Trial Periods

Plans can include free trial periods. During trial:

1. Subscription status is trialing

2. No charges until trial ends

3. First charge scheduled for trial_end date

{
  "status": "trialing",
  "trial_end": "2024-01-29T11:00:00Z",
  "billing": {
    "next_charge_at": "2024-01-29T11:00:00Z"
  }
}

---

Handling Failed Charges

When a charge fails:

1. Subscription moves to past_due

2. Stablix retries 3 times over 7 days

3. After 3 failures, subscription stays past_due

4. You receive subscription.charge_failed webhooks

Retry Schedule

Attempt	Timing
1	Immediately
2	24 hours later
3	48 hours later

---

Escrow & Buffer Period

Charges go into escrow before release:

1. Charge → Funds held in escrow

2. Buffer Period → buffer_hours from plan (default: 24)

3. Release → Funds sent to merchant + splits

This allows time for dispute resolution.

---

Best Practices

1. Use Plans — Create plans and share payment links instead of creating subscriptions manually.

2. Set appropriate trials — 7-14 day trials reduce friction.

3. Monitor webhooks — Handle charge_failed and low_allowance events.

4. Communicate with subscribers — Send emails before charges and when issues occur.

5. Use external_id — Link subscriptions to your internal customer records.