All Endpoints

Complete reference of all API endpoints in Subscriptions Manager.

Quick Reference

Method	Endpoint	Auth	Description
GET	/api/v1/plans	Invoice	List all plans
POST	/api/v1/plans	Admin	Create a plan
GET	/api/v1/plans/{id}	Invoice	Get plan details
PUT	/api/v1/plans/{id}	Admin	Update a plan
DELETE	/api/v1/plans/{id}	Admin	Archive a plan
GET	/api/v1/subscriptions	Invoice	List subscriptions
GET	/api/v1/subscriptions/{id}	Invoice	Get subscription
PUT	/api/v1/subscriptions/{id}	Admin	Update subscription
POST	/api/v1/subscriptions/{id}/cancel	Admin	Cancel subscription
POST	/api/v1/subscriptions/{id}/pause	Admin	Pause subscription
POST	/api/v1/subscriptions/{id}/resume	Admin	Resume subscription
GET	/api/v1/subscribers	Invoice	List subscribers
GET	/api/v1/subscribers/{id}	Invoice	Get subscriber
GET	/api/v1/payments	Invoice	List payments
GET	/api/v1/payments/{id}	Invoice	Get payment details
GET	/public/plan/{id}	None	Public plan info
POST	/public/subscribe/{plan_id}	None	Create subscription
GET	/public/checkout/{subscription_id}	None	Get checkout page
POST	/public/webhook/satspay	None	SatsPay callback
POST	/public/webhook/stripe	None	Stripe callback
POST	/public/webhook/paypal	None	PayPal callback

Plans

Manage subscription plans.

GET/api/v1/plans

Description: List all active plans for the authenticated wallet.

Auth: Invoice Key

Response:

[
  {
    "id": "abc123",
    "name": "Pro Plan",
    "amount_sats": 10000,
    "interval": "monthly",
    "allow_lightning": true,
    "allow_onchain": false,
    "allow_stripe": true,
    "allow_paypal": false
  }
]

POST/api/v1/plans

Description: Create a new subscription plan.

Auth: Admin Key

Body:

{
  "name": "Pro Plan",
  "amount_sats": 10000,
  "interval": "monthly",
  "description": "Access to premium features",
  "trial_days": 7,
  "grace_period_days": 3,
  "allow_lightning": true,
  "allow_onchain": false,
  "allow_stripe": true,
  "allow_paypal": false
}

Parameters:

Field	Type	Required	Description
name	string	Yes	Plan display name
amount_sats	integer	Yes	Price in satoshis
interval	string	Yes	weekly, monthly, or yearly
description	string	No	Shown on checkout page
trial_days	integer	No	Free trial period (default: 0)
grace_period_days	integer	No	Days after failed payment (default: 0)
allow_lightning	boolean	No	Enable Lightning payments (default: true)
allow_onchain	boolean	No	Enable on-chain Bitcoin (default: false)
allow_stripe	boolean	No	Enable Stripe cards/Apple Pay/Google Pay
allow_paypal	boolean	No	Enable PayPal payments

GET/api/v1/plans/{id}

Description: Get details for a specific plan.

Auth: Invoice Key

Path Parameters:

• id - Plan ID

PUT/api/v1/plans/{id}

Description: Update an existing plan. Only include fields you want to change.

Auth: Admin Key

Note: Price changes only affect new subscriptions. Existing subscribers keep their original price.

DELETE/api/v1/plans/{id}

Description: Archive a plan and cancel all active subscriptions. Subscribers are notified.

Auth: Admin Key

Warning: This action cannot be undone.

Subscriptions

Manage subscriber subscriptions.

GET/api/v1/subscriptions

Description: List all subscriptions for your plans.

Auth: Invoice Key

Query Parameters:

• plan_id (optional) - Filter by plan
• status (optional) - Filter by status (active, paused, cancelled, etc.)

GET/api/v1/subscriptions/{id}

Description: Get details for a specific subscription including payment history.

Auth: Invoice Key

PUT/api/v1/subscriptions/{id}

Description: Update subscription metadata or settings.

Auth: Admin Key

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

Description: Cancel a subscription. Access continues until end of current period.

Auth: Admin Key

Body (optional):

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

Field	Type	Description
reason	string	Cancellation reason for records
immediate	boolean	If true, cancels immediately instead of at period end

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

Description: Pause a subscription. No payments will be collected until resumed.

Auth: Admin Key

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

Description: Resume a paused subscription.

Auth: Admin Key

Subscribers

Manage subscriber information.

GET/api/v1/subscribers

Description: List all subscribers across your plans.

Auth: Invoice Key

Query Parameters:

• search (optional) - Search by email, name, or contact info

GET/api/v1/subscribers/{id}

Description: Get subscriber details including all their subscriptions.

Auth: Invoice Key

Response:

{
  "id": "sub_123",
  "email": "user@example.com",
  "telegram": "@username",
  "nostr": "npub1...",
  "name": "John Doe",
  "created_at": 1704067200,
  "subscriptions": [...]
}

Payments

View payment history and details.

GET/api/v1/payments

Description: List all payments across subscriptions.

Auth: Invoice Key

Query Parameters:

• subscription_id (optional) - Filter by subscription
• status (optional) - Filter by status (paid, pending, failed)
• payment_method (optional) - Filter by method (lightning, onchain, stripe, paypal)

GET/api/v1/payments/{id}

Description: Get details for a specific payment.

Auth: Invoice Key

Response:

{
  "id": "pay_123",
  "subscription_id": "sub_456",
  "amount_sats": 10000,
  "status": "paid",
  "payment_method": "lightning",
  "payment_hash": "abc123...",
  "created_at": 1704067200,
  "paid_at": 1704067250
}

Public Endpoints

No authentication required. Used for checkout flows.

GET/public/plan/{id}

Description: Get public plan information for display on checkout pages.

Auth: None

Response: Plan name, price, interval, description (no sensitive data)

POST/public/subscribe/{plan_id}

Description: Create a new subscription (used by checkout form).

Auth: None

Body:

{
  "email": "user@example.com",
  "name": "John Doe",
  "telegram": "@username",
  "nostr": "npub1...",
  "payment_method": "lightning"
}

Response: Subscription ID and payment details (invoice, address, or redirect URL)

GET/public/checkout/{subscription_id}

Description: Get checkout page data including QR code and payment status.

Auth: None

Webhook Callbacks

Endpoints that receive payment confirmations from external services.

POST/public/webhook/satspay

Description: Callback endpoint for SatsPay Server. Receives on-chain and Lightning payment confirmations.

Auth: None (validated by charge ID)

POST/public/webhook/stripe

Description: Callback endpoint for Stripe webhooks. Receives card payment confirmations.

Auth: None (validated by Stripe signature)

POST/public/webhook/paypal

Description: Callback endpoint for PayPal IPN/webhooks. Receives PayPal payment confirmations.

Auth: None (validated by PayPal)