Skip to content

Subscription plans

A subscription plan instructs eComCharge how often and how much to charge a customer. Merchants are free to create an unlimited number of subscription plans for their shops.

Each plan has a unique ID which should be submitted in requests.


Create a plan

Request

To create a subscription plan, send a POST request to https://api.ecomcharge.com/plans with the following parameters:

Parameter Type Description
test boolean true or false. The plan will be a test one if it is true.
title * required
string Subscription title.
currency * required
string Currency in ISO-4217 format, for example USD
plan object A section of plan parameters.
amount * required
integer Amount of plan in minimal units.
interval * required
integer Interval of plan.
interval_unit * required
string Interval unit of plan (hour, day or month)
trial object
amount integer Trial period amount in minimal units. Works only together with trial.interval
interval integer Interval of trial period (integer). Works only together with trial.amount
interval_unit string Interval unit of trial period (hour, day or month). Works only with trial.interval_unit
as_first_payment boolean true or false. If true, the system considers the payment for the trial period as the first payment, which allows using all the rules for debiting funds, including recovery after payment errors after the trial period. This increases the risk of using stolen and single-use cards to pay for the trial period. If false, then in case of an error in the payment made after the end of the trial period, new attempts to debit funds will not be provided. Default: false
language string The payment page language, when paying for the plan. English (en) is set by default. Possible values of language parameter.
infinite boolean true or false. Set to true if billing cycles are infinite. Default: true
billing_cycles integer Billing cycles number. It is ignored if the infinite parameter is set to true.
number_payment_attempts integer Number of failed payment attempts before cancelling a subscription. Default: 3.

If the charge attempt fails, but there were previously successful charges within this subscription, the system will keep making payment attempts the following day:

- at 3 AM if "prevent_payments_at_night":false,
- at 8 AM if "prevent_payments_at_night":true

The attempts will be made until the payment is succesful or until the specified number of attempts runs out.

If the charge results in an error, but there were previously successful charges from this card within this plan, the next attempt will be made at the beginning of each following hour (with the exception of 8:00 PM —8:00 AM period if "prevent_payments_at_night": true) until the specified number of attempts runs out.
prevent_payments_at_night boolean true or false. If true, subscription payments are processed only during the period from 8:00 AM to 8:00 PM in the time zone set for the system. false is set by default.
Example of the requests for creating a plan with infinite billing cycles
curl https://api.ecomcharge.com/plans \
  -X POST -u shop_id:secret_key \
  -H "Content-Type: application/json" \
  -d \
'
{
  "test": true,
  "title": "Basic plan",
  "currency": "USD",
  "plan": {
    "amount": 20,
    "interval": 20,
    "interval_unit": "day"
  },
  "trial": {
    "amount": 10,
    "interval": 10,
    "interval_unit": "hour"
  },
  "language": "en",
  "infinite": true,
  "billing_cycles": null,
  "number_payment_attempts": 3,
}
'
Example of the requests for creating a plan with finite billing cycles
  {
    "test": true,
    "title": "Basic plan",
    "currency": "USD",
    "plan": {
      "amount": 20,
      "interval": 20,
      "interval_unit": "day"
    },
    "trial": {
      "amount": 10,
      "interval": 10,
      "interval_unit": "hour"
    },
    "language": "en",
    "infinite": false,
    "billing_cycles": 12,
    "number_payment_attempts": 3
  }
Response

If credentials and parameters are valid, eComCharge will return 201 HTTP status code and a new plan object with all the relevant details. Otherwise, eComCharge will return 422 HTTP status code and an error message.

Response example
{
    "id": "pln_a134847c902551de",
    "title": "Basic plan",
    "currency": "USD",
    "language": "en",
    "plan": {
        "amount": 20,
        "interval": 20,
        "interval_unit": "day"
    },
    "trial": {
        "amount": 10,
        "interval": 10,
        "interval_unit": "hour"
    },
    "number_payment_attempts": 3,
    "test": true
}
Example of the response to the request when a parameter is invalid or not included
{
    "errors": {
        "title": [
            "can't be blank"
        ]
    },
    "message": "Title can't be blank"
}

To get a payment for a plan, route the customer's browser via a GET or POST request to https://api.ecomcharge.com/plans/{plan_id}/pay, where {plan_id} stands for the identifier of the plan.


Get subscription plan details

To get details of a subscription plan, send a GET request to https://api.ecomcharge.com/plans/{plan_id}, where {plan_id} stands for the identifier of the plan.

If the plan ID exists, eComCharge will return 200 HTTP status code and the plan details.

Example of the request to get details of the plan with the ID pln_a134847c902551de
curl -u shop_id:secret \
  https://api.ecomcharge.com/plans/pln_a134847c902551de
Response example
{
    "id": "pln_a134847c902551de",
    "title": "Basic plan",
    "currency": "USD",
    "language": "en",
    "plan": {
        "amount": 20,
        "interval": 20,
        "interval_unit": "day"
    },
    "trial": {
        "amount": 10,
        "interval": 10,
        "interval_unit": "hour"
    },
    "number_payment_attempts": 3,
    "test": true
}

Get a list of plans

To get a list of all plans, send a GET request to https://api.ecomcharge.com/plans.

If there are plans, eComCharge will return 200 HTTP status code and an array of plans.

Example of the request with a list of plans
curl -u shop_id:secret \
  https://api.ecomcharge.com/plans
Response example
[
    {
        "id": "pln_2b0c211f50deb72c",
        "title": "Basic plan",
        "currency": "USD",
        "language": "en",
        "plan": {
            "amount": 20,
            "interval": 7,
            "interval_unit": "day"
        },
        "trial": {
            "amount": 10,
            "interval": 40,
            "interval_unit": "hour"
        },
        "number_payment_attempts": 3,
        "test": true
    },
    {
        "id": "pln_75eca73bfdcf143a",
        "title": "Pro plan",
        "currency": "USD",
        "language": "fr",
        "plan": {
            "amount": 30,
            "interval": 7,
            "interval_unit": "day"
        },
        "trial": {
            "amount": 10,
            "interval": 40,
            "interval_unit": "hour"
        },
        "number_payment_attempts": 5,
        "test": true
    }
]