---
updatedAt: 2026-09-29T03:19:58.000Z
agentTools:
  projectIndex: https://docs.paymongo.com/llms.txt
---

# Subscriptions

How to create plans, attach subscriptions, and handle billing cycles.

## Overview

The Subscriptions API automates recurring billing. You define a billing plan, a customer subscribes, and PayMongo generates invoices and collects payment on each cycle automatically. Account configuration is required before going live — contact PayMongo support to enable subscriptions on your account.

Supported payment methods: **Visa/Mastercard cards** and **Maya**. <Anchor target="_blank" href="https://developers.paymongo.com/docs/account-settings-account-capabilities#payment-methods">Ensure that your PayMongo Account is activated for the supported payment method.</Anchor> Card-based subscriptions require [Card Vaulting](../cards/card-vaulting) — the customer's card must be stored on a Customer object.

***

## Create a subscription

To set up a subscription you need three things: a plan, a customer, and a subscription linking the two.

**Create a plan** — defines the billing amount, currency, and interval. One plan can be reused across many subscriptions.

```javascript
const plan = await fetch('https://api.paymongo.com/v1/subscriptions/plans', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + btoa('sk_test_YOUR_SECRET_KEY:')
  },
  body: JSON.stringify({
    data: {
      attributes: {
        name: 'Monthly Pro Plan',
        amount: 29900,
        currency: 'PHP',
        interval: 'month',
        interval_count: 1
      }
    }
  })
}).then(r => r.json());
```

**Create a customer** — represents the subscriber in PayMongo.

```javascript
const customer = await fetch('https://api.paymongo.com/v1/customers', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + btoa('sk_test_YOUR_SECRET_KEY:')
  },
  body: JSON.stringify({
    data: {
      attributes: {
        first_name: 'Juan',
        last_name: 'dela Cruz',
        email: 'juan@example.com',
        phone: '09171234567'
      }
    }
  })
}).then(r => r.json());
```

**Create a subscription** — links the customer to the plan. PayMongo generates the first invoice immediately.

```javascript
const subscription = await fetch('https://api.paymongo.com/v1/subscriptions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + btoa('sk_test_YOUR_SECRET_KEY:')
  },
  body: JSON.stringify({
    data: {
      attributes: {
        plan_id: 'plan_xxx',
        customer_id: 'cus_xxx'
      }
    }
  })
}).then(r => r.json());
```

The first invoice generates a Payment Intent. Direct the customer through the normal payment flow — this also vaults their payment method for future cycles. The customer must complete this first payment within **24 hours** or the subscription is automatically cancelled.

**Subscription and invoice statuses**

| Subscription status    | What it means                                                        |
| ---------------------- | -------------------------------------------------------------------- |
| `incomplete`           | Waiting for the customer to complete the first payment               |
| `incomplete_cancelled` | Not paid within 24 hours — create a new subscription to retry        |
| `active`               | All invoices paid; service can be provided                           |
| `past_due`             | Latest invoice failed — PayMongo retries once per day, up to 3 times |
| `unpaid`               | Still unpaid after 3 retries — consider pausing service              |
| `cancelled`            | Subscription was cancelled; no new invoices will be generated        |

| Invoice status | What it means                                                         |
| -------------- | --------------------------------------------------------------------- |
| `draft`        | Generated 1 day before the billing date; amount can still be adjusted |
| `open`         | Finalized 12 hours after draft; payment attempt is made               |
| `paid`         | Payment succeeded                                                     |
| `void`         | Invoice was cancelled                                                 |

***

## Manage a subscription

**Cancel a subscription** — takes effect immediately. Any existing open invoices remain collectible.

```javascript
await fetch(`https://api.paymongo.com/v1/subscriptions/${subscriptionId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': 'Basic ' + btoa('sk_test_YOUR_SECRET_KEY:')
  }
});
```

**Change the plan** — plan changes take effect at the next billing cycle; the current cycle continues at the original plan rate.

**Change the payment method** — the customer must re-authenticate. PayMongo authorizes a small test amount on the new card then cancels it. The subscription continues with the new method from the next cycle.

***

## On-demand subscriptions

On-demand subscriptions give you full control over when each billing cycle is charged. PayMongo links the customer's payment method to a plan but does not automatically collect future payments — you trigger each invoice manually by calling the [Initiate On-Demand Payment](https://developers.paymongo.com/reference/initiate-on-demand-payment) endpoint.

> **Only Maya is supported for on-demand subscriptions.**
>
> **The recurring schedule is your responsibility.** PayMongo does not manage when or how often to charge customers. You must inform customers of the payment schedule.

Create a plan with `type: "on_demand"`. The `amount` on an on-demand plan only applies to the first payment — you set the amount for each subsequent cycle when triggering the invoice.

```javascript
const plan = await fetch('https://api.paymongo.com/v1/subscriptions/plans', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + btoa('sk_test_YOUR_SECRET_KEY:')
  },
  body: JSON.stringify({
    data: {
      attributes: {
        name: 'Insurance Monthly Plan',
        type: 'on_demand',
        amount: 100000,
        currency: 'PHP'
      }
    }
  })
}).then(r => r.json());
```

The setup flow (create customer, create subscription, first payment) is the same as a regular subscription, with two time limits to keep in mind:

1. **Create the subscription** — PayMongo generates the first invoice and its Payment Intent immediately. Store `latest_invoice.payment_intent.id` from the response.
2. **Attach the payment method** to that Payment Intent and redirect the customer to `next_action.redirect.url` to authorize it. The customer must complete authorization within the payment method's **authorization window** (see below). If they don't, the Payment Intent returns to `awaiting_payment_method` — create a new payment method and attach again.
3. **Complete the first payment** within **24 hours** of creating the subscription. Otherwise PayMongo cancels the subscription and its invoice, and the subscription status becomes `incomplete_cancelled` — create a new subscription to retry.

**Authorization windows for on-demand subscriptions**

| Payment method | Authorization window |
| -------------- | -------------------- |
| Maya           | 15 minutes           |

These windows apply only to on-demand subscriptions and can be shorter than the same provider's window for one-time payments listed on the [E-wallets](/docs/payment-acceptance-e-wallets#expiry-windows) page.

Once the first payment succeeds, the subscription becomes `active` and the payment method is stored for future charges.

For each subsequent cycle, call the Initiate On-Demand Payment endpoint — PayMongo creates the invoice and attempts to charge the stored payment method automatically, up to 3 attempts 24 hours apart.