Sign in Subscribe
Tutorials

How to Pause or Cancel Customer Subscriptions via the API

Allan Porras

Allan Porras

— 3 min read
How to Pause or Cancel Customer Subscriptions via the API

Managing the lifecycle of your customer subscriptions programmatically is essential for maintaining a flexible and user-friendly billing system. With 4Geeks Payments, you can use the API to pause or cancel subscriptions automatically, reducing manual administrative work and improving the customer experience during offboarding or temporary service breaks.

This guide explains how to locate a subscription and modify its status using the 4Geeks Payments API.

Prerequisites

Before you begin, ensure you have the following:

  • A 4Geeks Console account with active billing features.
  • Your API Key (Test or Live) found in Settings > API Keys in the Console.
  • The subscription_id of the customer you wish to manage.
  • A tool to send HTTP requests (e.g., Postman, cURL, or your application's backend).
Note: Always use your Test Key (sk_test_...) during development to avoid affecting real customer data or processing actual charges.

Start Accepting Online Payments in 5 Minutes

Get paid faster on your website, your platform or social media via our payment link. Multiple currencies. 100% secure. 5-min activation process.

Learn more

How to Manage Subscriptions via API

The subscription lifecycle in 4Geeks Payments is managed through standard RESTful endpoints. Follow these steps to find a subscription and change its status.

1. Authenticate Your Request

All API requests must be authenticated using Basic Auth. Use your API Key as the username and leave the password field empty.

  • Header: Authorization: Basic <Base64_Encoded_Key>

2. Retrieve the Subscription ID

To modify a subscription, you first need its unique identifier (subscription_id). You can find this by listing subscriptions for a specific customer.

Endpoint: GET https://api.4geeks.io/v1/subscriptions/

Example Request (cURL):

curl -X GET "https://api.4geeks.io/v1/subscriptions/?customer={customer_id}" \
     -u "sk_test_12345abcdef:"

Response:

The API will return a JSON list of subscriptions. Locate the id of the subscription you want to modify (e.g., sub_890xyz).

3. Cancel a Subscription

Canceling a subscription stops all future recurring charges immediately. This is typically a permanent action.

Endpoint: DELETE https://api.4geeks.io/v1/subscriptions/{subscription_id}/

Example Request (cURL):

curl -X DELETE "https://api.4geeks.io/v1/subscriptions/sub_890xyz/" \
     -u "sk_test_12345abcdef:"

Response:

A successful request will return a 200 OK or 204 No Content status, confirming the subscription has been terminated.

4. Pause a Subscription (Update Status)

If you want to temporarily stop charges without deleting the subscription record entirely, you can update the subscription's status to paused or inactive.

Endpoint: PATCH https://api.4geeks.io/v1/subscriptions/{subscription_id}/

Example Request (cURL):

curl -X PATCH "https://api.4geeks.io/v1/subscriptions/sub_890xyz/" \
     -u "sk_test_12345abcdef:" \
     -H "Content-Type: application/json" \
     -d '{
           "status": "paused"
         }'
Tip: You may also need to update the next_payment_date field when reactivating the subscription to ensure the billing cycle resumes correctly.

Common Use Cases

Scenario 1: Customer Churn Automation

Situation: A user clicks "Cancel Subscription" in your SaaS dashboard.

Application: Instead of sending an email to support, your system triggers a DELETE request to the 4Geeks Payments API. This instantly stops the billing cycle, ensuring the customer is not charged again, and triggers a confirmation email via 4Geeks AI Agents if configured.

Scenario 2: Seasonal Account Holds

Situation: A customer using 4Geeks Health requests to freeze their gym or wellness membership for one month while traveling.

Application: You use the PATCH endpoint to set the subscription status to paused. This retains their data and history but prevents the payment gateway from processing the next scheduled charge until you update the status back to active.

Troubleshooting

  • Error 401: Unauthorized
    • Cause: Your API Key is missing, incorrect, or has expired.
    • Solution: Check Settings > API Keys in the 4Geeks Console. Ensure you are encoding the key correctly (Base64) if not using a library that handles it for you.
  • Error 404: Not Found
    • Cause: The subscription_id does not exist or belongs to a different environment (e.g., using a Test ID with a Live Key).
    • Solution: Verify the ID using the GET /v1/subscriptions/ list endpoint and ensure your keys match the environment (Test vs. Live).
  • Error 400: Bad Request
    • Cause: You attempted to set an invalid status (e.g., "stopped" instead of "cancelled").
    • Solution: Refer to the official API documentation for the list of valid status strings supported by the platform.

FAQs

Can I reactivate a canceled subscription?

Generally, canceled subscriptions cannot be reactivated. You would typically need to create a new subscription for the customer. However, paused subscriptions can be set back to active.

Will the customer be notified when I cancel via API?

4Geeks Payments can be configured to send automated emails upon status changes. Check your email settings in the Console to enable or disable these notifications.

How do I handle refunds for a canceled subscription?

Canceling a subscription prevents future charges. To refund a past charge, you must use the Refunds API endpoint (POST /v1/refunds/) separately using the specific charge_id.

Read more