The following sections are for developers that want to create a shopping cart integration with SubscriptionBridge.com. As a developer you will have many decisions to make about how to integrate the SubscriptionBridge API into your shopping cart system. For example:

• you will have to determine how to best allow the store manager to “flag” certain products as subscriptions
• you will need to decide how to handle tax and shipping if there is a trial period
• you will need to decide how to display subscription information on your product details page
• etc.

This article will attempt to answer those tough questions so you can focus on your code.

The control panel area of your shopping cart should consist of the following pages:

The very first thing that needs to happen is for the shopping cart to be activated to use the API. If you have not reviewed the Developer's Guide, now would be a good time to do so. If you are already familiar with the API you will know the first API call is the ActivationRequest.

So the shopping cart will need a page in the control panel consisting of a form. The form will contain a place for the merchant to type their SubscriptionBridge API Credentials. You should also 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. Go back to the developer guide and sample code sections for help making the API call. Once you have successfully made the ActivationRequest you will capture the response. You will parse the response for the “Ack” element. If the “Ack” is “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.

After the store is 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 two different ways.

1. Modify Product
   Just about every shopping cart has a page where you can modify a product. You can simply expand that page to include the following items:
   • A checkbox to flag the product as a subscription.
   • A drop-down menu populated by the GetPackagesRequest. This will allow the user to select the corresponding package.
   • A checkbox to flag the product as having a trial
   • A new field for the trial price (if applicable)
2. Search and Select
   Some shopping carts have very complex product pages. You may not want to edit the product pages as it would make it difficult to install future shopping cart updates. In such a case we recommend that you create a page where you can select a desired product and flag it as a subscription. This page will be independent of the core shopping cart files so you can easily install future cart updates without overwriting your custom code. The selection page should have the following items:
   • A checkbox to flag the product as a subscription.
   • A drop-down menu populated by the GetPackagesRequest. This will allow the user to select the corresponding package.
   • A checkbox to flag the product as having a trial
   • A new field for the trial price (if applicable)

Regardless of which method you choose the process is the same.

• The user will flag the product as being a subscription.
• Next, they will select the matching package from the drop down, which was populated with all packages that exist in the merchant's SubscriptionBridge store. It is important to note that the option value in the drop down should be the package “LinkID” that is returned by GetPackagesRequest.
• They will also add a Trial Price is applicable. The price is not needed because it is already saved with the product.

You will save all of the user selections to the store database so they can be queried on the storefront later on.

Provide a page where the user can find and edit their linked subscription products.

We recommend that you also provide a basic Settings form. This form should allow the user to control some global actions, or display options. Here are just a few ideas.

• Text field to type in “Terms and Conditions”, which could be enforced on the storefront.
• Ability to turn all subscription products “On” and “Off”. (e.g. for sale and not for sale)
• Ability to select the payment options that are compatible with subscriptions. Click here for a list of compatible payment gateways. Incompatible payment options should be disabled in the storefront when a subscription is being purchased.

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:

• 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)

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.

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

The product details pages will need to be modified to display the pricing terms to the customers. For example, you may want to display something like…

FREE for the first month
$35.00 every 1 month after Trial
Plus shipping, tax, and handling

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.

Each view of the cart should be modified to accommodate a trial price. For instance, if their is a free trial the cart total would be zero. Since each shopping cart is different we cannot tell you exactly how to accomplish this task. You may want to set the line item itself to 0. On the other hand you may want to keep the line item price so you can use it later in your subscription request. In such a case, we recommend that you add an additional line item that displays the adjustment.

In either scenario you must update the subtotal and total to reflect the trial pricing. It must be clear to the customer what they are paying now. Here is a screen shot from a shopping cart that has been integrated with SubscriptionBridge.

- Add screen shot here

Prior to the payment screen you can display the “Terms and Conditions” the user saved in the control panel. You should implement some mechanism to prevent the customer from making payment without agreeing to the terms of the subscription that they are signing up for.

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:

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

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.

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 custom line of the widget comes into play. You can add a custom line to the pricing terms that says “Plus Tax and Shipping” or “Includes Tax and Shipping”. If you require additional legal terms or specifications to be displayed we recommend that you add additional form fields to the control panel setting page. That would allow the user to type additional details that would be displayed at on the payment screen.

After the payment form is submitted, you will generate the SubscriptionRequest 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” you will parse the “GUID” from the response and save it to your database. The GUID is the only information you will need from the response. With the GUID you can access all API Methods for subscriptions.

Your system should not display the GUID to the customer, nor need it send subscription specific emails. SubscriptionBridge will send a confirmation e-mail to the customer.