developer_guide:developer_guide:recommended
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
developer_guide:developer_guide:recommended [2010/01/05 16:48] – matt | developer_guide:developer_guide:recommended [2010/05/13 15:29] (current) – earlyimpact | ||
---|---|---|---|
Line 3: | Line 3: | ||
===== Overview ===== | ===== 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 APIs into your shopping cart system. | + | The following sections are for developers that want to create a shopping cart integration with SubscriptionBridge. |
+ | * you will have to determine how to best allow the store manager to " | ||
+ | * 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 questions so you can focus on your code. | ||
+ | |||
+ | We recommend that you review the [[: | ||
===== Control Panel ===== | ===== Control Panel ===== | ||
- | The control panel should consist | + | For the shopping cart to successfully integrate with SubscriptionBridge, |
==== Activation ==== | ==== Activation ==== | ||
- | The very first thing that needs to happen is the Shopping Cart must be activated to use the API. If you have not read over the Developer' | + | First, you will need a way for the merchant |
- | So you need a page in the control panel consisting of a form. The form will contain a place to type the API Credentials. | + | So the shopping cart's administration area will first of all need to include |
- | When the form is submit | + | When the form is submitted, |
- | If the activation was not a success then check for a " | + | If the activation was not a success then check for a " |
- | ==== Linking Packages ==== | + | ---- |
- | After the store is activated its products must be linked to the corresponding package on SubscriptionBridge.com. We will provide two ways this can be accomplished. | + | Here is an example of the "SubscriptionBridge |
- | | + | {{: |
+ | |||
+ | ---- | ||
+ | |||
+ | ==== 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' | ||
+ | |||
+ | | ||
* A checkbox to flag the product as a subscription. | * A checkbox to flag the product as a subscription. | ||
- | * A drop down menu populated by the [[: | + | * A drop-down menu populated by the [[: |
* A checkbox to flag the product as having a trial | * A checkbox to flag the product as having a trial | ||
* A new field for the trial price (if applicable) | * A new field for the trial price (if applicable) | ||
- | - **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. | + | - **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. |
* A checkbox to flag the product as a subscription. | * A checkbox to flag the product as a subscription. | ||
- | * A drop down menu populated by the [[: | + | * A drop-down menu populated by the [[: |
* A checkbox to flag the product as having a trial | * A checkbox to flag the product as having a trial | ||
* A new field for the trial price (if applicable) | * A new field for the trial price (if applicable) | ||
- | Regardless of which method | + | For example, in the [[cartintegration: |
+ | {{: | ||
- | ==== View / Modify Linked Packages ==== | + | ---- |
- | Provide a page where the user can find and edit their linked subscription products. | + | Regardless of which method you choose |
- | ==== Settings ==== | + | * The user will flag the product as being a subscription. |
+ | * They will then select the matching //package// from the drop-down, which was populated with all packages that exist in the merchant' | ||
+ | * 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. | ||
- | We recommend that you also provide a basic settings form. This form should allow the user to control some global actions, or display options. | + | Technical recommendations: |
- | * Text field to type "Terms and Conditions", | + | |
- | * Ability to turn all subscription products " | + | |
- | * Ability to select the payment options that are compatible with subscriptions. | + | |
+ | * 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/ | ||
+ | * 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 // | ||
+ | ==== Settings ==== | ||
+ | |||
+ | We recommend that you also provide a basic // | ||
+ | |||
+ | * Text field to type in "Terms and Conditions", | ||
+ | * Ability to turn all subscription products " | ||
+ | * 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 ===== | ===== Storefront ===== | ||
Line 56: | Line 87: | ||
==== Add to Cart ==== | ==== Add to Cart ==== | ||
- | The Add to Cart mechanism in your cart should be modified so that only 1 subscription | + | === Recommendation: |
- | Also during the add to cart process you will need to consider the data you will need after payment is rendered. | + | 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__, |
+ | |||
+ | * separating the subscription' | ||
+ | * 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__ 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 === | ||
+ | |||
+ | Also during the //Add to Cart// | ||
For instance, you may want to save the following: | For instance, you may want to save the following: | ||
+ | |||
* The LinkID of the product/ | * The LinkID of the product/ | ||
* A flag indicating if there is a trial | * A flag indicating if there is a trial | ||
* The trial price, if applicable | * The trial price, if applicable | ||
+ | ==== Product Details & Payment Terms Widget ==== | ||
- | ==== Product Details ==== | + | 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... |
- | The product details pages will need modified to display | + | < |
+ | $35.00 per month after the Trial | ||
+ | Plus shipping, tax, and handling fee</ | ||
- | FREE for the first month \\ | + | 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 " |
- | $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. | + | |
Learn about the [[: | Learn about the [[: | ||
+ | ==== Where to display the Subscription Terms Widget ==== | ||
- | ==== View Cart ==== | + | We recommend using the Terms Widget: |
- | Each view of the cart should be modified to accommodate a trial price. | + | - 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 | ||
+ | Here is an example of the Terms Widget shown on the shopping cart page on a [[cartintegration: | ||
- | Here is a screen shot from a shopping cart that has been integrated with SubscriptionBridge. | + | {{: |
+ | ==== Terms & Conditions ==== | ||
- | <image here> | + | Prior to the customer completing the order you should |
- | + | ||
- | ==== Agree to Terms ==== | + | |
- | + | ||
- | Prior to the payment screen | + | |
+ | As mentioned above, since different subscription products/ | ||
==== Saving the Order ==== | ==== Saving the Order ==== | ||
- | Every cart saves the order at a different location in the checkout flow. Regardless of when, 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 [[: | + | 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 [[: |
For instance, you may want to save the following with the order details: | For instance, you may want to save the following with the order details: | ||
+ | |||
* trial total | * trial total | ||
* total | * total | ||
Line 102: | Line 146: | ||
* shipping | * shipping | ||
- | If you have all of this information saved with the order then you can easily query after payment is rendered to generate the XML for your SubscriptionRequest. | + | 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 [[: |
+ | === An example === | ||
+ | Here is a practical example to visualize why you need all of this information: | ||
+ | |||
+ | * trial total: $17.50 + $1.75 = $19.25 | ||
+ | * total: $35 + $12.50 + $3.50 = $51 | ||
+ | * trial tax: $1.75 | ||
+ | * tax: $3.50 | ||
+ | * trial shipping: 0 | ||
+ | * 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 ==== | ==== Payment Screen ==== | ||
- | The payment screen is your final opportunity to be clear about the pricing terms. | + | 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 [[: |
+ | |||
+ | 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 [[: | ||
+ | |||
+ | Now, if the cart is adding tax and shipping then your total will obviously be different than the price displayed in the terms. | ||
+ | |||
+ | < | ||
+ | $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 // | ||
+ | ==== Subscription creation request 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 [[: | ||
+ | |||
+ | The important thing to remember at this point is that you validate the [[: | ||
+ | |||
+ | Once you get a " | ||
+ | |||
+ | ===== 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 < | ||
+ | |||
+ | < | ||
+ | ==== Customer account area ==== | ||
- | ==== Post Payment and Confirmation ==== | + | Similarly to the administration area: |
- | After the payment form is submit you will generate | + | * 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 | ||
- | The important thing at this point is that you validate | + | The syntax for the link to the SubscriptionBridge Customer Center |
- | Once you get a status of " | + | < |
- | Your system should not display the GUID to the customer, nor need it send subscription specific emails. | + | == Landing Pages < |
+ | * **Detail** \\ | ||
+ | * **Transaction History** \\ Replace < | ||
+ | * **Edit Billing** \\ Replace < | ||
+ | * **Edit Shipping** \\ Replace < | ||
+ | * **Cancel Subscription** \\ |
developer_guide/developer_guide/recommended.1262728124.txt.gz · Last modified: 2010/01/04 23:00 (external edit)