Subscriptions

The process in which a customer subscribes to the recurring item like plan, add-ons or coupon is termed as Subscription.

At the beginning of every term subscriptions are invoiced based on the recurring items and immediately charged against the credit card of customer in case 'auto_collection' is enabled, or else the invoice will be generated as 'Payment Due'.

Create a subscription

While creating the subscription and customer, a plan, multiple addons and coupon can be attached.

Future subscriptions

The subscription will be created in 'future', in case the start date is provided. Also in case 'trial' is provided, the subscription will go into the 'trial' state once it starts. Or else it will become 'active' directly once it starts.

Trial period

In case the plan has trial period or the 'trial end' is provided, the subscription will be created 'in_trial' state.

Once the card info is approved, it is not charged until the trial period ends.

Invoice

Invoice can be revoked immediately, in case the plan have no trial period and if any of the recurring items has charges. In case 'auto_collection' is activated, then card attributes are compulsory and subscription will be created only in case of the successful payment.

Card details

To pass the card details to this API requires PCI accountability at your end as the sensitive card details passes through your servers. In case you want to evade that, you can use one of the below given integration methodologies if pertinent:

  • In case you choose using Stripe gateway, Stripe.js can be used with your checkout form.
  • In case you choose using Braintree gateway, Braintree.js can be used with your checkout form.
  • In case you choose using Authorize.Net gateway, Accept.js can be used with your checkout form.
  • If you choose using the Adyen gateway, use the Client Side Encryption of Adyen to encrypt the sensitive data of card holder. When the data of cardholder is encrypted, pass the value as temp token in this API in adyen.encrypted.data.

Billing address

Whenever the EU VAT taxes are involved, the billing address will be considerable, on the basis of this address the tax calculations will be done. Therefore, EU VAT taxes will not be included for the customers without the billing address. Hence make sure that you have set this properly in case you have configured EU VAT Tax.

Note: In the cases where sites are created prior to 1st Mar 2014, billing address and 'vat_number' of customer will get replaced automatically, whenever the allied card gets updated. i.e. current values for 'vat_number' and billing address will be removed and the new values will get set. This scenario is now changed, the VAT number should not be passed with the card address but along the billing address. Billing Address features shall be overtly passed for customers paying offline through check, cash, bank transfer etc.

Sample Code / Result:
Language
$curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://apiv1.chargemonk.com/createSubscription", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => array ( 'api_token' => 'test_fEZhxDQuOmIMBAVC7K0wtNoPpGgRyed1', 'customer_id' => 'rohit', 'customer_company' => 'Rohit Pvt Ltd', 'customer_first_name' => 'Rohit', 'customer_last_name' => 'Pal', 'customer_email' => 'rohitpal@gmail.com', 'customer_phone' => '9898989898', 'auto_collection' => '1', 'plan_code' => 'basic_plan_test', 'addon_code' => 'basic_addon_test', 'coupon_code' => 'basic_coupon_test', 'start_date' => '1588247074', 'cycles' => '0', 'po_number' => 'PONUM123', 'customer_billing_first_name' => 'Rohit', 'customer_billing_last_name' => 'Pal', 'customer_billing_email' => 'rohitpal@gmail.com', 'customer_billing_phone' => '9898989898', 'address_line_1' => 'Sej Plza', 'address_line_2' => 'Malad West', 'billing_country' => 'IN', 'billing_state' => 'Maharashtra', 'billing_city' => 'Mumbai', 'billing_zip' => '400101', 'ship_to_billing_address' => '0', 'shipping_first_name' => 'Sunil', 'shipping_last_name' => 'Pal', 'shipping_email' => 'sunilpal@gmail.com', 'shipping_phone' => '9898989898', 'shipping_line1' => 'Advent Atria', 'shipping_line2' => 'Malad West', 'shipping_country' => 'IN', 'shipping_state' => 'Maharashtra', 'shipping_city' => 'Mumbai', 'shipping_zip' => '400069', 'invoice_now' => '1', 'card_first_name' => 'Rohit', 'card_last_name' => 'Pal', 'card_number' => '4111111111111111', 'cvv' => '789', 'expiry_month' => '12', 'expiry_year' => '2019', 'gateway_id' => 'chm_ZB2vdrHKuk', 'card_address' => 'Sej Plaza', 'card_extend_address' => '3rd floor', 'card_country' => 'IN', 'card_state' => 'Maharashtra', 'card_city' => 'Mumbai', 'card_zip' => '400101' ), )); $response = curl_exec($curl); curl_close($curl); echo $response;
{ "status": "success", "message": "Subscription added successfully." }

Create Subscription attributes

Key R/O Description
api_token required Token generated by ChargeMonk.
string
customer_id optional Id for the new customer. If not given, this will be auto-generated.
string,  unique
customer_company required Company name of the customer.
string
customer_first_name required First name of the customer.
string,  characters only
customer_last_name required Last name of the customer.
string,  characters only
customer_email required Email of the customer.
string,  unique, email
customer_phone required Phone number of the customer.
integer,  6 digits - 15 digits
auto_collection optional Does payments need to be collected automatically.
Possible values are
1: On forming an invoice, the attempt to charge the payment method of customer is made automatically.
0: There will be no automatic charge collection but offline recording of all payments must be there.
string,  default=1
plan_code required Id of the created plan based on token.
string
plan_currency optional Currency code of the plan.
string,  default=USD
plan_amount optional Amount that will override the Plan's default price.
decimal
plan_quantity optional Quantity of plan. Applicable only for the quantity based plans.
integer,  default=1, min=1
addon_code optional Add recurring and non recurring addons for the customer.
For multiple Addons
eg. addon_code = JX5Xhs, J2Skjfd.
string
coupon_code optional Adds coupon for the customer.
string
addon_price optional Amount that will override the Addon's default price.
decimal
addon_quantity optional Quantity of addons. Applicable only for the quantity based addons.
string,  default=1, min=1
start_date optional Start date for your ‘future’ subscription.Should be greater than or equal to current date.
integer, In timestamp(UTC) in seconds format, default - current date
cycles optional Billing cycles for this subscription is chargeable. In case, configuring for a plan then revoke the billing cycles. Ignore this section, if you are not configuring any billing cycles.
integer,  min=0, default=0
po_number optional Number of the purchase order of this subscription.
string
customer_billing_first_name required First name of the customer billing info.
string,  characters only
customer_billing_last_name required Last name of the customer billing info.
string,  characters only
customer_billing_email required Email of the customer billing info.
string,  unique
customer_billing_phone required Phone number of the customer billing info.
integer,  6 digits - 15 digits
address_line_1 required Address line 1 of the customer billing info.
string
address_line_2 optional Address line 2 of the customer billing info.
string
billing_country required ISO Code of country.
eg. IN, AU, US
string
billing_state required State of the customer billing info.
string
billing_city required City of the customer billing info.
string
billing_zip required Zip/postal code of the customer billing info.
string
ship_to_billing_address optional You want to ship at billing address or a shipping address.
Possible values are
0: You can add shipping address.
1: Your address will be as set in billing address.
integer,  default=1
shipping_first_name optional First name of the customer shipping info.
string,  characters only
shipping_last_name optional Last name of the customer shipping info.
string,  characters only
shipping_email optional Email of the customer shipping info.
string,  unique
shipping_phone optional Phone number of the customer shipping address.
integer,  6 digits - 15 digits
shipping_line1 optional Address line 1 of the customer shipping address.
string
shipping_line2 optional Address line 2 of the customer shipping address.
string
shipping_country optional ISO Code of country.
eg. IN, AU, US
string
shipping_state optional State of the customer shipping address.
string
shipping_city optional City of the customer shipping address.
string
shipping_zip optional Zip/postal code of the customer shipping address.
string
invoice_now optional In case charges are associated, generate an invoice on immediate basis or invoice them later after adding it to the unbilled charges.
Possible values are
0: Invoice will be generated later on.
1: Invoice will be generated on immediate basis .
integer,  default=1
card_first_name required First name of the cardholder.
string,  characters only
card_last_name required Last name of the cardholder.
string,  characters only
card_number required Card number of the card holder.
integer,  13 digits - 19 digits
cvv required Cvv of the cardholder.
integer,  3 digits - 4 digits
expiry_month required Expiry month of the cardholder.
Card month should be greater than equal to current month.
integer,  max: 12
expiry_year required Expiry year of the cardholder.
Card year should be greater than equal to current year.
integer,  4 digits
gateway_id required Code of the payment gateway.
string
card_address required Address of the card holder.
string
card_extend_address optional Extended address of the cardholder.
string
card_country required ISO Code of country.
eg. IN, AU, US
string
card_state required State of the cardholder.
string
card_city required City of the cardholder.
string
card_zip required Zip/Postal code of the cardholder.
string

List Subscription

Here you can find all the listed subscriptions and if you want to search any specific subscription use the filter option and find it directly.

Sample Code / Result:
Language
$curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://apiv1.chargemonk.com/listSubscriptions?api_token=test_fEZhxDQuOmIMBAVC7K0wtNoPpGgRyed1", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", )); $response = curl_exec($curl); curl_close($curl); echo $response;
{ "status": "success", "subscription": [ { "subscriptionId": "STraRQdg", "createdAt": 1574751898, "updatedAt": null, "noOfBillingCycles": 0, "autoCollection": 1, "billingPeriod": "1", "billingPeriodType": "month", "currencyCode": "USD", "startBillingDate": 1581418961, "nextBillingSubscription": 1577298600, "cancelledBillingDate": null, "status": "active", "customer": { "customerCode": "bElefbcC", "firstName": "Sunil", "lastName": "Pal" "autoCollection": 2, "email": "john.doe@gmail.com", "status": "active", "updatedAt": null, "createdAt": 1581418961, }, "billing": { "billingFirstName": "Sunil", "billingLastName": "Pal", "billingEmail": "sunilpal19@gmail.com", "billingPhone": "9889898989" "billingCity": "Columbus" "billingState": "Ohio" "billingZip": "421554" "billingAdd1": "23rd street" }, "plan": { "planName": "Basic Monthly", "planId": "basic_monthly", "planQuantity": "1", "planPrice": "1000.00" "planFreeQuantity": 0 }, "addons": [ { "addonId": "basic_addon_live", "addonName": "basic_addon_live", "addonInvoiceName": "basic_addon_live", "addonCurrency": "USD", "addonPrice": "100.00", "addonType": "0", "addonChargeType": "1", "addonBillingPeriod": "1", "addonBillingPeriodType": "month" "addonQuantity": "" "addonStatus": "active" "addonUpdatedAt": null } ], "coupons": [ { "couponId": "basic_coupon_live", "couponName": "fixed", "couponPrice": "10.00", "couponCurrencyCode": "USD", "couponDiscountType": "Percentage", "couponApplyOn": "invoice", "couponDurationType": "Forever" "couponRedemption": 0 "couponStatus": "active" "couponCreatedAt": 1580798157 "couponUpdatedAt": null } ], "cards": [ { "cardCode": "yDQQ75rs", "cardFirstName": "Sunil", "cardLastName": "Pal", "cardLast4": "1111", "cardIin": "411111", "cardMaskedNumber": "************1111", "cardExpiryMonth": "12", "cardExpiryYear": "2019", "cardGatewayName": "Adyen", "cardType": "visa", "cardStatus": "valid" } ], "invoice": [ { "invoiceCode": "XgKsGzF1", "invoiceSubTotal": "1100.00", "invoiceDiscount": "0.00", "invoiceTotal": "1100.00", "invoiceStatus": "success", "invoiceType": "Recurring" "invoiceCurrency": "USD" "invoiceUrl": "https://chargemonk.s3.amazonaws.com/upload/live/Q2hhcmdlTW9uay01/invoice/3bVmDt6E_1033.pdf", "invoiceDate ": "1574922298" "invoiceCreated ": "1571418961" } ] } ] }

List Subscription attributes

Key R/O Description
api_token required Token generated by ChargeMonk.
string
limit optional Limits the number of records to be shown.
integer,  default=25
page optional The page number depending upon the limit.
eg. In 100 records, limit 10 , page 2 will show records from 11-20
integer,  default=1
search_value optional First name, Last name and Subscription code can be searched.
string
order_by optional Display records in ascending or descending order.
asc, desc,  default=desc
order_param optional You can sort created at or updated at alone as well as with order by field.
eg. order_param = createdAt
createdAt, updatedAt,  default=createdAt
subscriptionCode optional To filter based on Subscription Id.
Operators supported: is, is_not, starts_with, ends_with, contains, does_not_contain
eg. filter[subscriptionCode][is] = 9DpnXa7ks
string
customerCode optional To filter based on Subscription Customer Id.
Operators supported: is, is_not, starts_with, ends_with, contains, does_not_contain
eg. filter[customerCode][ends_with] = a7ks
string
planCode optional To filter based on Subscription Plan Id.
Operators supported: is, is_not, starts_with, ends_with, contains, does_not_contain
eg. filter[planCode][does_not_contain] = 9DpnXa7ks
string
updatedAt optional To filter based on Subscription Updated at.
Operators supported: is, is_not, less_than, less_than_equal, greater_than, greater_than_equal, between
eg. filter[updatedAt][is] = 1588656235
eg. filter[updatedAt][between] = [1588656235,1588656023]
integer, In timestamp(UTC) in seconds format
activatedAt optional To filter based on Subscription Activated at.
Operators supported: is, is_not, less_than, less_than_equal, greater_than, greater_than_equal, between
eg. filter[activatedAt][is] = 1588656235
eg. filter[activatedAt][between] = [1588656235,1588656023]
integer, In timestamp(UTC) in seconds format
createdAt optional To filter based on Subscription Created at.
Operators supported: is, is_not, less_than, less_than_equal, greater_than, greater_than_equal, between
eg. filter[createdAt][less_than] = 1588656235
eg. filter[createdAt][between] = [1588656235,1588656023]
integer, In timestamp(UTC) in seconds format
status optional To filter based on status of the Subscription.
Operators supported: is, is_not
eg. filter[status][is] = active
'active', 'in_trial', 'future', 'cancelled', 'non_renewing', 'deleted'
noOfBillingCycles optional To filter based on No of billing cycles of the Subscription.
Operators supported: is, is_not, less_than, less_than_equal, greater_than, greater_than_equal
eg. filter[noOfBillingCycles][is] = 2
integer
nextBillingSubscription optional To filter based on Next Billing cycle of the Subscription.
Operators supported: is, is_not, less_than, less_than_equal, greater_than, greater_than_equal, between
eg. filter[nextBillingSubscription][is] = 1588656235
eg. filter[nextBillingSubscription][between] = [1588656235,1588656023]
integer, In timestamp(UTC) in seconds format
filter[match] optional 'All' will take 'AND' whereas 'ANY' will take 'OR' as condition.
eg. filter[match]= ALL, filter[subscriptionCode][is] = 9DpnXa7ks, filter[activatedAt][is] = [1588656023] Will be read as Filter if the filed has subscription code like 9DpnXa7ks OR activatedAt is [1588656023].
ANY, ALL

Next Billing Subscription

Fill in the details like API token, next renewal date and renewal date comment in the given fields and update your next billing subscription.

Sample Code / Result:
Language
$curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://apiv1.chargemonk.com/nextBillingSubscription", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => array( 'api_token' => 'test_fEZhxDQuOmIMBAVC7K0wtNoPpGgRyed1', 'subscription_code' => 'WqaEEkM7', 'next_renewal_date' => 1588656023, 'renewal_date_comment' => 'Next bill update.' ), )); $response = curl_exec($curl); curl_close($curl); echo $response;
{ "status": "success", "message": "Next Billing Date Updated Successfully." }

Next billing subscription attributes

Key R/O Description
api_token required Token generated by ChargeMonk.
string
subscription_code required Id of the subscription
string
next_renewal_date required The date on which future renewal should be charged.
integer, In timestamp(UTC) in seconds format
renewal_date_comment required The comment for the future renewal date.
string

Cancel Subscription

When you cancel a subscription, its current state will change into Cancelled state, and all recurring actions for it will stop.

Once you pass the end_of_term parameter as true, the cancellation will get schedule. Now the subscription status will first be set to non_renewing until the end of term, in case it is in the active state, and then cancelled. The state of subscription will not change in case it is in_trial state. Though, at the end of the trial, the cancellation will be scheduled.

Sample Code / Result
Language
$curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://apiv1.chargemonk.com/cancelSubscription", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => array( 'api_token' => 'test_fEZhxDQuOmIMBAVC7K0wtNoPpGgRyed1', 'subscription_code' => 'WqaEEkM7'), )); $response = curl_exec($curl); curl_close($curl); echo $response;
{ "status": "success", "message": "Subscription cancelled successfully." }

Cancel subscription attributes

Key R/O Description
api_token required Token generated by ChargeMonk.
string
subscription_code required Id of the subscription
string

Reactive Subscription

A cancelled subscription is reactivated with the help of this API. In case you want to shift the subscription to the In Trial state, you may specify a trial end date optionally. But in case the trial end is not given, the activation of subscription will take place, and invoice will get generated.

Future Scenario of Reactivation

In case activation date for a cancelled subscription is specified in future e.g. 10th December, but you want to activate it before that; say you activated it on 25th November then the start date will get changed from 10th December to 25th November automatically and the invoice will also get generated for the reactivation. The billing term will be from 25th November to 25th December; i.e. the next bill will get generated on 25th December.

Sample Code / Result:
Language
$curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://apiv1.chargemonk.com/reactivateSubscription", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => array( 'api_token' => 'test_fEZhxDQuOmIMBAVC7K0wtNoPpGgRyed1', 'subscription_code' => 'WqaEEkM7' ), )); $response = curl_exec($curl); curl_close($curl); echo $response;
{ "status": "success", "message": "Subscription activated successfully." }

Reactive subscription attributes

Key R/O Description
api_token required Token generated by ChargeMonk.
string
subscription_code required Id of the subscription
string