Subscriptions

Ecart Pay's Subscriptions API allows you to create and manage recurring payments for your users. Whether you're billing daily, weekly, monthly, quarterly, semiannually, or yearly, our flexible system supports direct subscriptions, reusable subscription templates, pro-rata billing, trial periods, and automatic payment processing.

Overview

You can create a subscription for a user in three 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 Direct Subscription: When you want to create a unique subscription for a specific user without saving the configuration for reuse.
• Creating Subscriptions with Advanced Features: Including pro-rata billing, specific billing cycles, trial periods, end dates for temporary subscriptions, and Merchant Managed Subscriptions.

Key Features

⚠️

WARNING

To follow the steps below, it is essential to have the corresponding Authorization Token. For more information, please refer to the following documentation page: Authorization Token

Create a Direct Subscription

Create a subscription directly without saving a reusable template. This supports all advanced features including pro-rata billing, specific billing cycles, trial periods, and end dates.

💻

Visit our API Reference to test this endpoint.

Endpoint

• POST https://ecartpay.com/api/subscriptions
• POST https://sandbox.ecartpay.com/api/subscriptions

Request Body

📘

Merchant-Managed Subscriptions

For further details on these type of subscriptions, please visit Merchant Management for Subscriptions

Examples

Request

{
    "customer_id": "6854346910775959c2173b48",
    "amount": 599,
    "currency": "MXN",
    "interval": "monthly",
    "frequency": 1,
    "service": "Business Plan",
    "benefits": [
        "Advanced analytics dashboard",
        "Priority customer support",
        "Custom integrations",
        "Team collaboration tools"
    ]
}

{
    "customer_id": "6854346910775959c2173b48",
    "amount": 1299,
    "currency": "MXN",
    "interval": "monthly",
    "frequency": 1,
    "service": "Enterprise Plan",
    "billing_cycle": {
        "day": 15,
        "month": 1
    },
    "trial_period_days": 7,
    "end_date": "2025-12-31",
    "benefits": [
        "Unlimited everything",
        "Dedicated account manager",
        "White-label solution",
        "99.9% SLA guarantee"
    ]
}

Response

{
    "account_id": "6851ef3dd0b39474707f960d",
    "customer_id": "6854346910775959c2173b48",
    "status": "active",
    "service": "Enterprise Plan",
    "amount": 1299,
    "currency": "MXN",
    "interval": "monthly",
    "frequency": 1,
    "trial_period_days": 7,
    "billing_cycle": {
        "day": 15,
        "month": 1
    },
    "end_date": "2025-12-31",
    "attempts": 0,
    "benefits": [
        "Unlimited everything",
        "Dedicated account manager",
        "White-label solution",
        "99.9% SLA guarantee"
    ],
    "errors": [],
    "card_ids": [],
    "id": "687e87d3e0ceebb93d273da9",
    "created_at": "2025-01-21T18:32:51.952Z",
    "updated_at": "2025-01-21T18:32:51.952Z"
}

How Subscription Processing Works

Automatic Payment Flow

1. Subscription Created:

   • POST /api/subscriptions creates subscription WITHOUT card_ids
   • Customer receives email invitation with secure link
   • Subscription status: active but no payment methods

2. Customer Dashboard Access:

   • Option A: Customer clicks email link for direct access
   • Option B: Customer visits sandbox.ecartpay.com/subscriptions/login for OTP login
   • Customer sees subscription details and payment form

3. Payment Method Addition:

   • Customer adds credit card through secure form
   • Frontend calls PUT /api/subscriptions/from-customer/:id with card_ids
   • This triggers automatic payment processing evaluation

4. Smart Processing (triggered by card_ids update):

   • Trial Period: No immediate charge, sets trial dates
   • Pro-rata: Charges proportional amount to next billing date
   • Standard: Charges full amount immediately
   • Failed Payment: Subscription continues with retry logic

Pro-rata Billing

When a subscription has a billing_cycle, the first payment is calculated proportionally:

Formula: (total_amount / days_in_cycle) * days_until_next_billing_date

Example: Monthly subscription with billing_cycle.day = 5 created on January 15th:

• Charges proportional amount from January 15th to February 5th
• Sets next_payment_date = February 5th
• Future payments charge full amount every 5th of the month

Trial Periods

• With Trial: No immediate charge, establishes trial end date
• Trial + Pro-rata: After trial, first charge is proportional to billing cycle
• Trial End: Automatic charge processing when trial period expires

Recurring Payments

• Worker Process: Automatically processes payments for subscriptions with next_payment_date <= today
• Error Handling: Multiple retry attempts with notifications
• End Date Support: Automatic termination for temporary subscriptions

Billing Cycle Configuration

Weekly Billing Cycle

{
    "billing_cycle": {
        "day": 1,    // 1=Monday, 2=Tuesday, ..., 7=Sunday
        "month": 1   // Not used but required
    }
}

Monthly/Quarterly/Semiannual/Yearly Billing Cycle

{
    "billing_cycle": {
        "day": 15,   // Day of month (1-31)
        "month": 3   // Month of year (1-12)
    }
}

Important Notes

• billing_cycle is immutable after creation
• System automatically handles short months (e.g., day 31 in February becomes day 28/29)
• billing_cycle is optional - subscriptions without it work as before
• Not supported for daily interval

Notification System

Automatic Notifications

Events:

• create: Subscription invitation sent to customer
• success: First successful payment
• retry_success: Payment successful after previous failures
• failure: Payment failure (attempt 2)
• final_failure: Multiple failures, subscription paused

Channels:

• Email: Always sent if customer has email

Limits:

• Maximum 5 invitation emails per subscription
• 24-hour cooldown between resend attempts

Customer Access Methods

Method 1: Direct Email Link (Invitation)

• Customer receives invitation email after subscription creation
• Email contains direct link to specific subscription dashboard
• Immediate access to that subscription without additional verification

Method 2: Customer Portal Login

• Customer visits app.ecartpay.com/subscriptions/login
• Enters email address for OTP verification
• Uses OTP endpoints to access all their subscriptions
• Note: Only subscriptions whose invitations have been previously accessed will be visible

Customer Dashboard Features

• Secure Access: Two-method authentication system
• Subscription Details: Plan information, benefits, status, pricing
• Payment Management: Add credit cards (triggers automatic payment processing)
• Billing History: View past and upcoming payments
• Cancellation: Self-service subscription cancellation

OTP Authentication Flow

Endpoints for Customer Login:

• POST /api/notifications/otp-send - Send OTP code to customer email
• POST /api/notifications/otp-verification - Verify OTP code

Process:

1. Customer visits /subscriptions/login
2. Enters email address
3. System sends OTP via otp-send endpoint
4. Customer enters OTP code
5. System verifies via otp-verification endpoint
6. Customer gets authenticated token for session management

Error Handling & Status Management

Subscription States

• Active: Subscription is functioning normally
• Pause: Temporarily paused due to payment failures (≥5 attempts)
• Cancelled: Permanently terminated

Payment Retry Logic

1. Attempt 1: Continue normally
2. Attempt 2: Send failure notification
3. Attempts 3-4: Continue retrying
4. Attempt 5: Pause subscription, send final notification

Validation Rules

• customer_id must exist and belong to the account
• amount must be positive number
• currency must be MXN or USD
• end_date must be future date
• billing_cycle.day must be 1-31
• billing_cycle.month must be 1-12 (except weekly)
• card_ids maximum 5 cards per subscription