Update a Subscription Plan

Overview

Update the details or state of a Subscription Plan. You can modify pricing, description, state (activate/deactivate), and optionally apply changes to all existing subscriptions using this plan.

Resource Access

User Permissions: Admin users only
Endpoint: PUT /subscription_plans/\{subscription_plan_id}

Arguments

Parameter	Type	Required	Description
subscription_plan_id	string	Yes (path)	The unique ID of the Subscription Plan
amount	integer	No	New base recurring amount in cents
nickname	string	No	Updated user-friendly nickname
description	string	No	Updated plan description
state	string	No	ACTIVE or INACTIVE
update_existing_subscriptions	boolean	No	If true, updates all existing subscriptions (default: false)
tags	object	No	Updated custom key-value metadata

Example Request

curl -X PUT \
  'https://api.ahrvo.network/payments/na/subscription_plans/SPsubscriptionPlan001' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 24900,
    "description": "Updated Basic plan with 20,000 API calls per month and priority email support",
    "nickname": "Basic Plus",
    "update_existing_subscriptions": false,
    "tags": {
      "tier": "basic",
      "version": "v3",
      "api_calls": "20000"
    }
  }'

Example Response

{
  "id": "SPsubscriptionPlan001",
  "created_at": "2023-11-01T10:00:00Z",
  "updated_at": "2023-12-10T16:00:00Z",
  "amount": 24900,
  "currency": "USD",
  "plan_name": "API Portal - Basic Plan",
  "description": "Updated Basic plan with 20,000 API calls per month and priority email support",
  "nickname": "Basic Plus",
  "linked_to": "MUmerchant123",
  "linked_type": "MERCHANT",
  "billing_interval": "MONTHLY",
  "duration_type": "EVERGREEN",
  "state": "ACTIVE",
  "billing_defaults": {
    "collection_method": "BILL_AUTOMATICALLY",
    "send_invoice": true,
    "send_receipt": true
  },
  "trial_defaults": {
    "interval_type": "DAY",
    "interval_count": 14
  },
  "discount_phase_defaults": null,
  "tags": {
    "tier": "basic",
    "version": "v3",
    "api_calls": "20000"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/subscription_plans/SPsubscriptionPlan001"
    },
    "merchant": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchant123"
    },
    "subscriptions": {
      "href": "https://api.ahrvo.network/payments/na/subscriptions?subscription_plan_id=SPsubscriptionPlan001"
    }
  }
}

Additional Information

HTTP 202 Accepted: Asynchronous operation
- Update request accepted but may take time
- Especially if updating existing subscriptions
- Response returned immediately
- Changes applied in background
Amount Updates: Change pricing
- Update amount field with new price in cents
- Example: 24900 = $249.00
- Affects future subscriptions only (unless update_existing_subscriptions=true)
- Cannot change currency after creation
State Updates: Activate or deactivate plan
- ACTIVE → INACTIVE: Archive/deprecate plan
  - New subscriptions cannot be created
  - Existing subscriptions continue unchanged
  - Good for phasing out old plans
  - Plan hidden from customers
- INACTIVE → ACTIVE: Reactivate plan
  - Make available for new subscriptions again
  - Useful if plan temporarily disabled
Update Existing Subscriptions: Critical parameter
- false (default): Only affects NEW subscriptions
  - Existing customers keep current pricing/terms
  - Most common and safest option
  - Grandfather existing customers
- true: Updates ALL active subscriptions
  - Changes applied to existing customers
  - Next billing cycle uses new amount
  - Use with caution - may violate agreements
  - Notify customers before making changes
  - Best for feature updates, not price increases
What Can Be Updated:
- ✅ amount: Pricing changes
- ✅ nickname: Display name
- ✅ description: Plan details and features
- ✅ state: ACTIVE/INACTIVE
- ✅ tags: Metadata and categorization
- ❌ plan_name: Cannot change (use nickname instead)
- ❌ billing_interval: Cannot change (create new plan)
- ❌ currency: Cannot change
- ❌ linked_to: Cannot change merchant
- ❌ trial_defaults: Cannot change (create new plan)
- ❌ discount_phase_defaults: Cannot change (create new plan)
- ❌ billing_defaults: Cannot change (create new plan)
Use Cases:
- Price Increase (Grandfathered):
```
{
  "amount": 24900,
  "update_existing_subscriptions": false
}
```
  - New customers pay $249/month
  - Existing customers keep $199/month
  - Reward loyalty with grandfathered pricing
- Price Increase (All Customers):
```
{
  "amount": 24900,
  "update_existing_subscriptions": true
}
```
  - All customers pay $249/month starting next billing
  - Notify customers 30+ days in advance
  - Risk: customer churn
  - May require customer agreement
- Archive Old Plan:
```
{
  "state": "INACTIVE"
}
```
  - Stop offering plan to new customers
  - Existing customers unaffected
  - Common when launching improved version
- Update Features/Description:
```
{
  "description": "Now includes 50,000 API calls and phone support",
  "tags": {
    "tier": "basic",
    "version": "v3",
    "api_calls": "50000",
    "support": "phone"
  }
}
```
  - Improve plan offering
  - No price change
  - Better value for customers
- Reactivate Seasonal Plan:
```
{
  "state": "ACTIVE"
}
```
  - Bring back plan for promotion
  - Re-enable for limited time
Price Change Best Practices:
- Increasing Prices:
  - Notify customers 30-60 days in advance
  - Explain value added
  - Offer grandfather pricing to existing customers
  - Consider annual discount incentive
  - Provide upgrade path to better plan
- Decreasing Prices:
  - Apply to all customers (including existing)
  - Builds goodwill and trust
  - May trigger annual-to-monthly downgrades
  - Consider limited-time promotion instead
- Adding Features Without Price Change:
  - Great for retention
  - Update description and tags
  - Announce to customers
  - Increases perceived value
Migration Strategies:
- Version 1 → Version 2:
  1. Create new plan (V2) with updated pricing/features
  2. Set old plan (V1) to INACTIVE
  3. Existing V1 customers stay on V1
  4. New customers only see V2
  5. Offer V1 customers incentive to upgrade to V2
- Force Migration:
  1. Update V1 plan with update_existing_subscriptions=true
  2. All customers moved to new pricing
  3. Send advance notification
  4. Provide opt-out/cancellation window
  5. Risk of churn - use sparingly
Common Workflows:
- Annual Price Adjustment:
  1. Review plan pricing yearly
  2. Create new plan version with updated price
  3. Set old plan to INACTIVE
  4. Grandfather existing customers
  5. New customers get new pricing
- Feature Enhancement:
  1. Add new features to service
  2. Update plan description
  3. Update tags with new feature flags
  4. Keep same price (or slight increase)
  5. Announce to customers
- Plan Consolidation:
  1. Too many similar plans
  2. Pick best plan to keep
  3. Set others to INACTIVE
  4. Migrate customers to consolidated plan
  5. Simplify pricing page
Subscription Impact:
- update_existing_subscriptions=false:
  - Existing subscriptions: No change
  - New subscriptions: Use updated plan
  - Each subscription snapshot plan at creation time
- update_existing_subscriptions=true:
  - Existing subscriptions: Updated on next billing
  - Subscription amount field updated
  - Previous pricing history may be lost
  - Irreversible - cannot roll back
Tags for Version Control:
- Track plan evolution with tags
- Example:
```
{
  "version": "v3",
  "last_updated": "2023-12-10",
  "changelog": "increased_api_limits"
}
```
- Helps with support and troubleshooting
- Audit trail of plan changes
State Transitions:
- ACTIVE → INACTIVE: Common (deprecate plan)
- INACTIVE → ACTIVE: Less common (reactivate)
- Cannot delete plans (archive with INACTIVE instead)
- Inactive plans still visible in admin, hidden from customers
Error Scenarios:
- Cannot update immutable fields (billing_interval, trial_defaults)
  - Create new plan instead
- Cannot update INACTIVE plan (set to ACTIVE first)
- Amount must be positive integer
- Invalid state value (must be ACTIVE or INACTIVE)
Notification Recommendations:
- Price increase: 30-60 day notice
- Feature addition: Immediate announcement
- Plan archival: 30 day notice (if forcing migration)
- Terms changes: Per user agreement/local law
Related Endpoints:
- GET /subscription_plans/{id}: View current plan details
- GET /subscriptions?subscription_plan_id={id}: See affected subscriptions
- POST /subscription_plans: Create new plan version instead of updating
- PUT /subscriptions/{id}: Update individual subscription

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Additional Information​

Overview

Resource Access

Arguments

Example Request

Example Response

Additional Information