> For the complete documentation index, see [llms.txt](https://docs.foloosi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.foloosi.com/subscriptions/api-subscription.md).

# Api Subscription

This Section guides you to create subscription via api payment mode.

The API subscription is compatible with all types of integration methods. If you want **to skip the 3DS option**, please contact Foloosi's support team.

**NOTE,**

**A subscription can only be created when the API is set to live mode.**

### Basic Requirements

* Foloosi merchant account - [click here to sign up ](https://foloosi.com/business-signup).
* Create api credentials - [click here to create](/get-started/create-api-credentials.md).

### Steps to create subscription

To create a subscription using any type of integration, simply add the required post data to the initialize API.

<pre class="language-javascript" data-line-numbers><code class="lang-javascript">// additional data to be passed with initialize api,
api_subscription :  "Yes", /**NOTE- THIS FIELD MUST BE IN YES */
<strong>recurring_data : {
</strong>    plan : {
        name : "Api new plan", /** YOUR PLAN NAME*/
        billing_type : "day", /** value must be day/week/month/year */
        billing_cycle : 1, /** it only applicable for week and month billing type.ex Every 1 weeks */
        billing_currency : "AED", //it should be 3 digit code and other than AED you should enabled multi currency option from Foloosi
        billing_amount : "SUBSCRIPTION AMOUNT",
        setup_fee : "SETUP FEE", //which is subscription setup one time fee
        total_count : 10, //number of deductions
        description : "daily demo plan",
        start_date : "dd-mm-yyyy" //which is optional param.if you given value should be in the format
                                  //Note : if you given date means .at the time of payment will be charged by transaction
                                  //amount as you given .subscription recurring will start on the given date and given billing amount
    },
    customer : {
        name : "CUSTOMER NAME",
        email : "CUSTOMER EMAIL ID"',
        mobile : "CUSTOMER MOBILE NO",
    }
}
</code></pre>

#### Sample images

After successful subscription creation, it has to be listed in Foloosi panel. Please login to view the subscription created.

<figure><img src="https://2728483298-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQCT5TjkKNyS34llPoX%2Fuploads%2FAMmztaxIWS1VWqgGcqHU%2Fsubscrption.png?alt=media&amp;token=9d23f6d0-01ee-4c5c-8b28-ee4a4da9b4fa" alt=""><figcaption><p>Subscription list</p></figcaption></figure>

Click the subscription id to view details like below

<figure><img src="https://2728483298-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQCT5TjkKNyS34llPoX%2Fuploads%2FMbHZrILKoFMC8TQoj9S5%2Fsubscrption-2.png?alt=media&amp;token=7662ab11-9ead-4d01-8459-e9898cccbd65" alt=""><figcaption><p>Subscription detail popup</p></figcaption></figure>

**To get the Transaction Details And Subscription number**

For Transaction Details, you can use the Get request as below.

{% code lineNumbers="true" %}

```javascript
GET API LINK: https://api.foloosi.com/v1/api/transaction-detail/YOUR_TRANSACTION_ID

HEADERS:
secret_key : YOUR_SECRET_KEY

SAMPLE RESPONSE:
{
    "message": "Transaction detail are",
    "data": {
        "transaction_no": "FLSXXXXXXXXXXXXXX",
        "receipt": null,
        "request_currency": "AED",
        "request_amount": 18,
        "customer_currency": "AED",
        "customer_amount": 18,
        "merchant_currency": null,
        "merchant_amount": null,
        "status": "pending",
        "created": "2022-11-01T10:21:04+00:00",
        "optional1": "order-id-123",\\optional fields passed on initialize api
        "optional2": "order-reference",\\optional fields passed on initialize api
        "optional3": "",\\optional fields passed on initialize api
        "subscription_no": "FLSSXXXXXXXXXXXXX"
    }
}
```

{% endcode %}

**To get the Subscription Details**&#x20;

For Subscription Details, you can use the Get request as below,&#x20;

{% code lineNumbers="true" %}

```javascript
GET API LINK: https://api.foloosi.com/v1/open/subscription-link/detail/YOUR_TRANSACTION_ID

HEADERS:
secret_key : YOUR_SECRET_KEY

SAMPLE RESPONSE:
{
    "message": "Subscription details are",
    "data": {
        "customer": {
            "name": "FOLOOSI CUSTOMER",
            "email": "tech@foloosi.com",
            "mobile": "567812345",
            "card_last_four": "5123"
        },
        "plan": {
            "name": "Mobile PostPaid",
            "type": "Billed Every month",
            "amount": "AED 114.60",
            "unit": "1 x AED 114.60 per unit",
            "setup_fee": 0,
            "status": "active",
            "created": "01-10-2022 02:11 am"
        },
        "invoices": [
            {
                "id": 50094,
                "subscription_id": 1031,
                "billing_type": "month",
                "billing_count": 1,
                "bill_date": "2022-11-01",
                "status": "paid"
            },
            {
                "id": 50095,
                "subscription_id": 1031,
                "billing_type": "month",
                "billing_count": 1,
                "bill_date": "2022-12-01",
                "status": "pending"
            }
        ]
    }
}
```

{% endcode %}

**To cancel a Subscription**&#x20;

**NOTE** : Follow any one of the methods below to cancel a subscription,

**a**. To cancel a Subscription with api , you can use the api given below,&#x20;

{% code lineNumbers="true" %}

```javascript

PUT API LINK: https://api.foloosi.com/v1/open/subscription-link/suspend

HEADERS:
secret_key : YOUR_SECRET_KEY

BODY:
subscription_no : YOUR_SUBSCRIPTION_NO

SAMPLE RESPONSE:
{
    "message": "Subscription cancelled successfully",
    "data": {
        "status": 200
    }
}
```

{% endcode %}

**b**. You can cancel the subscription directly from foloosi panel.

* login to foloosi panel.
* click *subscriptions* under subscription category.
* click the subscription id, it will open a popup as shown below.

<figure><img src="https://2728483298-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQCT5TjkKNyS34llPoX%2Fuploads%2FXx11Catiy4V7JyjQBkQM%2Fsubscrption-cancel.png?alt=media&amp;token=6bf81cc2-3e36-4ae7-80aa-0d09fe4c9a6f" alt=""><figcaption><p>cancel subscription</p></figcaption></figure>

**NOTE**

Supports 170 World Currencies

## Properties

List of properties available:

<table><thead><tr><th width="103">Name</th><th width="98">Type</th><th width="122">Required</th><th width="211">Description</th></tr></thead><tbody><tr><td>merchant_key</td><td>String</td><td>true</td><td>your foloosi merchant key</td></tr><tr><td>secret_key</td><td>String</td><td>true</td><td>your foloosi secret key</td></tr><tr><td>reference_token</td><td>String</td><td>false</td><td>the reference token - generates automatically if null</td></tr><tr><td>site_redirect<em>_</em>url</td><td>String</td><td>false</td><td>the url which will get payment response after payment completed.</td></tr><tr><td>transaction_amount</td><td>String</td><td>true</td><td>transaction amount </td></tr><tr><td>currency</td><td>String</td><td>true</td><td>transaction currency</td></tr><tr><td>customer_name</td><td>String</td><td>false</td><td>customer name - auto render in payment popup if passed</td></tr><tr><td>customer_email</td><td>String</td><td>false</td><td>customer email - auto render in payment popup if passed</td></tr><tr><td>customer_mobile</td><td>String</td><td>false</td><td>customer mobile - auto render in payment popup if passed</td></tr><tr><td>customer_address</td><td>String</td><td>false</td><td>customer address - auto render in payment popup if passed</td></tr><tr><td>customer_city</td><td>String</td><td>false</td><td>customer city - auto render in payment popup if passed</td></tr><tr><td>billing_state</td><td>String</td><td>false</td><td>Billing State - auto render in payment popup if passed</td></tr><tr><td>billing_postal_code</td><td>String</td><td>false</td><td>Billing Postcode - auto render in payment popup if passed</td></tr><tr><td>billing_country</td><td>String</td><td>false</td><td>Billing Country - auto render in payment popup if passed</td></tr><tr><td>api_subscription</td><td>String</td><td>true</td><td>It  must be Yes for create subscription</td></tr><tr><td>recurring_data</td><td>Array</td><td>true</td><td>It contain subscription details</td></tr><tr><td>plan</td><td>Array</td><td>true</td><td>It  must have plan detail</td></tr><tr><td>name</td><td>String</td><td>true</td><td>It must be string and name for the plan</td></tr><tr><td>biling_type</td><td>String</td><td>true</td><td>it must be day/week/month/year</td></tr><tr><td>billing_cycle</td><td>Integer</td><td>true</td><td>it only applicable for week and month billing type.ex Every 1 weeks</td></tr><tr><td>billing_currency</td><td>String</td><td>true</td><td>it should be 3 digit code and other than AED you should enabled multi currency option from Foloosi</td></tr><tr><td>billing_amount</td><td>Integer</td><td>true</td><td>recurring amount should be passed here</td></tr><tr><td>setup_fee</td><td>Integer</td><td>false</td><td>which is subscription setup one time fee</td></tr><tr><td>total_count</td><td>Integer</td><td>true</td><td>number of deductions in recurring</td></tr><tr><td>description</td><td>String</td><td>true</td><td>subscription description should be entered</td></tr><tr><td>start_date</td><td>String</td><td>false</td><td>which is optional param.if you given value should be in the format('dd-mm-yyyy')<br>if you given date means .at the time of payment will be charged by transaction<br>amount as you given .subscription recurring will start on the given date and given billing amount</td></tr><tr><td>customer</td><td>Array</td><td>true</td><td>It should contain customer details</td></tr><tr><td>name</td><td>String</td><td>true</td><td>it  must be customer name</td></tr><tr><td>email</td><td>String</td><td>true</td><td>it must be customer email Id</td></tr><tr><td>mobile</td><td>Integer</td><td>true</td><td>it must be customer mobile number</td></tr></tbody></table>

#### Support

Visit <https://www.foloosi.com> for support requests or email to <tech@foloosi.com>.

## Developed by

Foloosi Technologies Pvt Ltd.

## License

Copyrights (c) 2025 Foloosi