Update subscription contract status (pause/resume/activate)

Changes the status of a subscription contract. This allows pausing, resuming, or activating subscriptions to control billing and delivery.

Full behavior, validation rules, and side effects

Key Features:

• Pause Subscriptions: Temporarily stop billing and deliveries
• Resume Subscriptions: Reactivate paused subscriptions
• Activate Subscriptions: Start inactive subscriptions
• Activity Logging: All status changes are logged for audit trail
• Customer Restrictions: Includes minimum cycle checks when called from customer portal

Status Values:

• ACTIVE: Subscription is active and billing/delivering normally
• PAUSED: Subscription is temporarily paused (no billing, no deliveries)
• CANCELLED: Subscription is cancelled (use DELETE endpoint instead)

Pause vs. Cancel:

• Pause: Temporary hold, customer can resume anytime
• Cancel: Permanent termination, requires creating new subscription to restart

Common Use Cases:

• Vacation Hold: Customer going on vacation, pause deliveries temporarily
• Financial Pause: Customer needs temporary break from payments
• Product Surplus: Customer has too much product, pause until they use it
• Seasonal Pause: Pause subscriptions during off-season (e.g., lawn care in winter)
• Resume After Pause: Customer ready to restart after temporary hold
• Reactivate Failed: Reactivate subscription after payment method updated

Pause Behavior:

• Billing Paused: No charges while paused
• Deliveries Paused: No orders created while paused
• Next Billing Date: Preserved or recalculated on resume (merchant setting)
• Unlimited Duration: Pauses can be indefinite unless merchant sets limits

Resume Behavior:

• Immediate Reactivation: Subscription becomes active immediately
• Next Billing Date: Calculated based on pause duration settings
• Deliveries Resume: Next delivery scheduled according to interval

Customer Portal Restrictions: When called from customer portal (vs. merchant API):

• Minimum Cycles: Cannot pause/cancel until minimum billing cycles met
• Freeze Period: Updates may be frozen until minimum requirements satisfied
• Retention Rules: Special retention discounts may be offered on cancellation

Important Notes:

• Customer Communication: Consider sending email notifications on status changes
• Billing Cycles Not Lost: Paused cycles don’t count toward minimums
• No Pro-rata: No refunds or credits when pausing mid-cycle

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

PUT /api/external/v2/subscription-contracts-update-status

Update subscription contract status (pause/resume/activate)

cURL

curl --request PUT \
  --url https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-status

400

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid subscription status"
}

Headers

X-API-Key · string

Query Parameters

contractId · integer<int64> · required

Subscription contract ID

status · enum<string> · required

New subscription status

Available options: ACTIVE, PAUSED

api_key · string

API Key (Deprecated - Use Header X-API-Key instead)

Response

204

Subscription status successfully updated (no content returned)