SubscriptionBridge: recurring billing and subscription management system - Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
~~NOTOC~~

<note>

The Magento Add-On is no longer supported in-house by Early Impact.  The Add-On is now Open Source and available for your custom development projects.  The source code can be downloaded via the developers section of this wiki. While we no longer maintain the source code we do still offer full support and consultation related to SubscriptionBridge. 

</note>


====== SubscriptionBridge Extension for Magento (BETA) ======
===== Overview =====

{{ :cartintegration:magento-logo.png|Magento is integrated with SubscriptionBridge}}

The **[[http://www.magentocommerce.com/magento-connect/Early+Impact%2C+Inc./extension/4755/earlyimpact_subscriptionbridge|SubscriptionBridge Extension for Magento]]** allows you to sell subscriptions directly from your Magento-powered online store. 

During checkout, Magento will detect that the product/service being purchased is a subscription and will pass all necessary information to SubscriptionBridge, which will crate a recurring billing profile for the customer.

Features include:

  * Quick install via Magento Connect Manager
  * Easily activate a **live connection** between your Magento-powered store and your SubscriptionBridge Merchant account
  * **Map items** in your Magento store catalog to subscription packages that have been setup in SubscriptionBridge
  * Automatically display subscription terms when showing product details and during checkout, via the **built-in [[developer_guide:developer_guide:terms_widget|subscription terms widget]]**
  * Define Terms & Conditions at the product level so that the correct terms are shown during checkout, before the order for the subscription can be placed.
  * Automatically create a subscription in the recurring payment system associated with your SubscriptionBridge store (e.g. Authorize.Net, PayPal Website Payments Pro).
  * Manage subscription billing and recurring payments through SubscriptionBridge 

The extension is now in **BETA** simply because it needs to be used in "real life" environments for a bit longer to ensure that everything is working as expected. We will remove the BETA label as soon as possible.

===== Screen shots =====

==== Product details page ====

The product details page in the Magento storefront catalog automatically loads subscription terms information from SubscriptionBridge, without that information needing to be stored in the Magento database. This makes for a light, quick integration between the two systems.

{{:cartintegration:magento:sbmagento_st1.png|Magento product details page}}

==== Shopping cart page ====

Subscription terms are also shown on the shopping cart page when the product (subscription) is added to the shopping cart.

{{:cartintegration:magento:sbmagento_st2.png|Magento shopping cart page}}

==== Magento store administration ====

In the Magento store administration area you can quickly activate the integration with SubscriptionBridge, configure optional settings, and create associations between items in the catalog and subscription packages that have been setup in SubscriptionBridge.

{{:cartintegration:magento:sbmagento_cp1.png|}}
{{:cartintegration:magento:sbmagento_st2.png|}}
{{:cartintegration:magento:sbmagento_cp3.png|}}

Once you have created a link between a product and a SubscriptionBridge package, there are a number of settings that you can define at the product level.

{{:cartintegration:magento:sbmagento_cp4.png|}}

===== Installing the SubscriptionBridge Extension =====

The [[http://www.magentocommerce.com/magento-connect/Early+Impact%2C+Inc./extension/4755/earlyimpact_subscriptionbridge|SubscriptionBridge Extension for Magento]] is available on the Magento Connect Web site. [[http://www.magentocommerce.com/magento-connect/Early+Impact%2C+Inc./extension/4755/earlyimpact_subscriptionbridge|Click here]] to visit the extension's page on Magento Connect.

To install the SubscriptionBridge Extension for Magento:

  * In your Magento administration area, click on "//System > Magento Connect > Magento Connect Manager//"
  * Load the SubscriptionBridge Extension page in the Magento Connect Web site
  * Request the extension key for the extension by clicking on the corresponding button
  * Enter the extension key in the Magento Connect Manager and click on "Install"
  * Click on "Refresh" and the extension should now be listed as shown below

{{:cartintegration:magento:sbmagento_cp5.png|Magento Connect Manager}}

  * Click on "Return to Admin" to return to your Magento administration area

===== Activating the SubscriptionBridge Extension =====

Before you can associate products in your Magento catalog with subscription package in SubscriptionBridge, you must connect your Magento store with one of your SubscriptionBridge-powered stores.

==== Obtaining API credentials from SubscriptionBridge ====

  * Open a new browser window and log into the [[https://www.subscriptionbridge.com/MerchantCenter/login.asp|SubscriptionBridge Merchant Center]]
  * Locate the SubscriptionBridge store that you want to connect to your Magento-powered store
  * Click on **API Credentials**
  * Agree to the Terms & Conditions and then API credentials will be shown to you

==== Entering the SubscriptionBridge credentials in Magento ====

  * Return to Magento and select "System > Configuration" (if the configuration menu is not shown, log out and log back in)
  * Select //SubscriptionBridge > API > Activate SubscriptionBridge Integration - Enter API Credentials//
  * Enter the API credentials that you obtained from SubscriptionBridge (your other browser window should still be open)
    * API User Name
    * API Password
    * API Key
  * The API URL is pre-populated with the default value (<nowiki>https://www.subscriptionbridge.com/Subscriptions/Service2.svc/</nowiki>) and should not be altered.
  * Click on "Save Config" to save the configuration. You should receive a confirmation message as shown below. Your Magento store is now successfully communicating with SubscriptionBridge.

{{:cartintegration:magento:sbmagento_cp6.png|API credentials added successfully}}

===== SubscriptionBridge settings in Magento =====

Under "//System > Configuration//", select "//SubscriptionBridge > Configurations//".

==== SubscriptionBridge Center Links ====

There are two fields that contain pre-populated URLs to the SubscriptionBridge Customer and Merchant Center. You should not need to change these links.

==== Messages ====

You can edit default messages shown by Magento in the storefront. Specifically:

  * **Message - Cart not valid** \\ This message pertains to a current limitation: customers can only purchase a subscription product OR a regular product, but not both at the same time. This limitation might be removed in the future. The default message is: "//The shopping cart is not valid. You can add only one subscription product or general products.//"
  * **Message - Terms and Condition Title** \\ You can show "Terms & Conditions" during checkout. This is the title of that section. Default message is: "//Accept SubscriptionBridge terms and condition.//"
  * **Message - Add subscription not allow** \\ This message pertains to a current limitation: customers can only purchase a subscription product OR a regular product, but not both at the same time. This limitation might be removed in the future. This message is shown when there is already a "regular" product in the cart. The default message is: "//The shopping cart is currently in use. At this time, you can not add a subscription product to the cart. If you would like to purchase subscription items, please first complete the current order and then place a new one//"
  * **Message - No additional products** \\ This message pertains to a current limitation: customers can only purchase a subscription product OR a regular product, but not both at the same time. This limitation might be removed in the future. This message is shown when there is already a "subscription" product/service in the cart. The default message is: "//The shopping cart is currently in use for purchasing a subscription. At this time, you can not add additional products to the cart. If you would like to purchase additional items, please complete the current order and then place a new one. Alternatively, you can empty the shopping cart and add different products.//"
  * **Message - Only one subscription** \\ This message pertains to a current limitation: customers can only purchase one subscription at a time. This limitation might be removed in the future. This message is shown when there is already a "subscription" product/service in the cart. The default message is:"//The shopping cart is currently in use for purchasing a subscription. Only one subscription product can be added to the shopping cart.//"

===== Associating Products and Subscription Packages =====

To turn an item in your Magento store catalog into a subscription-based product or service, you need to "link it" to a package that you have __previously__ setup in the SubscriptionBridge Merchant Center.

==== Create a Package in SubscriptionBridge ====

Make sure that you have already created at least one package in SubscriptionBridge, and that the package is ready to be purchased. You can double-check by logging into the Merchant Center and clicking on "//Package Links//" for the store that you are working with. Can those packages be purchased in the built-in SubscriptionBridge shopping cart? If so, then they are also available for "linking" to an item in your Magento catalog. If not, then you probably need to finish configuring them in SubscriptionBridge (e.g. make sure that you have specified a package description, price, etc.).

==== Linking Packages and Products ====

  * Log into your Magento admin area
  * Click on "//SubscriptionBridge > Create Package Link//".
  * Search for the item that you want to turn into a subscription and click "//Create//"
  * The **Packages** drop-down will load a list of the packages that have been setup in your SubscriptionBridge Merchant Center and that are ready for sale (not all packages will be listed).
  * Select the subscription package that you want to associate with this product
  * Then enter settings that are consistent with the package settings that you have created in SubscrptionBridge (e.g. trial price)
  * If you want customers to have to agree to Terms & Conditions for the subscription during checkout, set "//Require that customers agree to the following Agreement//" to "//Yes//" and enter the terms in the corresponding text area.
  * Click "//Save//" to save the product-package link

{{:cartintegration:magento:sbmagento_cp7.png|Subscription product settings}}

==== Subscription Price ====

Note that the regular price for this subscription-based product or service is not shown in this window. Only the trial price is (if any). That's because the "regular" price is the price that you entered when you created it. Edit it now if you need to. It should be consistent with the regular subscription price that you have specified for this subscription package in SubscriptionBridge.

==== Listing existing subscription Packages ====

You can now view a list of the items that you have linked to subscription packages by selecting //SubscriptionBridge > View/Modify Subscription Packages//. You can edit existing product-package associations by clicking on "//Edit//".
===== Subscription Terms Widget =====

The Subscription Terms Widget allows you to show terms for the subscription in the Magento storefront, dynamically retrieving them from SubscriptionBridge. You can style the widget using simple CSS.

To show the widget, you need to edit a few files in the Magento storefront. This is because "design" pages cannot be altered through an extension (so we can't take care of this automatically for you, unfortunately). In each of the following cases, make sure to create a backup copy of the original file before editing it.

==== Edit "product\view.phtml" ====

  * Download the file "\app\design\frontend\default\default\template\catalog\product\view.phtml" via FTP
  * Open it in Notepad or your favorite HTML editor
  * Locate the following code around line 68 <code><?php echo $this->getTierPriceHtml() ?></code>
  * Add the following code right after that line: <code><?php
// start code to add
if($_product->getSbLinkid()) echo $this->helper('subscriptionbridge')->getSbApiWidget($_product->getSbLinkid()); 
// end code to add
?></code>
  * Save the file and upload it back to the Web server.

==== Edit "cart\item\default.phtml" ====

  * Download the file "\app\design\frontend\default\default\template\checkout\cart\item\default.phtml" via FTP
  * Open it in Notepad or your favorite HTML editor
  * Locate the following code around line 52 <code><!-- / --></code>
  * Add the following code right after that line: <code><?php
// start code to add
if($_item->getSbLinkid()) echo $this->helper('subscriptionbridge')->getSbApiWidget($_item->getSbLinkid());
// end code to add
?></code>
  * Save the file and upload it back to the Web server.

==== Edit "onepage\review\item.phtml" ====

  * Download the file "\app\design\frontend\default\default\template\checkout\onepage\review\item.phtml" via FTP
  * Open it in Notepad or your favorite HTML editor
  * Locate the following code around line 49 <code><!-- / --></code>
  * Add the following code right after that line: <code><?php
// start code to add
if($_item->getSbLinkid()) echo $this->helper('subscriptionbridge')->getSbApiWidget($_item->getSbLinkid());	 
// end code to add
?></code>
  * Save the file and upload it back to the Web server.

==== Edit "renderer\default.phtml" ====

  * Download the file "\app\design\frontend\default\default\template\sales\order\items\renderer\default.phtml" via FTP
  * Open it in Notepad or your favorite HTML editor
  * Locate the following code around line 29 <code><td><h5 class="title"><?php echo $this->htmlEscape($_item->getName()) ?></h5></code>
  * Add the following code right after that line: <code><?php 
    // start code to add
    $_sbOrder = $this->getOrder();
    $_sbPayment = $_sbOrder->getPayment();
    if($_sbPayment->getMethod() == 'subscriptionbridge') :
    	 echo $this->helper('subscriptionbridge')->getSbCustomerCenterLinkDeatils($_sbPayment->getCcTransId(),$_sbOrder->getCustomerEmail());
    endif;
    // end code to add
?></code>
  * Save the file and upload it back to the Web server.

===== Other notes =====
==== Product Type ====

If you are selling a subscription-based service (i.e. non-shipping, typically non-taxable), make sure to setup the product in Magento as a //Virtual// product. Otherwise Magento will consider it a shipping product. You can't change the product type after creating a product.
==== Current Limitations ====

  * One subscription \\ You can only purchase one subscription product/service at a time. The message that informs customers of this scenario can be edited in the Magento administration area.
  * Either a subscription or regular products \\ You cannot put in the shopping cart, at the same time, a subscription product with one or more regular products. Subscriptions must be purchased separately. The message that informs customers of this scenario can be edited in the Magento administration area.
  * PayPal Express Checkout \\ PayPal Express Checkout is not supported at this time.