Shopping Cart Integration: Magento - Specifications

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).
   3. Whether there are Terms & Conditions that the customer must agree to before purchasing the subscription
      This should be a texarea field where the merchant may enter T&C for the subscription. If T&C are entered:
      1. Show the T&C during checkout (wherever it is easier to do so in Magento). For example, they could be shown on the payment page
      2. Require that the customer agree to the T&C before purchasing the subscription
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.

There are text strings that will be shown in the storefront that are specific to the SubscriptionBridge integration. The store manager should have control on what is shown. Specifically:

• Message to show when: Shopping cart in use for subscription
  For example: “The shopping cart is currently in use for purchasing a subscription. At this time, you can not add additional products to the cart. If you would like to purchase additional items, please complete the current order and then place a new one (this can be done very quickly as your customer information will have already be entered). Alternatively, you can empty the shopping cart and add different products. <a href=”“>View shopping cart</a>.”
• Message to show when: Shopping cart in use
  For example: “The shopping cart is currently in use. At this time, you can not add a subscription product to the cart. If you would like to purchase subscription items, please first complete the current order and then place a new one (this can be done very quickly as your customer information will have already be entered). Alternatively, you can empty the shopping cart and add different products. <a href=”“>View shopping cart</a>”
• Tex strings related to Terms & Conditions
  For example:
  • Terms & Conditions
  • Please read and agree to the terms & conditions listed below
  • I agree to the Terms & Conditions
• Message to show on payment page to inform customer of credit card authorization
  For example: “$1 Authorization: We will validate your credit card by performing a $1 authorization. Once authorized, the transaction will immediately be voided. This authorization is performed because our billing system will charge the actual subscription amount at a different time (later today).”

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

The customizable messages mentioned above under Settings are shown to the customer when these scenarios occur.

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.

Customers might be eligible for a discount or apply a coupon during checkout.

1. If a coupon or a discount is applied during checkout, it will affect the regular subscription amount (total)
2. Coupons and discounts do not affect the trial total (if a trial exists)

When a discount applies, the subscription terms shown by the Terms Widget will not match the subscription amount that the customer will be paying. This is not a problem. The discrepancy is explained to the customer by the merchant by using the third line of the Terms Widget.

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.

As mentioned above when defining how a product is linked to a package, if Terms & Conditions have been entered, the customer should be required to agree to the T&C before being able to submit the payment form.

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, <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):

https://www.subscriptionbridge.com/CustomerCenter/AutoLogin.asp?ID=<GUID>&Email=<EMAIL>&mode=<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.