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 |