This document includes the specifications that were used in the Magento Extension for SubscriptionBridge.

• The Magento store manager will have access to a page where he/she can enter their SubscriptionBridge API Credentials. The page provide a link to the instructions on how to obtain their API credentials. This will provide a way for the store to be authorized to communicate with SubscriptionBridge.
• The activation process is accomplished using the ActivationRequest call in the SubscriptionBridge API.
• Once the ActivationRequest has been executed successfully, the system will capture the response and parse it, looking for the “Ack” element. If “Ack” has a value of “Success”, then the activation was a success. If the activation was not a success then check for a “Error” element in the XML. If the error element exists you can parse out the “ErrorCode” and “ErrorDetail” so you can display a message to the user.

Here is an example of the “SubscriptionBridge Activation” page in the ProductCart integration:

The Magento store administration area will provide a way for the merchant to associate items that exist in the store catalog with the corresponding package in the merchant's SubscriptionBridge store. This will be accomplished as follows:

1. Search the store catalog. Products already linked to a subscription package should not appear in the search results.
2. Select a product
3. Select a subscription package to link it to.
   This can be done by showing a drop-down menu populated by the GetPackagesRequest. The drop-down is populated with all packages that exist in the merchant's SubscriptionBridge store, and that have not already been associated with other products in the store catalog. It is important to note that the option value in the drop down must be the package “LinkID” that is returned by GetPackagesRequest.
4. Make sure that the relationship is unique: the same package should only be associated with one product in the store catalog
5. Prompt the merchant to specify whether:
   1. There is a trial
   2. What the trial price is
      This is done so that when customers search or browse the store, the subscription price is shown (e.g. $49.95), but when they checkout, the actual price paid today is shown (e.g. $0). The Terms Widget provides the details on exactly what the terms are (e.g. FREE for the first month. $49.95 per month after the Trial).
6. Save the product - package association

Here is an example of how the product-package link screen looks in the ProductCart integration:

The Magento store administration area will provide a way for the merchant to review and edit the existing product-package associations.

Our recommendations for shopping cart integration with SubscriptionBridge include a way for the merchant to specify Terms & Conditions at the product level that the customer should agree to when checking out. However, this feature will not be part of the first version of the Magento Extension for SubscriptionBridge.

The Add to Cart mechanism will be modified so that:

1. only 1 subscription product can be added to the shopping cart
2. non-subscription products cannot be added if a subscription product exists already in the shopping cart

This limitation exists to avoid complex scenarios, such as:

• separating the subscription's price from the other items when a discount is used
• calculating which portion of the total tax should be added to the subscription (if taxable)
• calculating which portion of the total shipping charges (if the subscription contains shippable products)

Also during the Add to Cart process you will need to consider the data you will need after payment is rendered. If you use an array or database to store the cart contents, then this is a good time to get the data you need for checkout. You will be creating a SubscriptionRequest that will generate the recurring billing in your SubscriptionBridge Merchant Center. Please review the SubscriptionRequest and make sure you are saving all the required information.

For instance, you may want to save the following:

• The LinkID of the product/package in the cart
• A flag indicating if there is a trial
• The trial price, if applicable

SubscriptionBridge includes a simple widget that allows you to display subscription payment terms without having to store that information in the store database. You can place the widget in the HTML source code and pass into the widget the “LinkID” of the package. The widget will communicate with SubscriptionBridge to display the most up-to-date pricing information. Learn about the Terms Widget.

The Magento storefront will display the subscription payment terms, via the Terms Widget:

1. On the product details page
   This ensures that the customer can visually, immediately recognize the product as a subscription product, and see what the subscription terms are.
2. On the shopping cart page
   This ensures that the customer knows that a subscription product has been added to the shopping cart.
3. On the payment page
   This ensures that the customer is reminded of exactly what the subscription terms are at the time the order is finalized.

Here is an example of the Terms Widget shown on the shopping cart page on a ProductCart-powered store.

The checkout flow will be the standard Magento checkout flow until the payment page. The system will detect that the customer is checking out with a subscription and redirect to a special payment page that will communicate with SubscriptionBridge to setup the new subscription by executing a SubscriptionRequest call.

The Magento storefront will gather all the information needed for the SubscriptionRequest call, which includes:

• trial total
• total
• trial tax
• tax
• trial shipping
• shipping

See an example of what this information might look like.

Incompatible payment options will be disabled in the storefront when a subscription is being purchased. The customer will be taken automatically to the only payment option supported, which is the payment form that you have created to pass information to the SubscriptionBridge API via the SubscriptionRequest call.

The payment screen is the final opportunity to be clear about the pricing terms for the subscription that the customer is signing up for. Therefore, it will display the subscription terms via the Terms Widget.

After the payment form is submitted, the Magento storefront will contact SubscriptionBridge to create the new subscription through the SubscriptionRequest call.

The system will validate the SubscriptionResponse a confirmation is shown. If there are any errors you should redirect back to the payment page and display the error message to the customer.

Once you get a “Ack” (Acknowledgment) of “Success”, parse the “GUID” from the response and save it to your database. The GUID is the only information you will need to save from the response. It uniquely identifies a specific subscription. With the GUID you can access all API Methods. We recommend that you save this information in the table where order information is saved, or in a separate table that references the order ID.

The merchant will be able to see a report of orders that contained a subscription. This new page in the Magento store administration area will include:

• Order ID
• Order Date
• Customer Name
• Product Name
• Link to the SubscriptionBridge Merchant Center so that the merchant may manage the subscription. The syntax for the link should be as follows, where <GUID> is the identifier for the subscription associated with the order:

https://www.subscriptionbridge.com/MerchantCenter/SubscriptionslistDetails.asp?SubscriptionUID=<GUID>

Due to restrictions in the ability to edit the standard order details page, the standard order details page in the Magento store administration area will not contain details on whether the order contains a subscription.

The customer account management area will include a way for the customer to “Manage by subscriptions”

• Detect whether the customer has placed an order for a subscription
• Link to a page that lists those orders
• Provide a link to the SubscriptionBridge Customer Center. The syntax for the link to the SubscriptionBridge Customer Center should be as follows, where <GUID> is the identifier for the subscription associated with the order, and <EMAIL> is the customer's e-mail address (which was passed to SubsriptionBridge via the SubscriptionRequest call:

https://www.subscriptionbridge.com/CustomerCenter/AutoLogin.asp?ID=<GUID>&Email=<EMAIL>&mode=details