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

# Configure trials

# Trial Subscription

A **trial** is a predefined period during which the customer can access a subscription before the first recurring payment is collected.

Trials are configured using the optional `trialSettings` object in the <a href="https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825">Create Susbcription API</a> request.

During the trial period, the subscription remains in the **TRIAL** state.

## Trial Activation Flow

The following flow illustrates the two supported trial activation options:

* **Trial with a payment mandate**
* **Trial without a payment mandate**

At the end of the trial, the subscription either proceeds with automatic billing (if a valid payment mandate is available) or follows the configured subscription policy.

***

## Trial with Payment Mandate

In this flow, the customer authorizes or adds a payment mandate while activating the trial.

### Behaviour

* The customer provides or authorizes a payment mandate during trial activation.
* No payment is collected when the trial starts.
* The subscription remains in the **TRIAL** state throughout the trial period.
* If the customer has not cancelled the subscription before the trial ends, Transact Bridge automatically attempts the first recurring payment using the saved payment mandate.

<Note>
  No debit is attempted during the trial period.
</Note>

***

## Trial without Payment Mandate

In this flow, the customer starts the trial without providing a payment mandate.

### Behaviour

* The customer starts using the subscription immediately.
* No payment authorization is required during activation.
* The customer can add a payment mandate at any time while the trial is active.
* When the trial ends:
  * If a payment mandate is available, Transact Bridge attempts to collect the first payment.
  * Otherwise, the subscription follows the configured billing or activation policy.

<Warning>
  If no payment mandate has been added by the end of the trial, automatic billing cannot be performed until one is available.
</Warning>

***

## Comparison

| Feature                                    | Trial with Payment Mandate    | Trial without Payment Mandate       |
| :----------------------------------------- | :---------------------------- | :---------------------------------- |
| Payment mandate required at activation     | ✅ Yes                         | ❌ No                                |
| Payment collected at activation            | ❌ No                          | ❌ No                                |
| Customer can use subscription during trial | ✅ Yes                         | ✅ Yes                               |
| Payment mandate can be added later         | Not required                  | ✅ Yes                               |
| Automatic payment at trial end             | ✅ Using saved payment mandate | ✅ If payment mandate has been added |

## Trial Lifecycle

```mermaid theme={null}
flowchart TD

    A[Create Subscription<br/>with trialSettings]

    A --> B{Payment Mandate<br/>Provided?}

    %% WITH PAYMENT MANDATE
    B -->|Yes| C[Customer authorizes<br/>payment mandate]
    C --> D[Subscription enters<br/>TRIAL state]
    D --> E[No payment is<br/>collected during trial]
    E --> F{Trial Ends?}
    F -->|Customer Cancelled| G[Subscription Cancelled<br/>No renewal debit]
    F -->|Active Subscription| H[Attempt first recurring<br/>payment using saved<br/>payment mandate]
    H --> I[Subscription becomes<br/>ACTIVE]

    %% WITHOUT PAYMENT MANDATE
    B -->|No| J[Trial starts without<br/>payment authorization]
    J --> K[Subscription enters<br/>TRIAL state]
    K --> L[Customer may add<br/>payment mandate later]
    L --> M{Trial Ends?}
    M -->|Payment Mandate Added| N[Collect first payment]
    N --> O[Subscription becomes<br/>ACTIVE]
    M -->|No Payment Mandate| P[Follow configured<br/>subscription policy]
```

## API Configuration

Trials are enabled by including the optional `trialSettings` object in the <a href="https://docs.transactbridge.com/#307dc665-ae10-4e43-8853-5b7f04961825">Create Susbcription API</a> request.

```json theme={null}
{
  "trialSettings": {
    "trialPeriod": 14,
    "trialPeriodUnit": "DAY"
  }
}
```

Refer to the **Create Subscription API** documentation for all supported `trialSettings` parameters.