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"
}
Get a payment link for a plan
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
}
]