Skip to main content

Cancel a Subscription

Overview​

Cancel a Subscription to stop all future recurring charges. The subscription state will change to CANCELED and no additional payments will be collected.

Resource Access​

  • User Permissions: Admin users only
  • Endpoint: DELETE /subscriptions/\{subscription_id}

Arguments​

ParameterTypeRequiredDescription
subscription_idstringYes (path)The unique ID of the Subscription to cancel

Example Request​

curl -X DELETE \
  'https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response​

HTTP/1.1 204 No Content

Additional Information​

  • HTTP 204 No Content: Success returns empty response
    • No response body
    • Subscription has been canceled
    • State changed to CANCELED
  • Immediate Cancellation: Effective immediately
    • No future charges will occur
    • Current billing period continues until end date
    • No refund for partial period (unless manually applied)
  • Cannot Be Undone: Cancellation is permanent
    • Cannot reactivate canceled subscription
    • Must create new subscription to restart
    • Preserves cancellation for historical records
  • Access Until Period End: Customer retains access
    • Paid through current billing cycle
    • Service continues until next_billing_date
    • Example: Cancel Dec 10, next bill Jan 1
      • Service continues through Dec 31
      • No charge on Jan 1
  • Use Cases:
    • Customer Cancellation: Self-service cancellation
    • Non-Payment: Cancel after repeated failed payments
    • Terms Violation: Account suspension/termination
    • Voluntary Churn: Customer no longer needs service
    • Upgrade Path: Cancel basic, create pro subscription
  • Best Practices:
    • Survey Reason: Ask why customer canceling
      • Improve retention
      • Identify issues
      • Offer alternatives
    • Offer Alternatives: Before canceling
      • Downgrade to cheaper plan
      • Pause subscription (if supported)
      • Apply discount/credit
    • Confirm Action: Prevent accidental cancellations
      • "Are you sure?" confirmation
      • Explain what they'll lose
      • Show access end date
    • Send Confirmation: Email after cancellation
      • Confirm cancellation
      • State access end date
      • Offer to reactivate
    • Retention Offers: Save at-risk customers
      • Discount for staying
      • Free month extension
      • Feature upgrade
  • Partial Period Refunds: Not automatic
    • Cancellation doesn't refund current period
    • To refund partial period:
      1. Calculate days unused
      2. Create refund Transfer manually
      3. Or apply credit for future use
    • Example: Cancel halfway through month
      • Paid $49 for full month
      • Used 15 days, 15 days unused
      • Refund $24.50 manually if desired
  • Common Workflows:
    • Standard Cancellation:
      1. Customer clicks "Cancel Subscription"
      2. Show confirmation dialog
      3. Call DELETE /subscriptions/{id}
      4. Display "Subscription Canceled" message
      5. Send confirmation email
      6. Service continues until period end
    • Cancel with Partial Refund:
      1. Cancel subscription (DELETE)
      2. Calculate unused days
      3. Create refund Transfer
      4. Email customer about refund
    • Dunning Flow (Failed Payments):
      1. Payment fails 3 times
      2. Send final notice email
      3. Wait 7 days for customer to update payment
      4. If no update, cancel subscription
      5. Send cancellation notice
  • Reactivation: Customer wants to return
    • Cannot uncancel
    • Create new subscription
    • May offer discount for returning customers
    • Import previous settings/preferences
  • State Changes:
    • Before: state: "ACTIVE"
    • After: state: "CANCELED"
    • Can verify with GET /subscriptions/{id}
  • Webhooks: Listen for cancellation events
    • subscription.canceled webhook
    • Trigger internal workflows
    • Update CRM, analytics
    • Send customer communications
  • Historical Data: Canceled subscriptions remain accessible
    • View via GET /subscriptions/{id}
    • Filter via GET /subscriptions?state=CANCELED
    • Important for reporting, analytics
    • Calculate churn rate
  • Related Endpoints:
    • GET /subscriptions/{id}: Verify cancellation status
    • POST /subscriptions: Create new subscription (if reactivating)
    • POST /transfers: Create refund for partial period