All Endpoints

Complete reference of all API endpoints in Subscriptions Manager.

Quick Reference

Plans

Method	Endpoint	Auth	Description
GET	/api/v1/plans	Invoice	List all plans (paginated)
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/plans/{id}/subscribers	Invoice	List plan subscribers (paginated)

Subscriptions

Method	Endpoint	Auth	Description
GET	/api/v1/subscriptions	Invoice	List subscriptions (paginated, filterable)
GET	/api/v1/subscriptions/{id}	Invoice	Get subscription
POST	/api/v1/subscriptions/{id}/pause	Admin	Pause subscription
POST	/api/v1/subscriptions/{id}/resume	Admin	Resume subscription
POST	/api/v1/subscriptions/{id}/cancel	Admin	Cancel subscription
POST	/api/v1/subscriptions/{id}/extend	Admin	Add free days
GET	/api/v1/subscriptions/{id}/manage-link	Admin	Get subscriber portal URL
GET	/api/v1/subscriptions/{id}/payments	Invoice	List payments (paginated)

Archive

Method	Endpoint	Auth	Description
GET	/api/v1/archive/plans	Invoice	List archived plans (paginated)
GET	/api/v1/archive/subscriptions	Invoice	List archived subscriptions (paginated)

Public

Method	Endpoint	Auth	Description
GET	/public/plan/{id}	None	Public plan info
POST	/public/subscribe	None	Create subscription (JSON body)
GET	/public/payment/{id}/status	None	Check payment status
POST	/public/nwc/validate	None	Validate NWC connection
POST	/public/subscribe/nwc	None	Create NWC subscription

Subscriber Portal

Method	Endpoint	Auth	Description
GET	/public/manage/subscriptions	Subscriber	List subscriptions (paginated)
POST	/public/manage/subscription/{id}/cancel	Subscriber	Cancel subscription
GET	/public/manage/wallets	Subscriber	List NWC wallets (paginated)
DELETE	/public/manage/wallets/{id}	Subscriber	Disconnect NWC wallet

Webhooks

Method	Endpoint	Auth	Description
POST	/public/webhook/satspay	None	SatsPay callback
POST	/public/webhook/stripe	None	Stripe callback
POST	/public/webhook/paypal	None	PayPal callback

Pagination

All list endpoints marked (paginated) accept limit and offset query parameters and return a PaginatedResponse wrapper.

Param	Default	Range	Description
limit	50	1–200	Items per page
offset	0	0+	Items to skip

Plans

Manage subscription plans.

GET/api/v1/plans

Description: List all active plans for the authenticated wallet (paginated).

Auth: Invoice Key

Query Parameters: limit (default 50), offset (default 0)

Response:

{
  "items": [
    {
      "id": "abc123",
      "name": "Pro Plan",
      "amount_sats": 10000,
      "interval": "monthly",
      "allow_lightning": true,
      "allow_onchain": false,
      "allow_stripe": true,
      "allow_paypal": false
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

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 (paginated).

Auth: Invoice Key

Query Parameters:

• limit (default 50) - Items per page (1–200)
• offset (default 0) - Items to skip
• 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

Description: Create a new subscription (JSON body).

Auth: None

Body:

{
  "plan_id": "plan_abc123",
  "payment_method": "lightning",
  "email": "user@example.com",
  "name": "John Doe",
  "receive_confirmations": true,
  "receive_reminders": true
}

Field	Type	Required	Description
plan_id	string	Yes	Plan to subscribe to
payment_method	string	Yes	lightning, onchain, card, paypal, or nwc
email	string	No	Subscriber email
name	string	No	Subscriber name
telegram	string	No	Telegram username
nostr	string	No	Nostr npub or NIP-05
receive_confirmations	boolean	No	Opt in to confirmations (default: true)
receive_reminders	boolean	No	Opt in to reminders (default: true)

Response: Returns a CheckoutResponse with payment_id, payment_method, payment details (invoice, address, QR codes, or checkout URL), and expires_at. For trial plans, returns a TrialSubscriptionResponse instead.

GET/public/payment/{id}/status

Description: Check payment status.

Auth: None

Response:

{
  "payment_id": "pay_123",
  "status": "paid",
  "paid_at": 1704067250,
  "subscription_id": "sub_xyz789"
}

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)