Table of Contents
The following sections are for developers that want to create a shopping cart integration with SubscriptionBridge. As a developer you will have many decisions to make about how to integrate the SubscriptionBridge API into your shopping cart system. For example:
This article will attempt to answer those questions so you can focus on your code.
We recommend that you review the Developer's Guide to familiarize with the SubscriptionBridge API. We will refer to the SubscriptionBridge API throughout this document.
For the shopping cart to successfully integrate with SubscriptionBridge, the administration area (e.g. the Control Panel) of your shopping cart software should include - at least - the following features.
First, you will need a way for the merchant to authorize their store to communicate with SubscriptionBridge. In other words, the shopping cart must be activated to use the SubscriptionBridge API. This is accomplished through the ActivationRequest.
So the shopping cart's administration area will first of all need to include a page where the merchant can enter their SubscriptionBridge API Credentials. The page should provide a link to the instructions on how to obtain their API credentials.
When the form is submitted, it will invoke an API call to SubscriptionBridge. The documentation contains sample code for this call. Once you have successfully made the ActivationRequest, 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:
Once the store has been activated, you will need to provide a way for the merchant to associate items that exist in the shopping cart's catalog with the corresponding package in the merchant's SubscriptionBridge store. This can be accomplished in many different ways. Here are two suggestions.
For example, in the ProductCart integration the second method is used. A search page allows the store manager to locate a product in the store catalog. Then, a screen such as the one shown below allows the store manager to associate that product with a subscription package. The subscription packages available for selection are listed in the drop-down shown on the page, and have been retrieved via the API.
Regardless of which method you choose the process is the same.
Provide a page where the user can find and edit their product-package associations.
We recommend that you also provide a basic Settings form. This form should allow the user to control some global preferences, such as:
The Add to Cart mechanism in your cart should be modified so that only 1 subscription product can exist in the cart at any time. If you choose to allow multiple items in the cart along with a subscription product you must solve some complex scenarios, such as:
These and other scenarios can be quite challenging to resolve through the shopping cart's storefront code. As such, we recommend that you do not allow multiple items in the cart when a subscription product is involved. This will rarely be an issue for the vast majority of stores as subscription products & services are typically not purchased together with non-subscription products and services (of course, there are exceptions to this rule, but this is true in most cases).
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 product details pages will need to be modified to display subscription terms to the customers. For example, you may want to display something like…
FREE for the first month $35.00 per month after the Trial Plus shipping, tax, and handling fee
You may wonder how you will display such information if that data is saved at SubscriptionBridge.com. Luckily, there is a simple widget to achieve this goal. You simply place the widget in your HTML and pass into the widget the “LinkID” of the package (which you saved in the control panel). The widget will communicate with SubscriptionBridge to display the most up-to-date pricing information.
Learn about the Terms Widget.
We recommend using the Terms Widget:
Here is an example of the Terms Widget shown on the shopping cart page on a ProductCart-powered store.
Prior to the customer completing the order you should display the “Terms and Conditions” that were saved in the store's administration area. You should implement some mechanism to prevent the customer from completing the order without agreeing to the terms of the subscription that they are signing up for.
As mentioned above, since different subscription products/services can have different Terms and Conditions, this is a setting that you will likely want to allow the merchant to configure at the product level.
Every cart saves the order at a different location in the checkout flow. Regardless of when this is done with your shopping cart, at this point you should have calculated the trial tax, recurring tax, trial shipping and shipping totals. This is a good time to save this data because you will need it for the SubscriptionRequest later on. Please review the SubscriptionRequest and make sure you are saving all the required information at this point.
For instance, you may want to save the following with the order details:
If you have all of this information saved with the order, then you can easily query it after payment is submitted and generate the XML for your SubscriptionRequest.
Here is a practical example to visualize why you need all of this information: assume you are selling a Wine Club membership: members received a monthly wine shipment at a price of $35 per month, but for the first month - in order to attract new members -there is a 50% discount and shipping is free. Let's assume taxes are 10% and shipping charges are non-taxable. The subscription details could be:
The above assumes that the subscription is for a product that requires taxes and shipping charges calculated during checkout (e.g. monthly wine shipment; monthly vitamin shipment; etc.). If the customer is instead purchasing a service, things are much easier as you will typically have no shipping and taxes. For example, assume there is a service that costs $19.95 a month, with a free trial. In this scenario you would have:
Incompatible payment options should be disabled in the storefront when a subscription is being purchased. The customer must 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 (see below for more information).
The payment screen is your final opportunity to be clear about the pricing terms for the subscription that the customer is signing up for. We recommend that you again display the Terms Widget. The widget will display the most accurate and updated pricing information for the subscription (Package) that the customer is signing up for.
Now, if the cart is adding tax and shipping then your total will obviously be different than the price displayed in the terms. That is where the 3rd line displayed by the widget can help (in the example below, ”Plus shipping, tax, and handling fee”). You don't have to worry about this information: it is entered by the merchant in the SubscriptionBridge Merchant Center and displayed automatically by the Terms Widget only when available.
50% the first month $35.00 per month after the Trial Plus shipping, tax, and handling fee
If you require additional legal terms or specifications to be displayed we recommend that you add additional form fields to the Settings mentioned above. This would allow the merchant to display additional details that would be displayed at on the payment screen.
After the payment form is submitted, you will need to contact SubscriptionBridge to create the new subscription profile that the customer just requested. This is done through the SubscriptionRequest call using all of the information you have previously gathered and saved during the checkout process. Please review the developers guide and sample code for more specific help completing this action.
The important thing to remember at this point is that you validate the SubscriptionResponse before you display the confirmation. 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.
We recommend that you customize the additional areas of the shopping cart so that both the merchant and the customer can recognize that an order was placed for a subscription product and link to SubscriptionBridge (if needed).
By checking the products that an order contains, you can easily determine whether it includes a subscription product. You can also do so by checking to see if there is a subscription GUID associated with the order (depending on how that information has been saved - see above).
If the order is for a subscription product or service, you should make this clear on the order details page, and 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:
Similarly to the administration area:
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, <MODE> is the landing page (list of landing pages below), and <EMAIL> is the customer's e-mail address (which was passed to SubsriptionBridge via the SubscriptionRequest call):