# Creating a subscription

> Creating a subscription using Qualy's API.

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 an existing Contact to create a Subscription. The `contact` field accepts either the Contact ObjectId or the contact email. The `service` field accepts either the Service ObjectId or service name. See [Smart references](/docs/smart-references.md).

## Creating a subscription

To create a subscription on Qualy, you will have to use the [Subscription API](https://v1-spec.qualyhq.com/#post-/v1/subscriptions/create).

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

**cURL**

```bash
curl -X POST https://api.qualyhq.com/v1/subscriptions/create \
  -H 'Authorization: ApiKey your-api-key-here' \
  -H 'X-TENANT-ID: your-tenant-id-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Monthly Service Plan",
    "mode": "schedule",
    "description": {
      "internal": "Internal notes about this subscription",
      "external": "Monthly service fee for Premium Support"
    },
    "contact": "john.doe@example.com",
    "amount": 10000,
    "service": "Premium Support",
    "currency": "USD",
    "billing": {
      "startAt": "2026-10-01T00:00:00.000Z",
      "endAt": "2027-10-01T00:00:00.000Z"
    },
    "schedule": {
      "frequency": "every-month",
      "dayOfMonth": 1
    }
  }'
```

**JavaScript**

```javascript
const res = 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',
    mode: 'schedule',
    description: {
      internal: 'Internal notes about this subscription',
      external: 'Monthly service fee for Premium Support',
    },
    contact: 'john.doe@example.com',
    amount: 10000, // amount in cents (100.00)
    service: 'Premium Support',
    currency: 'USD',
    billing: {
      startAt: '2026-10-01T00:00:00.000Z',
      endAt: '2027-10-01T00:00:00.000Z',
    },
    schedule: {
      frequency: 'every-month', // bill once a month…
      dayOfMonth: 1, // …on the 1st
    },
  }),
});

const { data: subscription } = await res.json();
console.log(subscription._id);
```

**PHP (Laravel)**

```php
use Illuminate\Support\Facades\Http;

$subscription = Http::withHeaders([
    'Authorization' => 'ApiKey your-api-key-here',
    'X-TENANT-ID' => 'your-tenant-id-here',
])->post('https://api.qualyhq.com/v1/subscriptions/create', [
    'name' => 'Monthly Service Plan',
    'mode' => 'schedule',
    'description' => [
        'internal' => 'Internal notes about this subscription',
        'external' => 'Monthly service fee for Premium Support',
    ],
    'contact' => 'john.doe@example.com',
    'amount' => 10000, // amount in cents (100.00)
    'service' => 'Premium Support',
    'currency' => 'USD',
    'billing' => [
        'startAt' => '2026-10-01T00:00:00.000Z',
        'endAt' => '2027-10-01T00:00:00.000Z',
    ],
    'schedule' => [
        'frequency' => 'every-month', // bill once a month…
        'dayOfMonth' => 1, // …on the 1st
    ],
])->json('data');

echo $subscription['_id'];
```

### 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:

> **Note — Important**
>
> Once a subscription is created, new payment intents will be automatically generated following the subscription schedule. Each payment intent is editable until it's paid or canceled.

To manage the [Payment Intents](https://v1-spec.qualyhq.com/#get-/v1/payment-intents) created by the subsription, check the [Payment Intents API](https://v1-spec.qualyhq.com/#get-/v1/payment-intents).

The `schedule.frequency` field is **required** and sets the cadence. Then, depending on the frequency, you pin the exact billing day with `dayOfMonth` or `dayOfWeek`.

#### Frequency values

| `frequency` | Description |
| --- | --- |
| `every-week` | Bills weekly. Pair with `dayOfWeek`. |
| `every-2-weeks` | Bills every two weeks. Pair with `dayOfWeek`. |
| `every-month` | Bills monthly. Pair with `dayOfMonth`. |

#### Billing-day parameters

| Parameter | Description |
| --- | --- |
| `dayOfMonth` | Which day of the month to bill (1-28). Example: `dayOfMonth: 15` bills on the 15th. Use with `every-month`. |
| `dayOfWeek` | Which day of the week to bill (0-6, where 0 is Sunday). Example: `dayOfWeek: 1` bills every Monday. Use with `every-week` / `every-2-weeks`. |

> **Note — The `mode` field is required**
>
> Every subscription needs a `mode`. Use `schedule` for standard recurring billing on a fixed cadence (covered here). The other modes — `amount-cap` and `payment-intent-partial` — support advanced billing scenarios.

### 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)

```javascript
"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](https://v1-spec.qualyhq.com/#post-/v1/tax/create) to retrieve and create taxes. Learn more about Tax calculation in our [dedicated guide](/docs/guides/handling-using-tax-rates.md).

### 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:

**cURL**

```bash
curl -X POST https://api.qualyhq.com/v1/subscriptions/create \
  -H 'Authorization: ApiKey your-api-key-here' \
  -H 'X-TENANT-ID: your-tenant-id-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Annual Service Plan",
    "mode": "schedule",
    "description": {
      "internal": "Premium support subscription",
      "external": "Annual subscription for Premium Support"
    },
    "contact": "john.doe@example.com",
    "amount": 120000,
    "service": "Premium Support",
    "currency": "USD",
    "settlementCurrency": "EUR",
    "billing": {
      "startAt": "2026-10-01T00:00:00.000Z",
      "endAt": "2027-10-01T00:00:00.000Z"
    },
    "schedule": {
      "frequency": "every-month",
      "dayOfMonth": 1
    }
  }'
```

**JavaScript**

```javascript
const res = 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',
    mode: 'schedule',
    description: {
      internal: 'Premium support subscription',
      external: 'Annual subscription for Premium Support',
    },
    contact: 'john.doe@example.com',
    amount: 120000, // 1,200.00 in USD
    service: 'Premium Support',
    currency: 'USD',
    settlementCurrency: 'EUR', // customer pays in EUR
    billing: {
      startAt: '2026-10-01T00:00:00.000Z',
      endAt: '2027-10-01T00:00:00.000Z',
    },
    schedule: {
      frequency: 'every-month',
      dayOfMonth: 1,
    },
  }),
});

const { data: subscription } = await res.json();
console.log(subscription._id);
```

**PHP (Laravel)**

```php
use Illuminate\Support\Facades\Http;

$subscription = Http::withHeaders([
    'Authorization' => 'ApiKey your-api-key-here',
    'X-TENANT-ID' => 'your-tenant-id-here',
])->post('https://api.qualyhq.com/v1/subscriptions/create', [
    'name' => 'Annual Service Plan',
    'mode' => 'schedule',
    'description' => [
        'internal' => 'Premium support subscription',
        'external' => 'Annual subscription for Premium Support',
    ],
    'contact' => 'john.doe@example.com',
    'amount' => 120000, // 1,200.00 in USD
    'service' => 'Premium Support',
    'currency' => 'USD',
    'settlementCurrency' => 'EUR', // customer pays in EUR
    'billing' => [
        'startAt' => '2026-10-01T00:00:00.000Z',
        'endAt' => '2027-10-01T00:00:00.000Z',
    ],
    'schedule' => [
        'frequency' => 'every-month',
        'dayOfMonth' => 1,
    ],
])->json('data');

echo $subscription['_id'];
```

### 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:

```javascript
"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.

```javascript
"service": "Premium Support" // A Service ObjectId or name
```

## 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.

> **Note — Important**
>
> Each payment intent generated from a subscription is editable until it's paid or canceled. This allows you to make adjustments to individual payments without affecting the overall subscription.

### 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.