Payment Plans

Create and manage subscription payment plans.

Overview

Payment Plans define the structure for recurring subscriptions:

💰 Pricing - Amount and currency
📅 Billing frequency - Daily, weekly, monthly, yearly
🔄 Billing cycles - Limited or unlimited
📝 Trial periods - Free trials before first charge
⚙️ Setup fees - One-time initial charges

Create Payment Plan

Endpoint

POST /api/v1/payment-plans

curl -X POST https://dev.auxcore.net/api/v1/payment-plans \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Pro Plan",
    "description": "Professional subscription with all features",
    "amount": 99.00,
    "currency": "USD",
    "frequency": "monthly",
    "billingCycles": 0,
    "trialPeriodDays": 14,
    "setupFee": 50.00
  }'

Response:

{
  "success": true,
  "data": {
    "planId": "plan_abc123",
    "name": "Monthly Pro Plan",
    "description": "Professional subscription with all features",
    "amount": 99.00,
    "currency": "USD",
    "frequency": "monthly",
    "billingCycles": 0,
    "trialPeriodDays": 14,
    "setupFee": 50.00,
    "status": "active",
    "createdAt": "2026-01-28T12:00:00Z"
  }
}

Request Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Plan name
`description`	string	No	Plan description
`amount`	decimal	Yes	Recurring charge amount
`currency`	string	Yes	Currency code (USD, EUR, etc.)
`frequency`	string	Yes	Billing frequency
`billingCycles`	integer	No	Total billing cycles (0 = unlimited)
`trialPeriodDays`	integer	No	Free trial days
`setupFee`	decimal	No	One-time setup fee

Billing Frequencies

Frequency	Description	Example
`daily`	Every day	Gym memberships
`weekly`	Every 7 days	Weekly meal kits
`biweekly`	Every 14 days	Bi-weekly cleaning
`monthly`	Every 30 days	Most SaaS products
`quarterly`	Every 3 months	Quarterly subscriptions
`semiannually`	Every 6 months	Bi-annual payments
`annually`	Every 12 months	Annual licenses

List Payment Plans

Endpoint

GET /api/v1/payment-plans

curl "https://dev.auxcore.net/api/v1/payment-plans?status=active" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "plans": [
      {
        "planId": "plan_basic_123",
        "name": "Basic Plan",
        "amount": 29.00,
        "frequency": "monthly",
        "status": "active"
      },
      {
        "planId": "plan_pro_456",
        "name": "Pro Plan",
        "amount": 99.00,
        "frequency": "monthly",
        "status": "active"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 2
    }
  }
}

Get Payment Plan

Endpoint

GET /api/v1/payment-plans/:planId

curl https://dev.auxcore.net/api/v1/payment-plans/plan_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Update Payment Plan

Endpoint

PUT /api/v1/payment-plans/:planId

curl -X PUT https://dev.auxcore.net/api/v1/payment-plans/plan_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 109.00,
    "description": "Updated description"
  }'

⚠️ Note: Changes only affect new subscriptions, not existing ones.

Delete Payment Plan

Endpoint

DELETE /api/v1/payment-plans/:planId

curl -X DELETE https://dev.auxcore.net/api/v1/payment-plans/plan_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

⚠️ Note: Cannot delete plans with active subscriptions. Deactivate first.

Plan Examples

Basic SaaS Plan

{
  "name": "Basic Plan",
  "amount": 29.00,
  "currency": "USD",
  "frequency": "monthly",
  "billingCycles": 0,
  "trialPeriodDays": 7
}

Annual Plan with Discount

{
  "name": "Annual Pro",
  "amount": 990.00,
  "currency": "USD",
  "frequency": "annually",
  "billingCycles": 0,
  "description": "Save 17% vs monthly"
}

Limited-Time Subscription

{
  "name": "3-Month Trial",
  "amount": 49.00,
  "currency": "USD",
  "frequency": "monthly",
  "billingCycles": 3,
  "setupFee": 0
}

Service with Setup Fee

{
  "name": "Premium Service",
  "amount": 299.00,
  "currency": "USD",
  "frequency": "monthly",
  "setupFee": 500.00,
  "description": "Includes $500 onboarding"
}

Best Practices

✅ DO:

Offer trials - 7-14 days increases conversions
Create annual plans - Offer discounts for yearly billing
Clear naming - "Basic Monthly", "Pro Annual"
Document features - Use description field
Test thoroughly - Verify billing cycles work correctly
Version your plans - Create new plans for price changes

❌ DON'T:

Don't change existing plans - Create new versions instead
Don't delete active plans - Deactivate to hide from new signups
Don't forget setup fees - Include in trial descriptions
Don't use confusing names - Be clear about frequency
Don't skip trials - Major conversion booster

Next Steps

Need help? Contact support@auxvault.com