1. Integration Options
Sellers can choose to integrate with SubSuite via API and Webhooks (recommended) or Manually with Coupon Codes. API integration ensures a more seamless user experience and limited administration. Coupon codes allow for a quick and easy non-technical solution to get started.
1. What we do (Webhooks): (Purchases, Cancellations, Upgrades, Verification):
SubSuite sends requests to you every time a subscriber purchases, cancels, upgrades, or claims to be an active subscriber (subscriber verification).
2. What you do (API) (Cancellations):
Required: You will send us a request when a subscriber that registered with SubSuite cancels. Optional: With our API you can also request ANY fields you want from our database - get real time data at your fingertips. No additional setup.
View Field List and methods: for developer implementation
B) Method 2: Coupon Codes (Non-Technical - requires no coding)
1. Create coupon codes:
You will create and upload coupon codes to be used for each base plan. Coupon codes will allow new subscribers from SubSuite free lifetime access to that specific plan (payments are already processed at purchase so coupons need to be free, so the subscriber is not charged twice). Coupon codes should not be re-usable, and every subscriber will get their own unique code. New subscribers are directed to the login / registration web / app links you supply in your dashboard.
2. Email Confirmations:
You will receive automated emails confirming purchases, cancellations and upgrades and will need to manually update your systems. You will need to send us an email when one of your subscribers that joined SubSuite cancels or upgrades their service. Processes can be automated.
2. Payment Processing
Payments are immediately routed directly to your bank from Stripe without going to SubSuite first. Setup is fast and easy.
3. Customer Service
You can manage and own all non-payment related customer service processes normally. Chargebacks and payment issues are handled by SubSuite and Stripe, but you can initiate refunds, see all subscriber transaction / payment information and communicate anything back to your subscribers. Cancellations can be facilitated by either party if you integrate via API. Coupon code cancelations need to happen on SubSuite. You can provide subscribers with our email address:
4. Lifecycle Management
SubSuite works hard to retain your SubSuite subscribers, and keep them informed. While no additional management is needed for your subscribers that register for SubSuite, you are welcome to contact and engage with them at any time. We process all updates, free trial notices, cancelation emails, winback emails, etc. The only necessary interaction on your side, is a welcome email upon first registration, described below.
5. Subscriber First Access
If integrated via API, we recommend you send your own automated welcome email at purchase with instructions on accessing your services for the first time (if this a digital subscription) or confirmation that their delivery is being processed (for retail / physical delivery subscriptions). For digital services, include links to register for the first time (app download + instructions, web registration links, etc. - whatever works for your process) as well as any passwords they should use for their first registration or let them know to use your "forgot password" function on their first login. After they register, they can come back again to your login pages directly or navigate to your login pages from their dashboard on your SubSuite page.
== PURCHASE WEBHOOK ==
URL: <Provider specified>
Method: POST
REQUEST:
{
"event": "purchase",
"secret_key": "72d5de4b0e08518a8ea03f323c07c4f2",
"first_name": "Jimmy",
"last_name": "Subs",
"email": "
"shipping_required": "true",
"shipping_address": "123 Elm St",
"shipping_address2": "Apt 5",
"shipping_city": "Omaha",
"shipping_state": "NE",
"shipping_postal_code": "68102",
"shipping_country": "US",
"subsuite_user_id": "1",
"subsuite_subscription_id": "203",
"plan_name": "Premium",
"plan_term": "1 month",
"plan_price": "19.99",
"primary_plan": "false",
"subsuite_price": "14.99",
"subsuite_fee_percent": "13.00",
"processing_percent": "2.90",
"processing_fee": "0.30",
"net_payment": "12.31",
"purchase_datetime": "2024-05-24 20:21:35"
}
RESPONSE:
{
"received": "true"
}
Notes:
Your actual secret key can be found in the Integration tab of your Provider Dashboard.
Respond "received": "false" in the event of a Secret Key mismatch, or if some other error is encountered. The webhook will be retried multiple times.
Important: Please record the subsuite_user_id & subsuite_subscription_id values in your database/system for later reference or in the event you need to send us a cancellation request.
Shipping address fields will not be populated if "shipping_required" is "false" in your brand profile.
== UPGRADE WEBHOOK ==
URL: <Provider specified>
Method: POST
REQUEST:
{
"event": "change_plan",
"secret_key": "72d5de4b0e08518a8ea03f323c07c4f2",
"first_name": "Jimmy",
"last_name": "Subs",
"email": "
"subsuite_user_id": "1",
"subsuite_subscription_id": "203",
"plan_name": "Platinum",
"plan_term": "1 month",
"plan_price": "29.99",
"primary_plan": "false",
"subsuite_price": "24.99",
"subsuite_fee_percent": "13.00",
"processing_percent": "2.90",
"processing_fee": "0.30",
"net_payment": "20.72",
"previous_plan_name": "Premium",
"previous_plan_price": "19.99",
"change_datetime": "2024-06-07 11:35:52"
}
RESPONSE:
{
"received": "true"
}
== CANCEL WEBHOOK ==
URL: <Provider specified>
Method: POST
REQUEST:
{
"event": "cancel",
"secret_key": "72d5de4b0e08518a8ea03f323c07c4f2",
"first_name": "Jimmy",
"last_name": "Subs",
"email": "
"subsuite_user_id": "1",
"subsuite_subscription_id": "203",
"plan_name": "Platinum",
"plan_term": "1 month",
"plan_price": "29.99",
"primary_plan": "false",
"subsuite_price": "24.99",
"cancel_datetime": "2024-07-10 07:14:21",
"cancel_reason": "No longer using service",
"access_until": "2024-08-01 00:00:00"
}
RESPONSE:
{
"received": "true"
}
== VERIFY WEBHOOK ==
URL: <Provider specified>
Method: POST
REQUEST:
{
"event": "verify",
"secret_key": "72d5de4b0e08518a8ea03f323c07c4f2",
"email": "
}
RESPONSE:
{
"email": "
"plan_name": "Platinum",
"plan_term": "1 month",
"price_paid": "29.99",
"status": "Active"
}
Note:
Status should be "Active" or "Invalid". Plan Term should be "1 month’, "1 year", etc. All fields but Status are optional if the verification attempt is "Invalid".
== AUTHENTICATION TEST API CALL ==
URL: https://api.subsuite.io/v1/auth_test
Method: POST
Auth Username: (Locate in the Integration tab)
Auth Password: (Locate in the Integration tab)
REQUEST: (None)
SUCCESS RESPONSE:
{
"status": "success",
"code": "OK",
"message": "You have successfully authenticated.",
"data": []
}
ERROR RESPONSE:
{
"status": "error",
"code": "AUTH_ERROR",
"message": "Authentication required.",
"data": []
}
== PRIMARY PLAN CANCELLATION API CALL ==
URL: https://api.subsuite.io/v1/cancel_subscription
Method: POST
Auth Username: (Locate in the Integration tab)
Auth Password: (Locate in the Integration tab)
REQUEST:
{
"subsuite_user_id": "1",
"email": "
"subsuite_subscription_id": "203",
"cancel_datetime": "2024-07-10 07:14:21"
}
SUCCESS RESPONSE:
{
"status": "success",
"code": "OK",
"message": "Cancellation processed successfully.",
"data": []
}
ERROR RESPONSE:
{
"status": "error",
"code": "ACTION_FAILED",
"message": "Failed to process cancellation.",
"data": []
}
Notes:
Email is an optional field (a fallback in case subsuite_user_id is not provided - which is preferred). It is not necessary to specify both, but you must provide one.
In cases where the subsuite_subscription_id is known to your system, please provide it (this value is required to cancel subscriptions originating from SubSuite). To notify us that a subscription originating from your system has been cancelled, please pass "0" as the subsuite_subscription_id, along with the subscriber’s email address (the purpose of this is to inform us that the user has cancelled if you are their primary plan).
In the event of an error, your system should consider re-attempting the request one or more times (but not indefinitely). See the table of error codes below, to better determine how to respond to a specific error.
== ERROR CODES ==
OK - No error.
INVALID_ENDPOINT - The API does not have an operation associated with the URL requested.
AUTH_ERROR - Authentication error.
INVALID_USER - The user ID or email address provided does not match any known user.
INVALID_ID - The ID specified for a given resource (i.e. a subscription ID) is invalid.
NOT_FOUND - No resource was found to update in response to this request (the action may have already been performed previously).
ACTION_FAILED - The intended action (i.e. cancellation) could not be completed.
== WEBHOOK RECEIVER SAMPLE CODE (PHP) ==
<?php
define('SUBSUITE_SECRET_KEY', '72d5de4b0e08518a8ea03f323c07c4f2');
$post_data = file_get_contents('php://input');
$input = ($post_data) ? json_decode($post_data, true) : [];
if (!$input) exit;
$secret_key = $input['secret_key'] ?? '';
if ($secret_key != SUBSUITE_SECRET_KEY) { echo json_encode(['received' => 'false']); exit; }
$event = $input['event'] ?? '';
if ($event == 'purchase') {
subsuite_purchase($input);
} elseif ($event == 'change_plan') {
subsuite_change_plan($input);
} elseif ($event == 'cancel') {
subsuite_cancel($input);
} elseif ($event == 'verify') {
subsuite_verify($input);
} else {
echo json_encode(['received' => 'false']); exit;
}
echo json_encode(['received' => 'true']); exit;
function subsuite_purchase($input) {
// Add your code here
}
function subsuite_change_plan($input) {
// Add your code here
}
function subsuite_cancel($input) {
// Add your code here
}
function subsuite_verify($input) {
// Add your code here
}
?>
== API SAMPLE CODE (PHP) ==
<?php
$url = 'https://api.subsuite.io/v1/auth_test';
$post_data = [];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_USERNAME, '8ea0372d5fc4');
curl_setopt($ch, CURLOPT_PASSWORD, '4b0e038572d5fde18a8ea0323c07c4f2');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($post_data));
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$response = ($response) ? json_decode($response, true) : [];
$status = $response['status'] ?? 'error';
?>