Documentation
Start typing to search…

Merchant Management for Subscriptions

Merchant Management is a feature that allows you to delegate subscription lifecycle control to your own systems while EcartPay handles payment processing and checkout. When enabled, you receive invitation links directly in API responses and manage customer communications yourself, rather than relying on EcartPay's automated notifications.

Key Differences

Standard Subscriptions (Default)

  • Ecart Pay sends all customer emails and SMS notifications
  • Automatic payment retry notifications
  • Full customer portal access
  • Invitation links sent directly to customers via email

Merchant-Managed Subscriptions

  • No customer notifications from Ecart Pay
  • API response returns a checkout_link for you to distribute
  • Webhook notifications are sent to your notify_url
  • You control all customer communications
  • Limited customer portal functionality

⚠️

IMPORTANT

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

Creating a Merchant-Managed Subscription

Creating a Merchant-Managed Subcription is very similar to creating a direct subscription with the main difference being that you add the merchant_management boolean field and set it to true.

When merchant_management is set to true, you must provide:

  • notify_url: The webhook endpoint where EcartPay will send subscription event notifications. This field is required for creating a Merchant-Managed Subscription.
💻

Visit our API Reference to test this endpoint.

Endpoint

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

POST https://sanbdox.ecartpay.com/api/subscriptions

Header

Authorization: token

Example

Request

curl --location 'https://sandbox.ecartpay.com/subscriptions' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY4YTRjMzE1MGIyOGE5NTg0MzA1YTJhYSIsImFjY291bnRfaWQiOiI2OGE0YzMxNTBiMjhhOTU4NDMwNWEyYTYiLCJhY2NvdW50Ijp7ImVtYWlsIjoiaHVnby5tb3JpbkBlY2FydHBheS5jb20iLCJmaXJzdF9uYW1lIjoiSHVnbyIsImxhc3RfbmFtZSI6Ik1vcsOtbiIsInBob25lIjoiNTI4MTE2MTI2NzY3IiwiY291bnRyeSI6Ik1YIiwiY3VycmVuY3kiOiJNWE4iLCJ2ZXJpZmllZCI6dHJ1ZSwiYWN0aXZlIjp0cnVlfSwiaWF0IjoxNzU5MzM3OTU5LCJleHAiOjE3NTkzNDE1NTl9.FdrGZ8UqJ4bp48ClKwRXUcHn8EGuK5UDM30wsngbHb0MGJE7hNVAN-XW0FNJPda2rsrnvzs0bAuHMdm1E4Yd6A' \
--header 'Content-Type: application/json' \
--header 'Cookie: _cid=9732c680-2343-4b1e-a242-7677212b8425; _ctk=b8de975f20ee4889a9ed7f4be14d1e06; lang=en' \
--data '{
  "frequency": "1",
  "billing_cycle": {
    "day": 28,
    "month": 1
  },
  "customer_id": "68cdcfa92ebbd864ef059453",
  "amount": 50,
  "currency": "MXN",
  "interval": "monthly",
  "service": "Suscripción mensual de: Devocional TcD",
  "merchant_management": true,
  "notify_url": "https://yourwebsite.com/webhooks/subscription",
  "trial_period_days": 30,
  "benefits": [
    "Entrega mensual del devocional antes del inicio de mes"
  ]
}'

Response

{
    "account_id": "68a4c3150b28a9584305a2a6",
    "customer_id": "68cdcfa92ebbd864ef059453",
    "card_ids": [],
    "status": "active",
    "service": "Suscripción mensual de: Devocional TcD",
    "amount": 50,
    "currency": "MXN",
    "interval": "monthly",
    "frequency": 1,
    "trial_period_days": 30,
    "billing_cycle": {
        "day": 28,
        "month": 1
    },
    "notify_url": "https://yourwebsite.com/webhooks/subscription",
    "merchant_management": true,
    "attempts": 0,
    "benefits": [
        "Entrega mensual del devocional antes del inicio de mes"
    ],
    "errors": [],
    "id": "68dd6aae415083138159dbe9",
    "created_at": "2025-10-01T17:53:50.965Z",
    "updated_at": "2025-10-01T17:53:50.965Z",
    "checkout_link": "https://sandbox.ecartpay.com/subscriptions/68dd6aae415083138159dbe9?_v=d7e91f163caf8b4c5a3f76f4f52b03cbe683986be69e2d3bc843a893fe5d60e4bb4aaa834fed9875ea8c393eddebfd6ec9972066984d699453334c66f1bf1effd15a6e5eb3493f3fc52fea5570ca9291844cbb417b8bfc227f7a41a1568917c2be0f4f19de69c780942c401ada873879085af7eb47e7ea37847cf13e2186438f7a23b224e7d0a6820ea41bd5a1b1d1eff412f7fa559770761ceee66dac27c73671e4c53ed9deaa984d26300f832b89ce2e29c614269efa0e2f0d6bbb4f2c24002a338275b439655636164ef24721b3188642e8c88e5c1145412bf4e462e7f849b482ed2232c9b63bd46cd951d882529a6a526ab8a866289764d279365ed4855d681a3a8f6ffbbcac0b4fc2a7060faa7cf59015d07dc2b7cd14a55e10a4082184de6c6853f8c8d2c5165658b48060579622c168b37e0ac9873897cf51a3af8996579d800fad36c67fea8bf4d7025b7819491176db553bb21bee0854063a0b180e73ef70b3d97ea10c3585ccd4d2fa529f27cb34be3c87dd428349cf47e74a83f5754bab8d621ddd8fb292f6375e3e53126645826f28da93e4e9d104cd95d0a21bae7a151de9455cafc54d79938da8224f1b061b86688bc330983c1fb9831573f1634d66711e12dd83eeba69423ceae5d78757658d34dcd3829620f7671a14db8bf0429523bdc711b5d4a6ee5944343f0583da7d14e243269670c5eedcede893e9a3f8ce23595e7f0e47334de205ba46551e53d388cf833ef3c044ec831bcc07b5f98c917ecec2aa18c5943508d6d3cf03a98dd59d7bbe89bb37f5c23b68bfe45d9d866cb6d09e34127e14751c66d2dfdb"
}

🔔

Webhook Events

Your notify_url endpoint will receive POST requests for these events:

  • Subscription created
  • Payment successful
  • Payment failed
  • Payment retry attempted
  • Subscription paused
  • Subscription cancelled

When to Use Merchant Management

Consider this feature when you need:

  • Complete control over customer communication templates and timing.
  • Integration with existing subscription management systems.
  • Custom subscription workflows and business logic.
  • Branded customer experience without EcartPay notifications.
  • Specialized handling of subscription lifecycle events.

Backwards Compatibility

  • All existing subscriptions continue working without changes.
  • The merchant_management field defaults to false if not specified.
  • Standard subscription behavior remains unchanged.


Updated 2 days ago