> ## Documentation Index
> Fetch the complete documentation index at: https://developer.transactbridge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

# Subscriptions

TransactBridge Subscriptions allow merchants to set up **recurring payments** for products or services. A subscription defines the billing frequency, amount, payment flow, invoice behavior, and rules for handling failed payments.

Customers can subscribe through a [**shareable Payment link**](https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825) that opens a hosted payment page. Once the subscription is created and the customer completes the required payment or payment-method setup, the subscription is reflected in the TransactBridge panel. Webhooks and callbacks can also be configured to receive real-time subscription and payment updates.

## Subscription Types

TransactBridge supports two subscription billing models:

| Type         | Description                                                                                                               | Configuration        |
| ------------ | ------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| **Prepaid**  | The customer pays before receiving access to the service. The amount is collected at the beginning of the billing period. | `billAtStart: true`  |
| **Postpaid** | The customer uses the service first and is charged at the end of the billing period.                                      | `billAtStart: false` |

## Subscription Lifecycle

A subscription can move through different states during its lifecycle:

```mermaid theme={null}
flowchart LR
    A[PENDING] --> B[TRIAL]
    A --> C[ACTIVE]
    B --> C
    C --> D[PAUSED]
    D --> C
    C --> E[CANCELLED]
    C --> F[EXPIRED]
    A --> G[PENDING_EXPIRED]
    C --> H[FAILED]
```

| Status            | Description                                                                                           |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| `PENDING`         | Subscription is created and the customer can complete the payment or activation process.              |
| `PENDING_EXPIRED` | Customer did not complete the subscription before the configured expiry period.                       |
| `TRIAL`           | Subscription is in its trial period.                                                                  |
| `ACTIVE`          | Subscription is active and recurring billing can take place.                                          |
| `PAUSED`          | Subscription has been temporarily paused, either by the partner or based on configured payment rules. |
| `EXPIRED`         | Subscription has reached its expiration state.                                                        |
| `CANCELLED`       | Subscription has been cancelled by the customer, partner, or system configuration.                    |

## Key Subscription Configurations

When [creating a subscription](https://docs.transactbridge.com/#b075df15-b1ef-49ab-8871-6eaf2224dfb8), merchants can configure several parameters to control billing and payment behavior.

| Parameter                    | Purpose                                                                                     |
| ---------------------------- | ------------------------------------------------------------------------------------------- |
| `frequency`                  | Defines the recurring billing cycle.                                                        |
| `billAtStart`                | Determines whether the subscription is prepaid or postpaid.                                 |
| `maxQuoteAmount`             | Defines the maximum amount that can be auto-debited using the mandate.                      |
| `billingDateAnchor`          | Allows billing to occur on a specific day of the month.                                     |
| `dayUntillDue`               | Defines how long an invoice can remain due before becoming overdue.                         |
| `maxUnpaidInvoices`          | Defines the maximum number of unpaid invoices allowed.                                      |
| `postMaxUnpaidInvoices`      | Defines the subscription status after the unpaid-invoice limit is exceeded.                 |
| `reAttemptConfig`            | Configures retry attempts for failed invoice payments.                                      |
| `trialSettings`              | Configures the subscription trial period and payment-method requirements.                   |
| `discount` / `couponDetails` | Allows discounts or coupons to be applied to the subscription.                              |
| `maxUnpausedInvoiceDueCount` | Controls when a paused subscription can be reactivated after outstanding invoices are paid. |

## Billing Date Anchor

The `billingDateAnchor` parameter allows the merchant to define a fixed billing date.

For example, if:

```json theme={null}
{
  "frequency": "MNTH",
  "billingDateAnchor": "2"
}
```

the invoice is generated on the **2nd day of each month**, instead of using the customer's subscription start date as the billing date.

## Failed Payments and Retries

TransactBridge allows merchants to configure how failed or unpaid invoices should be handled.

The merchant can configure:

* Number of allowed unpaid invoices using `maxUnpaidInvoices`
* Number of days before a due invoice becomes overdue using `dayUntillDue`
* Retry attempts using `reAttemptConfig`
* The subscription state after the unpaid-invoice threshold is reached using `postMaxUnpaidInvoices`

This allows merchants to define whether a subscription should be **paused, expired, cancelled, or retried** when payments remain unpaid.

## Summary

TransactBridge subscriptions provide a flexible recurring billing mechanism that supports:

* Prepaid and postpaid billing
* Multiple billing frequencies
* Trial periods
* Fixed billing dates
* Coupons
* Automatic payment collection
* Failed-payment retries
* Pause, resume, cancellation, and expiration
* Webhooks and callbacks for subscription updates
* Hosted subscription payment links and checkout integrations

This flexibility allows subscriptions to be configured for fixed-price plans as well as usage-based billing models.