Creating a subscription

Qualy's API provides robust functionality for creating subscriptions, allowing developers to implement recurring payment systems with customizable schedules. This guide will take you through the process step by step, starting with a basic example and gradually introducing more complex subscription scenarios.

Before you start

You need to have a Contact _id to create a Subscription, use the Contact API to create or retrieve a Contact.

Creating a subscription

To create a subscription on Qualy, you will have to use the Subscription API.

When you create a Subscription, you can specify options like the name, amount, currency, billing details, and schedule:

try {
  const response = await fetch('https://api.qualyhq.com/v1/subscriptions/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
      'X-TENANT-ID': 'your-tenant-id-here',
    },
    body: JSON.stringify({
      "name": "Monthly Service Plan",
      "description": {
        "internal": "Internal notes about this subscription",
        "external": "Monthly service fee for Premium Support"
      },
      "contact": "656b9ef1a3258074a705433b",
      "amount": 10000, // Amount in cents (100.00)
      "service": "premium-support",
      "currency": "USD",
      "billing": {
        "startAt": "2025-10-01T00:00:00.000Z",
        "endAt": "2026-10-01T00:00:00.000Z"
      },
      "schedule": {
        "frequency": {
          "dayOfMonth": 1 // Bill on the 1st day of each month
        }
      }
    }),
  });

  if (response.ok) {
    const data = await response.json();
    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}

Subscription Scheduling Options

When creating a subscription, you need to define how frequently the payments should occur. This is controlled through the schedule property in your request:

To manage the Payment Intents created by the subsription, check the Payment Intents API.

Frequency Parameters

You can configure the subscription frequency by setting one of the following parameters:

Subscription Billing Period

Every subscription must have a defined billing period through the billing object, which contains:

• startAt: When the subscription begins (required)
• endAt: When the subscription ends (optional - if not provided, the subscription will continue indefinitely)

"billing": {
  "startAt": "2025-10-01T00:00:00.000Z",
  "endAt": "2026-10-01T00:00:00.000Z" // Optional
}

Tax calculation

Qualy's v1 API calculates the tax for each payment intent generated from a subscription based on the total amount. The tax settings you define when creating the subscription will be applied to all future payment intents generated from this subscription.

Check our Tax API to retrieve and create taxes. Learn more about Tax calculation in our dedicated guide.

Settlement currency and FX (Currency exchange)

Sometimes you may want to create a subscription in a specific currency (e.g. USD) but you want the end-user to pay in another (e.g. EUR). This is useful in many cases, especially when you want Qualy to pay the suppliers in the original currency, and to convert it automatically at the time of payout.

Set the property settlementCurrency as your desired currency. When payment intents are generated from the subscription and the end-user tries to pay, it will only display the payment options of the specified settlementCurrency.

Qualy will automatically fetch the most up-to-date FX rate for each payment intent generated from the subscription.

Here's an example of creating a subscription with a different settlement currency:

try {
  const response = await fetch('https://api.qualyhq.com/v1/subscriptions/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
      'X-TENANT-ID': 'your-tenant-id-here',
    },
    body: JSON.stringify({
      "name": "Annual Service Plan",
      "description": {
        "internal": "Premium support subscription",
        "external": "Annual subscription for Premium Support"
      },
      "contact": "656b9ef1a3258074a705433b",
      "amount": 120000, // 1,200.00 in USD
      "service": "656b9e1d2a3258dssfwe705433b",
      "currency": "USD",
      "settlementCurrency": "EUR", // Customer will pay in EUR
      "billing": {
        "startAt": "2025-10-01T00:00:00.000Z",
        "endAt": "2026-10-01T00:00:00.000Z"
      },
      "schedule": {
        "frequency": {
          "dayOfMonth": 1
        }
      }
    }),
  });

  if (response.ok) {
    const data = await response.json();
    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}

Monitoring subscription status

After creating a subscription, you can monitor its status through the Qualy dashboard or via API. The subscription object contains important tracking statistics:

"stats": {
  "nPaymentsCreated": 2, // Number of payment intents created so far
  "total": 240000, // Total amount expected over the subscription lifetime
  "lastPaymentCreatedAt": "2025-11-01T00:00:00.000Z", // When the last payment was created
  "nextPaymentDueAt": "2025-12-01T00:00:00.000Z" // When the next payment will be created
}

Linking services to subscriptions

When creating a subscription, you should specify the service field to indicate what service the subscription is for. This helps with reporting and organization within your Qualy account.

"service": "656b9e1d2a3258dssfwe705433b" // A Mongo ID of the Service

Managing payment intents from subscriptions

Once a subscription is created, Qualy will automatically generate payment intents based on the subscription schedule. These payment intents behave like any other payment intent in the system and can be managed through the standard Payment Intent API.

Subscription lifecycle

1. Creation: When you create a subscription, no payment intents are immediately created
2. First payment: On the schedule start date, the first payment intent is generated
3. Recurring payments: Subsequent payment intents are automatically created based on your frequency settings
4. End date: If specified, no new payment intents will be created after the subscription end date

Updating a subscription

You can update certain subscription parameters after creation by using the Subscription Update API.