Step-by-Step : Creating a Standard Monthly Subscription

The following workflow example illustrates how a subscription can be implemented.

Step 1: Create the Subscription

POST https://api.ecartpay.com/api/subscriptions
Authorization: Bearer your_jwt_token
Content-Type: application/json

{
    "customer_id": "cust_abc123",
    "amount": 29.99,
    "currency": "USD",
    "interval": "monthly",
    "frequency": 1,
    "service": "Premium Plan",
    "benefits": [
        "Unlimited access",
        "Priority support",
        "Advanced features"
    ]
}

What happens:

✅ Subscription created with status "active"
✅ Customer receives invitation email automatically
✅ No payment methods yet, so no charges
✅ Response includes subscription ID

Step 2: Customer Receives Email

The customer gets an email with:

Subject: "Subscription Invitation - Premium Plan"
Secure link: https://sandbox.ecartpay.com/subscriptions/sub_xyz789?_v=secure_token
Instructions to complete setup

Step 3: Customer Accesses Dashboard

Customer clicks email link and sees:

Subscription details (Premium Plan, $29.99/month)
List of benefits
Secure payment form to add credit card
Terms and conditions

Step 4: Customer Adds Payment Method

Customer fills out credit card form. Frontend calls:

PUT https://api.ecartpay.com/api/subscriptions/from-customer/sub_xyz789
Authorization: Bearer customer_token
Content-Type: application/json

{
    "card_ids": ["card_def456"]
}

What happens automatically:

✅ System evaluates shouldProcessAutomaticPayment()
✅ Since no trial period: charges $29.99 immediately
✅ Sets next_payment_date = today + 1 month
✅ Customer receives "Payment Successful" notification
✅ Subscription is now fully active with payment method

Step 5: Recurring Payments (Automatic)

Every month on the billing date:

✅ Worker finds subscription with next_payment_date <= today
✅ Charges $29.99 to stored card
✅ Updates next_payment_date = next month
✅ If successful: customer gets receipt
✅ If failed: retry logic starts

Alternative: Customer Login Flow

If customer loses the email, they can:

Visit login page:

https://app.ecartpay.com/subscriptions/login

Request OTP:

POST https://api.ecartpay.com/api/notifications/otp-send
Content-Type: application/json

{
    "email": "[email protected]"
}

Verify OTP:

POST https://api.ecartpay.com/api/notifications/otp-verification
Content-Type: application/json

{
    "email": "[email protected]",
    "otp": "123456"
}

Generate session link:

POST https://api.ecartpay.com/api/subscriptions/generate-session-link
Authorization: Bearer otp_verified_token

{
    "subscription_id": "sub_xyz789"
}

Access subscription dashboard with generated link

Pro-rata Example

For a subscription with billing cycle on the 15th of each month, created on January 10th:

Same creation process but with:

{
    "billing_cycle": {
        "day": 15,
        "month": 1
    }
}

When customer adds payment method:
- Charges: ($29.99 / 31 days) * 5 days = $4.84 (Jan 10-15)
- Sets next_payment_date = January 15th
- Future payments: Full $29.99 every 15th

This complete flow ensures customers can successfully subscribe and manage their payments through either email invitation or the customer portal.