Documentation
Start typing to search…

Subscriptions Management

⚠️

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

Get All Subscriptions

💻

Visit our API Reference to test this endpoint.

Endpoint

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

Headers

  • Authorization: token

Query parameters

  • status: Filter by subscription status (active, pause, cancelled)
  • currency: Filter by currency (MXN, USD)
  • interval: Filter by billing interval
  • customer_id: Filter by customer ID
  • created_from: Filter by creation date (from)
  • created_to: Filter by creation date (to)

Examples

Request

curl --request GET \
     --url 'https://sandbox.ecartpay.com/api/subscriptions?limit=50&page=1' \
     --header 'accept: application/json, text/plain, */*' \
     --header 'authorization: sha512-ISUVO/6BRQXIK99xBXzPepY/L0HODhZKfN2nu7qJLOBhwttqqdDVHUPeye88km3M6ffb8p+jvnuy0/GChy4bXw==?40MQ'

Response

{
  "count": 5,
  "docs": [
    {
      "id": "68cdd2842ebbd864ef059570",
      "account_id": "68a4c3150b28a9584305a2a6",
      "customer_id": "68cdcfa92ebbd864ef059453",
      "card_ids": [
        "68cdd3022ebbd864ef05958c",
        "68cdd5122ebbd864ef0596b4",
        "68cdd5b62ebbd864ef0596e9",
        "68cdd5ed2ebbd864ef059717",
        "68cdd6052ebbd864ef059742"
      ],
      "status": "pause",
      "service": "Tacos cada mes",
      "amount": 200,
      "currency": "MXN",
      "interval": "daily",
      "frequency": 1,
      "trial_period_days": 0,
      "attempts": 5,
      "benefits": [
        "Tortillas extra",
        "Salsa verde",
        "Salsa roja",
        "Salsa guacamole",
        "Sal",
        "Limón"
      ],
      "errors": [
        "Problema al procesar el pago, pruebe con otra tarjeta. | discover 0842",
        "AMEX is not active, try another card. | amex 3998",
        "Problema al procesar el pago, pruebe con otra tarjeta. | jcb 0000",
        "Problema al procesar el pago, pruebe con otra tarjeta. | visa 3705",
        "Problema al procesar el pago, pruebe con otra tarjeta. | visa 4062"
      ],
      "created_at": "2025-09-19T22:00:36.182Z",
      "updated_at": "2025-09-19T22:15:34.880Z",
      "account_customer_id": "68cdcffb2ebbd864ef059465",
      "customer": {
        "id": "68cdcfa92ebbd864ef059453",
        "account_id": "68a4c3150b28a9584305a2a6",
        "email": "[email protected]",
        "first_name": "Prime",
        "last_name": "NueveCinco",
        "phone": "8116126767",
        "gateways": [],
        "created_at": "2025-09-19T21:48:25.149Z",
        "updated_at": "2025-09-19T21:49:47.728Z",
        "account_customer_id": "68cdcffb2ebbd864ef059465"
      }
    },
    {
      "id": "68cdd2162ebbd864ef0594fb",
      "account_id": "68a4c3150b28a9584305a2a6",
      "customer_id": "68cdcfa92ebbd864ef059453",
      "card_ids": [
        "68cdd25b2ebbd864ef059510"
      ],
      "status": "cancelled",
      "service": "Tacos cada mes",
      "amount": 200,
      "currency": "MXN",
      "interval": "daily",
      "frequency": 1,
      "trial_period_days": 0,
      "attempts": 0,
      "benefits": [
        "Tortillas extra",
        "Salsa verde",
        "Salsa roja",
        "Salsa guacamole",
        "Sal",
        "Limón"
      ],
      "errors": [],
      "created_at": "2025-09-19T21:58:46.904Z",
      "updated_at": "2025-09-19T22:00:05.097Z",
      "account_customer_id": "68cdcffb2ebbd864ef059465",
      "last_payment_date": "2025-09-19T21:59:56.838Z",
      "next_payment_date": "2025-09-20T21:59:56.838Z",
      "customer": {
        "id": "68cdcfa92ebbd864ef059453",
        "account_id": "68a4c3150b28a9584305a2a6",
        "email": "[email protected]",
        "first_name": "Prime",
        "last_name": "NueveCinco",
        "phone": "8116126767",
        "gateways": [],
        "created_at": "2025-09-19T21:48:25.149Z",
        "updated_at": "2025-09-19T21:49:47.728Z",
        "account_customer_id": "68cdcffb2ebbd864ef059465"
      }
    },
    {
      "id": "68cdcfa92ebbd864ef059459",
      "account_id": "68a4c3150b28a9584305a2a6",
      "customer_id": "68cdcfa92ebbd864ef059453",
      "card_ids": [
        "68cdd0a02ebbd864ef0594a0",
        "68cdd0632ebbd864ef059474"
      ],
      "status": "pause",
      "service": "Tacos diario",
      "amount": 150,
      "currency": "MXN",
      "interval": "daily",
      "frequency": 1,
      "trial_period_days": 0,
      "attempts": 5,
      "benefits": [
        "Salsa verde",
        "Salsa roja",
        "Cilantro",
        "Cebolla",
        "Coca de uva"
      ],
      "errors": [
        "AMEX is not active, try another card. | amex 3998",
        "CONSTANTS is not defined | mastercard 2235",
        "CONSTANTS is not defined | amex 3998",
        "CONSTANTS is not defined | mastercard 2235",
        "CONSTANTS is not defined | amex 3998",
        "CONSTANTS is not defined | mastercard 2235",
        "CONSTANTS is not defined | amex 3998",
        "CONSTANTS is not defined | mastercard 2235",
        "CONSTANTS is not defined | amex 3998",
        "CONSTANTS is not defined | mastercard 2235"
      ],
      "created_at": "2025-09-19T21:48:25.509Z",
      "updated_at": "2025-09-23T21:56:01.297Z",
      "account_customer_id": "68cdcffb2ebbd864ef059465",
      "last_payment_date": "2025-09-22T21:53:14.964Z",
      "next_payment_date": "2025-09-23T21:52:34.090Z",
      "customer": {
        "id": "68cdcfa92ebbd864ef059453",
        "account_id": "68a4c3150b28a9584305a2a6",
        "email": "[email protected]",
        "first_name": "Prime",
        "last_name": "NueveCinco",
        "phone": "8116126767",
        "gateways": [],
        "created_at": "2025-09-19T21:48:25.149Z",
        "updated_at": "2025-09-19T21:49:47.728Z",
        "account_customer_id": "68cdcffb2ebbd864ef059465"
      }
    },
    {
      "id": "68cdcbfed75e4961c7188678",
      "account_id": "68a4c3150b28a9584305a2a6",
      "customer_id": "68cdcbfed75e4961c7188672",
      "card_ids": [],
      "status": "active",
      "service": "Clases online",
      "amount": 399,
      "currency": "MXN",
      "interval": "monthly",
      "frequency": 1,
      "trial_period_days": 0,
      "attempts": 0,
      "benefits": [],
      "errors": [],
      "created_at": "2025-09-19T21:32:46.682Z",
      "updated_at": "2025-09-19T21:32:46.682Z",
      "customer": {
        "id": "68cdcbfed75e4961c7188672",
        "account_id": "68a4c3150b28a9584305a2a6",
        "email": "[email protected]",
        "first_name": "Elba",
        "last_name": "Lazo",
        "phone": "1234567890",
        "gateways": [],
        "created_at": "2025-09-19T21:32:46.409Z",
        "updated_at": "2025-09-19T21:32:46.409Z"
      }
    },
    {
      "id": "68c03f23acc9edbc2d955dd5",
      "account_id": "68a4c3150b28a9584305a2a6",
      "customer_id": "68addeca2dfa130e54601129",
      "card_ids": [],
      "status": "cancelled",
      "service": "Tacos cada mes",
      "amount": 200,
      "currency": "MXN",
      "interval": "daily",
      "frequency": 1,
      "trial_period_days": 0,
      "attempts": 0,
      "benefits": [
        "Tortillas extra",
        "Salsa verde",
        "Salsa roja",
        "Salsa guacamole",
        "Sal",
        "Limón"
      ],
      "errors": [],
      "created_at": "2025-09-09T14:52:19.034Z",
      "updated_at": "2025-09-19T21:38:13.580Z",
      "customer": {
        "id": "68addeca2dfa130e54601129",
        "account_id": "68a4c3150b28a9584305a2a6",
        "first_name": "Roberto Alejandro",
        "last_name": "de la Cruz Martinez",
        "phone": "8114854378",
        "user_id": "004",
        "gateways": [],
        "created_at": "2025-08-26T16:20:26.714Z",
        "updated_at": "2025-08-26T16:20:26.714Z"
      }
    }
  ],
  "pages": 1
}

Get Single Subscription

💻

Visit our API Reference to test this endpoint.

Endpoint

  • GET https://ecartpay.com/api/subscriptions/:id
  • GET https://sandbox.ecartpay.com/api/subscriptions/:id

Headers

  • Authorization: token

Path Parameters

  • id

Examples

Request

curl --request GET \
     --url https://sandbox.ecartpay.com/api/subscriptions/68cdcfa92ebbd864ef059459 \
     --header 'accept: application/json, text/plain, */*' \
     --header 'authorization: sha512-9cWkmQcx8hTPOzCompT/3VZ440XO5pVCzLkRDusfrIJdMjTv/jIdwlTOg2hVmBV6yy9AMR/EoWOKp9Qz0n7aLQ==?7nHQ'

Response

{
  "id": "68cdcfa92ebbd864ef059459",
  "account_id": "68a4c3150b28a9584305a2a6",
  "customer_id": "68cdcfa92ebbd864ef059453",
  "card_ids": [
    "68cdd0a02ebbd864ef0594a0",
    "68cdd0632ebbd864ef059474"
  ],
  "status": "active",
  "service": "Tacos diario",
  "amount": 150,
  "currency": "MXN",
  "interval": "daily",
  "frequency": 1,
  "trial_period_days": 0,
  "attempts": 0,
  "benefits": [
    "Salsa verde",
    "Salsa roja",
    "Cilantro",
    "Cebolla",
    "Coca de uva"
  ],
  "errors": [],
  "created_at": "2025-09-19T21:48:25.509Z",
  "updated_at": "2025-09-19T21:52:34.876Z",
  "account_customer_id": "68cdcffb2ebbd864ef059465",
  "last_payment_date": "2025-09-19T21:52:34.090Z",
  "next_payment_date": "2025-09-20T21:52:34.090Z",
  "customer": {
    "id": "68cdcfa92ebbd864ef059453",
    "email": "[email protected]",
    "first_name": "Prime",
    "last_name": "NueveCinco",
    "phone": "8116126767"
  },
  "cards": [
    {
      "id": "68cdd0632ebbd864ef059474",
      "brand": "amex",
      "last": "3998",
      "default": true
    },
    {
      "id": "68cdd0a02ebbd864ef0594a0",
      "brand": "mastercard",
      "last": "2235",
      "default": false
    }
  ]
}

Update Subscription

This critical endpoint adds or removes payment methods to a subscription. When card_ids are added, the system automatically determines the payment processing schedule based on the subscription's trial periods, billing cycles, and payment dates.

💻

Visit our API Reference to test this endpoint.

Endpoint

  • PUT https://ecartpay.com/api/subscriptions/:id
  • PUT https://sandbox.ecartpay.com/api/subscriptions/:id

Headers

  • Authorization: token

Path Parameters

  • id

Body

  • status: Can be active, paused, or cancelled.
  • card_ids: The card id.

Examples

Request

curl --request PUT \
     --url https://sandbox.ecartpay.com/api/subscriptions/from-customer/68dc05f2ff8f016d8e16aa43 \
     --header 'accept: application/json, text/plain, */*' \
     --header 'authorization: sha512-Xb0AEuTLnMly9QIqIXpOhBMPZPZ3JhDqzSAmGw6dMEyJwGxf1s9nqxto+grIFKIOStuCiS9ZRwMAW59g0xkRXg==?QGVA' \
     --header 'content-type: application/json' \
     --data '
{
  "status": "active",
  "card_ids": ["68cdd3022ebbd864ef05958c", "68cdd25b2ebbd864ef059510"]
}
'

Response

{
  "id": "68dc05f2ff8f016d8e16aa43",
  "account_id": "68a4c3150b28a9584305a2a6",
  "customer_id": "68cdcfa92ebbd864ef059453",
  "card_ids": [
        "68cdd3022ebbd864ef05958c",
        "68cdd25b2ebbd864ef059510"
  ],
  "status": "active",
  "service": "Tacos cada semana",
  "amount": 200,
  "currency": "MXN",
  "interval": "weekly",
  "frequency": 1,
  "trial_period_days": 0,
  "attempts": 0,
  "benefits": [
    "Tortillas extra",
    "Salsa verde",
    "Salsa roja",
    "Salsa guacamole",
    "Sal",
    "Limón"
  ],
  "errors": [],
  "created_at": "2025-09-30T16:31:46.631Z",
  "updated_at": "2025-09-30T16:34:05.112Z",
  "account_customer_id": "68cdcffb2ebbd864ef059465",
  "payment_processed": true,
  "payment_message": "The payment was successful and your subscription has started.",
  "subscription_started": true
}

Automatic Payment Logic:

  • First card added triggers shouldProcessAutomaticPayment() evaluation
  • If trial period active: No charge, sets trial end date
  • If billing cycle configured: Charges pro-rata amount
  • If standard subscription: Charges full amount immediately

Customer Update Subscription

Allows customers to update their own subscriptions from their dashboard. This is the endpoint used by the customer portal when they add payment methods.

💻

Visit our API Reference to test this endpoint.

Endpoint

  • PUT https://ecartpay.com/api/subscriptions/from-customer/:id
  • PUT https://sandbox.ecartpay.com/api/subscriptions/from-customer/:id

Headers

  • Authorization: token

Path Parameters

  • id

Body

  • status: Can be active, paused, or cancelled.
  • card_ids: The card id.

Examples

Request

curl --request PUT \
     --url https://sandbox.ecartpay.com/api/subscriptions/from-customer/68cdd2842ebbd864ef059570 \
     --header 'accept: application/json, text/plain, */*' \
     --header 'authorization: sha512-Xl7z9ovBPE9n9BrJQ26EpAB5gZuTo5rL0tf9uGDGHw6nlSpzjxQc+XnOA7KKaE+v4ujKg28m4WQw/7cXMQkfXQ==?VEwg' \
     --header 'content-type: application/json' \
     --data '
{
  "status": "active",
  "card_ids": [
    "68cdd3022ebbd864effffffc",
    "68cdd5122ebbd864effffff4",
    "68cdd5b62ebbd864effffff9"
  ]
}
'

Response

{
  "id": "68cdd2842ebbd864ef059570",
  "account_id": "68a4c3150b28a9584305a2a6",
  "customer_id": "68cdcfa92ebbd864ef059453",
  "card_ids": [
    "68cdd3022ebbd864effffffc",
    "68cdd5122ebbd864effffff4",
    "68cdd5b62ebbd864effffff9"
  ],
  "status": "active",
  "service": "Tacos cada mes",
  "amount": 200,
  "currency": "MXN",
  "interval": "daily",
  "frequency": 1,
  "trial_period_days": 0,
  "attempts": 2,
  "benefits": [
    "Tortillas extra",
    "Salsa verde",
    "Salsa roja",
    "Salsa guacamole",
    "Sal",
    "Limón"
  ],
  "errors": [
    "Problema al procesar el pago, pruebe con otra tarjeta. | discover 0842",
    "AMEX is not active, try another card. | amex 3998"
  ],
  "created_at": "2025-09-19T22:00:36.182Z",
  "updated_at": "2025-09-19T22:14:14.195Z",
  "account_customer_id": "68cdcffb2ebbd864ef059465",
  "payment_processed": false,
  "payment_message": "The payment could not be processed with this card. Try adding another payment method.",
  "subscription_started": false
}

Customer Dashboard Process:

  1. Customer accesses subscription via email link or customer subscriptions dashboard
  2. Customer adds credit card in secure form
  3. Frontend calls this endpoint with new card_ids
  4. Automatic payment processing triggers based on subscription configuration
❗️

Important

The customer must have previously accessed the subscription invitation for it to appear in their subscriptions dashboard.


Resend Invitation Link

Resends the subscription invitation email to the customer. Limited to 5 invitations per subscription with 24-hour cooldown.

💻

Visit our API Reference to test this endpoint.

Endpoint

  • POST https://ecartpay.com/api/subscriptions/:id/resend-invitation-link
  • POST https://sandbox.ecartpay.com/api/subscriptions/:id/resend-invitation-link

Headers

  • Authorization: token

Path Parameters

  • id

Examples

Request

curl --request POST \
     --url https://sandbox.ecartpay.com/api/subscriptions/68dc0d3cff8f016d8e16abee/resend-invitation-link \
     --header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY4YTRjMzE1MGIyOGE5NTg0MzA1YTJhYSIsImFjY291bnRfaWQiOiI2OGE0YzMxNTBiMjhhOTU4NDMwNWEyYTYiLCJhY2NvdW50Ijp7ImVtYWlsIjoiaHVnby5tb3JpbkBlY2FydHBheS5jb20iLCJmaXJzdF9uYW1lIjoiSHVnbyIsImxhc3RfbmFtZSI6Ik1vcsOtbiIsInBob25lIjoiNTI4MTE2MTI2NzY3IiwiY291bnRyeSI6Ik1YIiwiY3VycmVuY3kiOiJNWE4iLCJ2ZXJpZmllZCI6dHJ1ZSwiYWN0aXZlIjp0cnVlfSwiaWF0IjoxNzU5MjQ5MTk1LCJleHAiOjE3NTkyNTI3OTV9.zLEgqmMfqoOlzoC_Qh58mTOMhArAugIPOxP5ypD-MIiycouPvM0Y9KjKBWKlSLdc4zKSIPO4MBhJt0L8gr3xhw'

Response

{
    "message": "Invitation link sent successfully"
}

Generate Session Link

Generates a secure link for customers to access a specific subscription dashboard. This endpoint is used internally after OTP verification to create session links.

💻

Visit our API Reference to test this endpoint.

Endpoint

  • POST https://ecartpay.com/api/subscriptions/generate-session-link
  • POST https://sandbox.ecartpay.com/api/subscriptions/generate-session-link

Headers

  • Authorization: token

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/subscriptions/generate-session-link' \
--header 'Authorization: eyJhbGciOiJIUzUxMhMeDnR5cCI6IkpXVCJ9.eyJfDGI6IjY4YTRjMzE1MGIyOGE5NTg0MzA1YTJhYSIsImFjY291bnRfaWQiOiI2OGE0YzMxNTBiMjhhOTU4NDMwNWEyYTYiLCJhY2NvdW50Ijp7ImVtYWlsIjoiaHVnby5tgrEpbkBlY2FydHBheS5jb20iLCJmaXJzdF9uYW1lIjoiSHVnbyIsImxhc3RfbmFtZSI6Ik1vcsOtbiIsInBob25lIjoiNTI4MTE2MTI2NzY3IiwiY291bnRyeSI6Ik1YIiwiY3VycmVuY3kiOiJNWE4iLCJ2ZXJpZmllZCI6dHJ1ZSwiYWN0aXZlIjp0cnVlfSwiaWF0IjoxNzU5ODUzMjczLCJleHAiOjE3NTk4NTY4NzN9.gsLgWQvSbq27YQvNIzivZHqbQDkNHOooRgeO0klO89CA8NnLnq2yn_jAKbwhov8rznMvAy9_ZYzJTN9PD_gfDG' \
--header 'Content-Type: application/json' \
--header 'Cookie: lang=en' \
--data '{
    "subscription_id": "68dc0d3cff8f016d8e16abee"
}'

Response

{
    "session_link": "https://sandbox.ecartpay.com/subscriptions/687e87d3e0ceebb93d273da9?_v=auth_token"
}

Note: The generated session link is identical to the one sent in invitation emails. Used by the customer portal after OTP authentication.

📘

Note

The generated session link is identical to the one sent in invitation emails. Used by the customer portal after OTP authentication.


Updated 5 days ago