Skip to content

How to Pause or Cancel Customer Subscriptions via the API in 4Geeks Payments

🤖 Explain with AI

Managing the customer lifecycle efficiently is crucial for modern SaaS and subscription-based businesses. While the 4Geeks Console provides a user-friendly interface for manual management, scaling operations often requires programmatic control. 4Geeks Payments offers a robust API that allows developers to pause or cancel subscriptions automatically, integrating seamlessly with your own customer portals or internal administrative tools.

This article guides you through the technical steps to pause or cancel customer subscriptions using the 4Geeks Payments API, ensuring your billing logic remains accurate and your customer experience seamless.

Prerequisites

Before interacting with the API, ensure you have the following:

  • Active 4Geeks Payments Account: You must have the 4Geeks Payments module enabled on your account.
  • API Credentials: Your API Key and Secret are required for authentication. These can be generated in the Developers section of the 4Geeks Console.
  • Subscription ID: The unique identifier (subscription_id) for the specific customer subscription you wish to modify.
  • API Client: A tool like Postman, cURL, or your preferred programming language (Python, Node.js, etc.) to send HTTP requests.

Step-by-Step Instructions

Step 1: Authenticate Your Request

All API requests to 4Geeks Payments must be authenticated to ensure security. You will authenticate using a Bearer Token in the header of your request.

  1. Locate your API credentials in the Settings > Developers tab of the dashboard.
  2. Include the following header in your HTTP request: Authorization: Bearer YOUR_API_KEY

Step 2: Retrieve the Subscription ID

To modify a subscription, you first need to identify it. If you do not already have the ID stored in your database, you can retrieve it by listing subscriptions for a specific customer.

  1. Send a GET request to the endpoint: https://api.4geeks.io/v1/subscriptions.
  2. Filter by the customer’s email or unique customer ID.
  3. From the JSON response, copy the id string (e.g., sub_1a2b3c4d5e).

Step 3: Pausing a Subscription

Pausing is ideal for temporary suspensions where you expect the customer to return. It stops the billing cycle without deleting the subscription object, allowing for easy reactivation.

  1. Endpoint: Prepare a POST request to: https://api.4geeks.io/v1/subscriptions/{subscription_id}/pause
  2. Body Parameters (Optional): You can specify a resume_at parameter (Unix timestamp) if you want the subscription to automatically reactivate on a specific date. 
    {
  "resume_at": 1735689600
}
  3. Execute: Send the request.
  4. Verification: The API will return the subscription object with a status of paused. Ensure your internal system updates the user’s access level accordingly.

Step 4: Canceling a Subscription

Cancellation permanently ends the billing cycle. Depending on your configuration, this may happen immediately or at the end of the current billing period.

  1. Endpoint: Prepare a DELETE (or POST, depending on specific configuration) request to: https://api.4geeks.io/v1/subscriptions/{subscription_id}/cancel
  2. Body Parameters:
    • cancel_at_period_end (boolean): Set to true to let the customer finish the month they already paid for. Set to false for immediate revocation. 
      {
  "cancel_at_period_end": true
}
  3. Execute: Send the request.
  4. Verification: The API returns the object with a status of canceled (or active with a cancel_at timestamp if you chose to cancel at period end).

Common Use Cases

Scenario 1: The “Seasonal Hold”

Situation: You run an education platform using 4Geeks Payments, and a student wants to freeze their account during summer break rather than cancelling entirely. Application: Your student portal triggers the Pause endpoint (/pause) with a resume_at date set for September 1st. Result: Billing stops immediately. On September 1st, the API automatically reactivates the subscription and attempts to capture the payment, retaining the customer without manual intervention.

Scenario 2: Automated Churn Management

Situation: A customer clicks “Cancel Account” in your SaaS dashboard. Application: Your backend triggers the Cancel endpoint (/cancel) with cancel_at_period_end: true. Result: The customer retains access until their paid term expires. 4Geeks Payments ensures no further invoices are generated, and the subscription status eventually transitions to canceled automatically, keeping your finance records accurate.

Troubleshooting

Issue 1: 401 Unauthorized Error

  • Cause: Your API Key is missing, incorrect, or has expired.
  • Solution: Check the Authorization header. Regenerate your keys in the 4Geeks Console if necessary.

Issue 2: 404 Not Found

  • Cause: The subscription_id provided does not exist or belongs to a different environment (e.g., Sandbox vs. Production).
  • Solution: Verify the ID matches the environment you are querying. Ensure you aren’t trying to access a Live ID in the Sandbox environment.

Issue 3: Subscription Status Conflict (409)

  • Cause: You are trying to pause a subscription that is already canceled, or cancel a subscription that is already paused without reactivating it first.
  • Solution: Always check the status field of the subscription object via a GET request before attempting a state change to ensure the action is valid.

Conclusion

Automating subscription management via the API empowers your business to handle scaling customer bases with precision. By integrating pause and cancel logic directly into your applications, you reduce the workload on support staff and offer a smoother experience for your users.

For more advanced configurations, such as handling proration during cancellations or setting up webhooks for status changes, explore the Developer Documentation in the 4Geeks Console.