Subscriptions

Ecart Pay’s Subscriptions API allows you to create and manage recurring payments for your users. Whether you're billing daily, monthly, or yearly, our flexible system supports direct subscriptions or reusable subscription templates to simplify scale.

Overview

You can create a subscription for a user in two ways:

Using a Subscription Template: Ideal when you need to apply the same subscription logic to multiple customers (e.g., gym memberships, SaaS plans).
Creating a Subscription Directly: When you want to create a unique subscription for a specific user without saving the configuration for reuse.

1. Create a Subscription Template

Use a template when you want to define a reusable subscription model with parameters like billing frequency and trial period.

Endpoint

POST /api/subscriptions-template

Request Body

Field	Type	Description
`amount`	integer	Amount to charge per interval, in cents (e.g., `100` = $100.00)
`currency`	string	ISO 4217 currency code (e.g., `MXN`)
`interval`	integer	Send 1
`frequency`	string	Billing interval: `daily`, `weekly`, `monthly`, or `yearly`
`service`	string	Name or label for the subscription service
`trial_period_days`	integer	(Optional) Number of days before the first charge
`benefits`	array	List of benefits included in the subscription

Example Request

{
    "amount": 100,
    "currency": "MXN",
    "interval": "monthly",
    "frequency": 1,
    "service": "Gold Plus",
    "trial_period_days": 30,
    "benefits": [
        "Unlimited access to premium content",
        "24/7 priority support",
        "Exclusive 15% discounts",
        "Up to 3 additional users"
    ]
}

Example Response

{
    "account_id": "6851ef3dd0b39474707f960d",
    "amount": 100,
    "currency": "MXN",
    "interval": "monthly",
    "frequency": 1,
    "service": "Gold Plus",
    "trial_period_days": 30,
    "benefits": [
        "Unlimited access to premium content",
        "24/7 priority support",
        "Exclusive 15% discounts",
        "Up to 3 additional users"
    ],
    "id": "687e8679e0ceebb93d273d8f",
    "created_at": "2025-07-21T18:27:05.053Z",
    "updated_at": "2025-07-21T18:27:05.053Z"
}

2. Create a Subscription from a Template

Once a template is created, use it to subscribe users.

Endpoint

POST /api/subscriptions

Response Body

Field	Type	Description
`template_id`	string	ID of the subscription template used
`customer_id`	string	ID of the customer the subscription was created for
`card_ids`	array	List of card IDs associated with the subscription

Example Request

{
    "template_id": "687e8679e0ceebb93d273d8f",
    "customer_id": "6854346910775959c2173b48",
    "card_ids": ["686308a6a237c8038e020776"],
}

Example Response

{
    "account_id": "6851ef3dd0b39474707f960d",
    "customer_id": "6854346910775959c2173b48",
    "card_ids": [
        "686308a6a237c8038e020776"
    ],
    "status": "active",
    "service": "Gold Plus",
    "amount": 100,
    "currency": "MXN",
    "interval": "monthly",
    "frequency": 1,
    "trial_period_days": 30,
    "attempts": 0,
    "benefits": [
        "Unlimited access to premium content",
        "24/7 priority support",
        "Exclusive 15% discounts",
        "Up to 3 additional users"
    ],
    "errors": [],
    "id": "687e87d3e0ceebb93d273da9",
    "created_at": "2025-07-21T18:32:51.952Z",
    "updated_at": "2025-07-21T18:32:51.952Z"
}

3. Create a One-Off Subscription (Without Template)

If you want to create a subscription without saving a reusable template, pass the subscription parameters directly.

Endpoint

POST /api/subscriptions

Request Body

Field	Type	Description
`customer_id`	string	ID of the customer to subscribe
`card_ids`	array	List of card IDs to be used for payment
`amount`	integer	Amount to charge per interval, in cents (e.g., `100` = $100.00)
`currency`	string	ISO 4217 currency code (e.g., `MXN`)
`interval`	integer	Send 1
`frequency`	string	Billing interval: `daily`, `weekly`, `monthly`, or `yearly`
`service`	string	Name or label for the subscription service
`trial_period_days`	integer	(Optional) Number of days before the first charge
`benefits`	array	List of benefits included in the subscription

Example Request

{
    "customer_id": "6854346910775959c2173b48",
    "card_ids": ["686308a6a237c8038e020776"],
    "amount": 100,
    "currency": "MXN",
    "interval": "monthly",
    "frequency": 1,
    "service": "Gold Plus",
    "trial_period_days": 30,
    "benefits": [
        "Unlimited access to premium content",
        "24/7 priority support",
        "Exclusive 15% discounts",
        "Up to 3 additional users"
    ]
}

Example Response

{
    "account_id": "6851ef3dd0b39474707f960d",
    "customer_id": "6854346910775959c2173b48",
    "card_ids": [
        "686308a6a237c8038e020776"
    ],
    "status": "active",
    "service": "Gold Plus",
    "amount": 100,
    "currency": "MXN",
    "interval": "monthly",
    "frequency": 1,
    "trial_period_days": 30,
    "attempts": 0,
    "benefits": [
        "Unlimited access to premium content",
        "24/7 priority support",
        "Exclusive 15% discounts",
        "Up to 3 additional users"
    ],
    "errors": [],
    "id": "687e87d3e0ceebb93d273da9",
    "created_at": "2025-07-21T18:32:51.952Z",
    "updated_at": "2025-07-21T18:32:51.952Z"
}

Coming Soon

Subscription cancellation
Pause and resume options