Subscriptions

Create subscription plans and manage recurring billing on Solana.

Subscriptions

Subscriptions let you set up recurring billing. You define a plan with an amount and interval, then customers subscribe to it. ZendFi automatically creates payments when they are due and sends webhook events so you can track the lifecycle.

Subscription Plans

Create a Subscription Plan

POST /api/v1/subscription-plans

name · string · required

Plan name shown to customers.

description · string

Plan description.

amount · number · required

Recurring amount per billing cycle.

currency · string · default: "USD"

Currency code.

billing_interval · string · required

Billing interval: daily, weekly, monthly, yearly.

interval_count · integer · default: "1"

Number of intervals between billings. For example, billing_interval: "monthly" with interval_count: 3 bills quarterly.

trial_days · integer · default: "0"

Number of trial days before the first billing.

max_cycles · integer

Maximum number of billing cycles. Omit for unlimited.

metadata · object

Arbitrary key-value pairs.

Example

cURL

curl -X POST https://api.zendfi.tech/api/v1/subscription-plans \
  -H "Authorization: Bearer zfi_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Plan",
    "description": "Full access to all features",
    "amount": 29.99,
    "billing_interval": "monthly",
    "trial_days": 14
  }'

Response

{
  "id": "plan_test_abc123",
  "merchant_id": "merch_xyz789",
  "name": "Pro Plan",
  "description": "Full access to all features",
  "amount": 29.99,
  "currency": "USD",
  "billing_interval": "monthly",
  "interval_count": 1,
  "trial_days": 14,
  "max_cycles": null,
  "is_active": true,
  "created_at": "2026-03-01T12:00:00Z",
  "subscription_url": "https://checkout.zendfi.tech/subscription/plan_test_abc123"
}

List Subscription Plans

GET /api/v1/subscription-plans

Returns all plans for the authenticated merchant.

Get a Subscription Plan

GET /api/v1/subscription-plans/{plan_id}

This endpoint is public — no authentication required. This allows customers to view plan details before subscribing.

---

Customer Subscriptions

Create a Subscription

POST /api/v1/subscriptions

Subscribes a customer to a plan.

plan_id · string · required

The subscription plan ID (UUID).

customer_wallet · string · required

Customer’s Solana wallet address.

customer_email · string

Customer email for notifications and receipts.

metadata · object

Arbitrary key-value pairs.

Example

cURL

curl -X POST https://api.zendfi.tech/api/v1/subscriptions \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan_test_abc123",
    "customer_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "customer_email": "[e-mail]"
  }'

Get a Subscription

GET /api/v1/subscriptions/{id}

Returns subscription details including current period and status.

Cancel a Subscription

POST /api/v1/subscriptions/{id}/cancel

Cancels the subscription. The customer retains access until the end of the current billing period.

Pay a Subscription

POST /api/v1/subscriptions/{id}/pay

Creates a payment for the current billing period. ZendFi calls this automatically, but you can trigger it manually if needed.

---

Subscription Lifecycle

Status	Description
active	Subscription is active and billing normally
trialing	Subscription is in its trial period
past_due	Most recent payment failed, retrying
paused	Temporarily paused
cancelled	Subscription has been cancelled
expired	Subscription has expired

Webhook Events

Event	When
SubscriptionCreated	New subscription created
SubscriptionRenewed	Subscription renewed for next billing period
SubscriptionCancelled	Subscription cancelled
SubscriptionPaymentFailed	Recurring payment attempt failed

See the Subscriptions guide for an end-to-end implementation walkthrough.