Differences

This shows you the differences between two versions of the page.

--- developer_guide:developer_guide:recommended [2010/03/02 03:45] – earlyimpact
+++ developer_guide:developer_guide:recommended [2010/05/13 15:29] (current) – earlyimpact
@@ Line 3: / Line 3: @@
 ===== Overview =====
-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 [[developer_guide:developer_guide|SubscriptionBridge API]] into your shopping cart system.  For example:
+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 [[developer_guide:developer_guide|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
@@ Line 10: / Line 10: @@
   * etc.
-This article will attempt to answer those tough questions so you can focus on your code.
+This article will attempt to answer those questions so you can focus on your code.
+We recommend that you review the [[:developer_guide:developer_guide|Developer's Guide]] to familiarize with the SubscriptionBridge API. We will refer to the SubscriptionBridge API throughout this document.
 ===== Control Panel =====
-The control panel area of your shopping cart should consist of the following pages:
+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.
 ==== Activation ====
-The very first thing that needs to happen is for the shopping cart to be activated to use the SubscriptionBridge API. If you have not reviewed the [[:developer_guide:developer_guide|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 [[:developer_guide:call_reference:ActivationRequest|ActivationRequest]].
+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 [[:developer_guide:call_reference:ActivationRequest|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 [[:cartintegration:productcart:pc_api_credentials|instructions on how to obtain their API credentials]].
@@ Line 24: / Line 26: @@
 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.
+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 [[cartintegration:productcart:productcart|ProductCart]] integration:
+{{:developer_guide:developer_guide:sb_integration_activation.png|SubscriptionBridge activation in ProductCart}}
+----
-==== Linking Packages ====
+==== Linking Products and Packages ====
-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 two different ways.
+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.
   - **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:
@@ Line 40: / Line 50: @@
     * A checkbox to flag the product as having a trial
     * A new field for the trial price (if applicable)
+For example, in the [[cartintegration:productcart|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.
+{{:developer_guide:developer_guide:sb_integration_packagelink.png|Creating and editing a package link}}
+----
 Regardless of which method you choose the process is the same.
@@ Line 47: / Line 63: @@
   * They will also add a //Trial Price// is applicable. The price of the product itself is not needed as part of this interface because it is already part of the add/modify product page.
-Save all of the user selections to the store database so they can be queried on the storefront later on.
+Technical recommendations:
+  * Save the relationship between products and packages in a separate database table
+  * Make sure that the relationship is unique: the same package should only be associated with one product in the store catalog
+  * Additional, package-level options can be useful and should be stored in the same table. They include:
+    * Trial price, as mentioned above
+    * Terms & Conditions: you may want to show the customer terms and conditions that the customer must agree to before signing up for the product/service that they are about to subscribe to. The terms and conditions could be shown during checkout (e.g. on the payment page, before payment information can be submitted).
+  * All of the above needs to be saved in the store database so that it can be queried in the storefront.
 ==== View / Modify Linked Packages ====
 Provide a page where the user can find and edit their //product-package associations//.
 ==== Settings ====
-We recommend that you also provide a basic //Settings// form. This form should allow the user to control some global preferences.
+We recommend that you also provide a basic //Settings// form. This form should allow the user to control some global preferences, such as:
-Here are just a few ideas.
-  * Text field to type in "Terms and Conditions", which could be enforced on the storefront.
+  * Text field to type in "Terms and Conditions", which could be enforced on the storefront. Terms & Conditions could also be specified at the product level, as mentioned above, overwriting the store setting.
   * 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. [[:merchant_guide:payment_gateways|Click here for a list of compatible payment gateways]]. Incompatible payment options should be disabled in the storefront when a subscription is being purchased.
+  * Ability to control the additional text strings used in the storefront for the sale of subscriptions (if you feel that any are needed). For example, the merchant might want to display some additional information on the payment screen (e.g. "//We typically process your subscription request within 24 hours.//")
 ===== Storefront =====
@@ Line 69: / Line 89: @@
 === Recommendation: one subscription, no other products ===
-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:
+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
@@ Line 75: / Line 95: @@
   * 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.
+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).
 === Preparing the data you will need ===
@@ Line 86: / Line 106: @@
   * A flag indicating if there is a trial
   * The trial price, if applicable
 ==== Product Details & Payment Terms Widget ====
@@ Line 99: / Line 118: @@
 Learn about the [[:developer_guide:developer_guide:terms_widget|Terms Widget]].
-==== View Cart ====
+==== Where to display the Subscription 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.
+We recommend using the Terms Widget:
-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.
+  - One 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.
+  - On the **shopping cart page** \\ This ensures that the customer knows that a subscription product has been added to the shopping cart.
+  - 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 [[cartintegration:productcart:productcart|ProductCart-powered]] store.
 {{:developer_guide:developer_guide:sb_cart_widget.png|SubscriptionBridge's subscription terms widget}}
+==== Terms & Conditions ====
-==== Agree to Terms ====
+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.
-Prior to the payment screen you can display the "Terms and Conditions" the user saved in the store's administration area.  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.
+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.
 ==== Saving the Order ====
@@ Line 137: / Line 159: @@
   * shipping: $12.50
+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:
+  * trial total: $0
+  * total: $19.95
+  * trial tax: 0
+  * tax: 0
+  * trial shipping: 0
+  * shipping: 0
 ==== Payment Screen ====
+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 [[:developer_guide:call_reference:SubscriptionRequest|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 [[:developer_guide:developer_guide:terms_widget|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 can add a custom line to the pricing terms that says "Plus Tax and Shipping" or "Includes Tax and Shipping".
+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.
 <code>50% the first month
@@ Line 147: / Line 179: @@
 Plus shipping, tax, and handling fee</code>
-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.
+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.
+==== Subscription creation request and confirmation ====
-==== Post Payment and Confirmation ====
+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 [[:developer_guide:call_reference:SubscriptionRequest|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.
-After the payment form is submitted, you will need to generate the [[:developer_guide:call_reference:SubscriptionRequest|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 [[:developer_guide:call_reference:subscriptionrequest#subscriptionresponse|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.
+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.
+===== After the purchase =====
+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).
+==== Administration area ====
+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:
+<code>https://www.subscriptionbridge.com/MerchantCenter/SubscriptionslistDetails.asp?GUID=<GUID></code>
+==== Customer account area ====
+Similarly to the administration area:
+  * Detect whether an order is for a subscription product or service
+  * Add information to the order details page indicating that this is the case
+  * Provide a link to the SubscriptionBridge Customer Center (unless you are not using the Customer Center, but rather performing all subscription management tasks via the API itself). For example, a customer might need to view recent subscription payments, update their billing information, add features to a subscription, or cancel the subscription.
+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):
+<code>https://www.subscriptionbridge.com/CustomerCenter/AutoLogin.asp?ID=<GUID>&Email=<EMAIL>&mode=<MODE></code>
+== Landing Pages <MODE> ==
+  * **Detail** \\   Replace <MODE> with "details" to send the customer to the subscription details page.
+  * **Transaction History** \\  Replace <MODE> with "history" to send the customer to the transaction page.
+  * **Edit Billing** \\  Replace <MODE> with "billing" to send the customer to the billing details page.
+  * **Edit Shipping** \\  Replace <MODE> with "shipping" to send the customer to the shipping details page.
+  * **Cancel Subscription** \\   Replace <MODE> with "cancel" to send the customer to the subscription cancellation page.