## Subscription Management

Glomo provides comprehensive tools to manage subscriptions throughout their lifecycle.
Merchants can pause, resume, cancel, or update subscriptions directly from the Glomopay dashboard or via APIs, giving full control over customer billing while maintaining transparency and compliance. Subscription management capabilities vary slightly depending on whether the subscription is Fixed-Frequency or As Presented.

![subscription_management](/assets/subscription_management.79557ee61e1968f4b8cf02ab754ca6e210b27fdff1440774455d82cda81e4e45.9e6425bf.png)

### Supported Management Actions

| Action | Fixed-Frequency Subscriptions | As Presented Subscriptions |
|  --- | --- | --- |
| Pause Subscription | ✅ Supported | ❌ Not applicable |
| Resume Subscription | ✅ Supported | ❌ Not applicable |
| Cancel Subscription | ✅ Supported | ✅ Supported |
| Update Next Payment Date | ✅ Supported | ❌ Not applicable |
| Manual Charge | ❌ Not applicable | ✅ Supported |
| Update Card | ✅ Supported | ✅ Supported |
| Deactivate Subscription Link | ✅ Supported | ✅ Supported |


## Pausing a Subscription

### What Happens When a Subscription Is Paused

- All upcoming scheduled payments are temporarily stopped.
- No charges will be attempted until the subscription is resumed.
- Subscription remains visible and can be reactivated at any time.


### Steps to Pause a Subscription

div
![subscription_pause](/assets/subscription_pause.e5b99ef79b2688993f6759ccd7cab5786e416eb5f94965e2ff732c16754522c0.9e6425bf.png)

Alternatively, you can use the **Pause Subscription API** to pause an active subscription.

## Resuming a Paused Subscription

### What Happens When a Subscription Is Resumed

- The subscription returns to Active state.
- Billing resumes based on the existing schedule.
- Future payments are charged automatically by Glomo.


### Steps to Resume a Subscription

div
![subscription_resume](/assets/subscription_resume.6fc7e13cc8868b547670dd1f3c110f7d561c08589da6cab6a7b10cf76031623b.9e6425bf.png)

Alternatively, you can use the **Resume Subscription API** to resume a paused subscription.

## Canceling a Subscription

### What Happens When a Subscription Is Cancelled

- The subscription is permanently stopped.
- No further payments will be charged.
- The subscription cannot be resumed once cancelled.


### Steps to Cancel a Subscription

div
Cancellation is supported for both Fixed-Frequency and As Presented subscriptions.

![subscription_cancel](/assets/subscription_cancel.3b67bfd82135f40a443fcaff08525566c6188d0189162ea92004e8b5ff2e3467.9e6425bf.png)

Alternatively, you can use the **Cancel Subscription API** to cancel an active subscription.

## Updating the Next Payment Date (Fixed-Frequency Only)

The **Update Next Payment Date** feature allows merchants to adjust the upcoming billing date for an active subscription.

This is particularly useful for merchants in the insurance and financial services sectors, where policy issuance or activation may occur after the initial payment collection.

By updating the next payment date, merchants can align the recurring billing schedule with business events without cancelling or recreating the subscription.

![update_next_payment_date](/assets/update-next-payment-date.a6261bb179569bfc03d37a93bd7888fea791d3572f7c80312b664ad472560d28.9e6425bf.png)

### When to Use

Use this feature when:

- You’ve collected the first payment and want the next charge to align with the policy start or renewal date.
- A customer has requested a short deferral of their next billing date.
- You want to maintain consistent billing intervals while preserving the subscription lifecycle.


Avoid using this feature to:

- Change subscription frequency (e.g., monthly → quarterly).
- Modify the billing amount.
- Retry a failed payment use the retry mechanism instead.


### Dashboard Flow

You can create a subscription directly from the Glomopay dashboard. Here's how:

### API Reference

Endpoint:


```curl
PATCH /subscriptions/{subscription_id}/next-payment-date
```

Request Body:


```http
{
"next_payment_date": "2025-11-10"
}
```

## Update Card on a Subscription

You can use this feature to request customers with an active subscription to update their card directly through the existing subscription link. This ensures uninterrupted future auto-debits without the need to create a new subscription.

### Steps to Request Card Update

div
![subscription_update_card](/assets/subscription_update_card.078031bade8b67986bd4e163e25ff8f4f8e4a9feb4c277f4fc1cac62ada00c66.9e6425bf.png)

### How It Works

- The **"Update Card"** CTA is displayed on the subscription link when the subscription is in **Active** status.
- The customer enters new card details on the checkout page.
- A **$1 USD** verification charge is processed on the new card and automatically refunded on success.
- The new card token **replaces the existing payment method** for all future auto-debits.


### What Happens When a Card is Updated

- The **Subscription ID remains unchanged** — no new subscription is created.
- The **billing cycle remains unchanged** — the next payment date and frequency are not affected.
- The new card token replaces the existing payment method for all subsequent auto-debits.
- A **tracker entry** is added to the subscription: *"Payment method has been updated. Card ending with XXXX will be used for subsequent payments."*
- A webhook event `subscription.payment_method.updated` is fired to notify the merchant.


### Validations and Restrictions

| Scenario | Behaviour |
|  --- | --- |
| Subscription is not in **Active** status | The "Change Card" CTA is **not displayed**. Card update is only available for active subscriptions. |
| Customer enters the **same card** already on file | The system detects a duplicate and displays: *"This card is already associated with your subscription. Please use a different card."* |


### Webhook

When a card is successfully updated, Glomo sends the following webhook event:

**Event type:** `subscription.payment_method.updated`

**Example payload:**


```json
{
  "entity_type": "subscription",
  "event_type": "payment_method.updated",
  "data": {
    "id": "sub_69a02470HQ8yr",
    "status": "active",
    "start_date": "2026-02-26",
    "end_date": "2027-02-26",
    "billing_cycles": 12,
    "next_payment_date": "2026-04-26",
    "expires_at": null,
    "subscription_link_url": "https://checkout.glomopay.com/subscriptions/sub_69a02470HQ8yr",
    "customer_id": "cust_69a023dfGW4Yt",
    "cancelled_at": null,
    "reference_number": "REF-12345",
    "notes": {},
    "payment_method": {
      "type": "card",
      "details": {
        "card_network": "visa",
        "card_type": "credit",
        "end_digits": "4242",
        "country_code": "ARE",
        "card_holder_name": "John Doe",
        "card_bin": "424242",
        "issuer_name": "Emirates NBD"
      }
    },
    "plan_name": "Monthly Premium",
    "plan_description": "Monthly subscription plan",
    "product_name": "Insurance Premium",
    "product_description": null,
    "amount": 40000,
    "currency": "USD",
    "interval_type": "monthly",
    "interval_count": 1,
    "max_amount": null
  }
}
```

The `payment_method` object in the webhook reflects the **newly updated card** details, allowing merchants to confirm the change in their systems.

## Handling Failed Payments & Halted Subscriptions

- If a scheduled payment fails after configured retries, the subscription moves to Halted state.
- While halted:
  - No further charges are attempted.
  - Merchant can collect a payment on the same subscription from the customer to move the subscription to the active state again.
- For As Presented subscriptions, halting occurs due to card expiry or repeated failed charges.