SUBSCRIPTIONS / PRESCRIPTIONS

SendSafe has the ability to process subscriptions including the ability to force billing by creating reorders periodically (i.e. monthly ordering of a refill prescription OR web site content subscription). Subscriptions can be configured to automatically renew at the end OR the expire when complete.

Subscriptions can be used for selling shippable products, digital payloads, pay-per-view websites, and much more!

SUBSCRIPTION OPERATION

IMPORTANT: Values in the OrderLineItem and OrderLineItemExt for the "parent order" is the control block for the subscription.

The parent order is the orignal order in which the subscription was purchased. Control values in the subscription control block are:

Subscription Life cycle:

  1. Subscription is ordered
  2. Subscription is activated [ subscriptionPeriodsLeft = # of periods | SubscriptionEnabed = 1 ]
  3. When the refill item has a quantity (items.QtyInStock) of zero then the subscription is on hold
  4. When each period is complete, a seperate REFILL order is placed for each subscription lineitem in the order using SubscriptionForcedOrderSKU and the SAME price that was originally charged for the item [ subscriptionPeriodsLeft is decremented ]
  5. When subscriptionPeriodsLeft = 0 the subscription has expired and access or services should be terminated [ subscriptionPeriodsLeft = 0 | SubscriptionEnabed = 1 ]
  6. If auto-renew is enabled THEN WHEN the subscriptionPeriodsLeft would be decremented to 0 INSTEAD the original subscription is started i.e. subscriptionPeriodsLeft = original number of periods.
  7. If a subscription charge fails then then "SubscriptionEnabed = 2" will be maintained until the charge is approved unless SUBSCRIPTION TERMINAL COUNT charges in a row are declined; in which case the subscription is disabled and "SubscriptionEnabed = 0". In the case of retry, the subscription control is setup so that the next period will expire in 24 hours WHICH effectively forces a retry of the charge in 24 hours. Depending on subscription processing times and cutoff times, the retry may not occur for as long as 48 hours.

There are two ways to find the "parent order" - either from the most recent subscription reorder OR by searching through all orders placed by the customer. The preferred method is to use a recent refill order.

To find the original subscription order from a refill: load the orderlineitem for any refill for the customer. To find a list of refills for a customer follow these steps:

  1. Open the Order LineItem Admin Page
  2. Enter the ItemIdCode for the subscription refill item. If you do not know the ItemCodeId use the Items admin page to locate this information.
  3. Enter the name of the customer into the "Contact Name" field.
  4. Press the [ Find Records ] button.

Once you have a refill orderline item loaded look in the AltItemDescription field. An so# appears in the AltItemDescription. The so# is the subscription order LineItemID for which this refill was issued. This is the LineItemID from the "parent order."

FYI: Make sure you copy the entire so# since it can run off the entry field to the right and the entire number may therefore not be visible.

Be sure to never change the AltItemDescription; changing this field can cause a subscription to fail.

Subscriptions can be turned on and off by setting the SubscriptionEnabed column in the control block: 0 = disabled, 1 = enabled, and 2 = enabled but NOT approved (i.e. the subscription is running but charges have been declined and will be retried). Load the "parent order" into the order admin page then click on the order lineitem for the subscription. Locate the SubscriptionEnabed and set as desired.

Subscriptions can be globally paused for an item by setting the items.QtyInStock for the refill to zero.

The shipto address can be changed in the customer MyAccount page or by editing addresses record that the ShiptoaddressID references in the control block (i.e. the original shipping address in the parent order). Load the "parent order" into the order admin page then click on the order lineitem for the subscription and make address changes as desired on the order lineitem.

The ship method can be changed by editing the ShipMethod in the control block. Load the "parent order" into the order admin page then click on the order lineitem for the subscription and make changes as desired on the order lineitem.

The number of refill orders remaining in a subscription can be changed by editing the SubscriptionPeriodsLeft in the control block. Load the "parent order" into the order admin page then click on the order lineitem for the subscription and make changes as desired on the order lineitem.

The date that the susbscription will be refilled can be changed by editing the NextOrderDate in the control block. Load the "parent order" into the order admin page then click on the order lineitem for the subscription and make changes as desired on the order lineitem.

If a credit card charge fails on a automated subscription reorder then the customer should be directed to use the Credit Card information update function found on the My Account page. The failed subscription reorder will be retried every 24 hours. If the customer has updated their account information then the retry will use the new information. Under no circumstances should the customer place a manual order for the items that would have been reordered by the subscription. If the customer does this they will be charged for both the manual order and then 24 hours later when the automated reorder goes through, they will be changed again (and receive double products).

SUBSCRIPTION REFILL PRICING

Subscription refills will charged the same price for the item during the entire lifetime of the subscription. Each refill is a clone of the original donnor order. The following costs will remain the same regardless the changes made to Items, customer records, or shipping cost pages. Cloned subscription orders WILL NOT retain the same SendSafeTxNum as the donnor; the Transactionid and SendSafeTxNum will be the same in a cloned subscription.

*The portion of the sales tax or shipping charges for a refill will be a simple ratio of the original amount
i.e. ratio = [SubTotal of all LineItems] / [Price of refill lineitem]
THEN protion of sales tax = original sales tax x ratio

The cloning process does have limitations. If a person moves from a location where sales tax is changed to a location where sales tax is not charge, then the control block records (original order) must have the sales tax amount changed. This must be done so that future clones of an order will have the correct amount. The same is true for price increase or changes in shipping charges.

SUBSCRIPTION SETUP

Steps to setup a subscription:

  1. Create an Item which will be the subscription that is ordered (see "Subcription Items" below).
  2. Create a matchng refill item (see SubscriptionForcedOrderSKU)
  3. Add Subscription biling job (see billing job)
  4. Configure robot for subscriptions (see robot setup)
  5. Test subscription ordering (see subscription testing)

Subscription Items are setup by assigning these values to an item which will be purchased as a subscription. These values are located in the ItemsExt:

Subscriptions must be setup so the Item which is the subscription also fulfills the first subscription allotment.

The refill SubscriptionForcedOrderSKU item will be used for subsequient orders. This item must NOT BE THE SAME SKU as the parent subscription item. The same item sku can be used by multiple different parent subscription items.

A free number of refills can be specified for a subscription as a bonus for purchasing a subscription instead of individual order.

The the deplexing flag is required in almost all cases so that subscription is processed as seperate lineitems if a item quantity of great than one was ordered.

To create a subscription which is only billed once and does not send out refills or process reorders set SubscriptionForcedOrderSKU to null.

Optional (legacy): You can make all listed subscriptions mutually exclusive by listing them in: Application("SubscriptionSKUS") = "S-001,S-006,S-101,S-106"

CHANGING SUBSCRIPTION SHIPPING

The customer can change the shipping address used for subscription refills by going to the MyAccount page and changing the subscription address.

The shipping address and method for subscription refills can also be change using the admin pages. To change the ship address or method for all future refills you must change the information in the original subscription. The original subscription is the control-block used for all refills. To find the original subscription order from a refill: load the orderlineitem for any refill and look in the AltItemDescription field. The so# appearing in the AltItemDescription is the subscription order number from which this refill was issued.

FYI: Make sure you copy the entire so# - since it can run off the entry field to the right and the entire number may therefore not be visible.

PAUSING A SUBSCRIPTION

Subscriptions can be paused individually or globally.

Global pause
Subscriptions can be globally paused for any item by setting the items.QtyInStock for the refill item to zero.

Individual pause
The admin page or SQL can be used to pause subscriptions. The subscription is paused by setting the SubscriptionEnabed flag to something other than 1. If you need to perform bulk enable/disable, the best way to do this is the set SubscriptionEnabed to something other than the defined 0=disabled and 1=enabled State. The processing logic uses an SQL query which include the clause "SubscriptionEnabed > 0" - as a result SubscriptionEnabed = -1 and be in a state where it is NOT disabled but also not running.

Any negative number can be used for pausing. As a result there can be an unlimited number of groups of subscriptions which are paused for different reasons and remain easily grouped.

SUBSCRIPTION CONFIGURATION IN ROBOT

In the global storefront file storefront config file:

Keyword Description
SUBSCRIPTIONS ENABLED = YES Enabled and disables activating subscription orders as they come in.
SUBSCRIPTION TERMINAL COUNT = 5 Set the number of failed charges before a subscription is disabled.
CONDDEPLEX LINEITEMS = YES Enable/Disable conditional deduplex of flagged lineitems

 

TESTING SUBSCRIPTIONS

Once you have subscriptions setup, you should test the setup.

  1. Place an order for the subscription
  2. Check that the order was placed correctly by loading the control block (lineItem) and examining the values for accuracy; note that SubscriptionPeriodsLeft = ( SubscriptionPeriodLength - 1) this is because the subscription is counted as the 1st order and it just occured.
  3. Edit the control block and set the NextOrderDate = 1/1/2006 (this date earlier than today's date will cause an immediate run and a refill order to be generated)
  4. Force the subscription job to run early by setting nextrun = null
  5. Check that the refill order was placed correctly and the LineItemID for the control block has been placed in the AltItemDescription of the refill.
  6. Edit the control block and set the SubscriptionPeriodsLeft = 1 and NextOrderDate = null (this will cause an immediate run and the subscription will expire or renew)
  7. Check that the subscription either expired OR was renewed as configured; note that renewed subscriptions will have SubscriptionPeriodsLeft = SubscriptionPeriodLength.

 

Subscription Activation

Subscription activation occurs when the subscription is first purchased. Acitivation sets up the subscription control block in the parent order lineitem. The activation function is performed by activateSubscriptionInOrder(). The following occurs:

 

SUBSCRIPTION BILLING JOB 20

Subscription billing is performed on orderlineitems and automatically forces a subscription order through the system for every subscription it finds. The activities performed by this job are listed below. These activities are performed on subscriptions which are enabled and in a state where action is required (i.e. NextOrderDate <= getDate()).

This function is run by a JobQueue job which looks like the example below:



Parameter value
param1 If set to 1 THEN charge for shipping on free subscription refills; set to anything other than one will result in zero shipping charges on any free subscription refill.
param2 Renewal mode: If set to 1 THEN subscription will automatically renew. If set to 0 or null then subscriptions will not automatically renew when their period has expired.
param3 max number of orders to process each pass (max value = 500)

Notes:

LISTING / ADVERTISEMENT SUBSCRIPTION TERMINATION JOB 35

The Generic SQL Job is used to run termination code which searches for listing / Advertisement subscription which have completed and then disabled their associated listings, advertisements, and other product records.

The termination jobs for listings finds subscriptions which have all billing cycles (SubscriptionType) completed and disables display of the subscription listing. The SQL which is used for Listing is: 

update listing set ApprovedForDisplay = 0
where indexkey in
(
Select listing.indexkey
from 
Orders, OrderLineItem, OrderLineItemExt, ItemsExt, listing 
where 
Orders.transactionid = OrderLineItem.transactionid and 
OrderLineItem.ItemCodeId = ItemsExt.ItemCodeId and 
OrderLineItem.LineItemid = OrderLineItemExt.LineItemid and 
listing.orderLineItemID = OrderLineItem.LineItemID and

NextOrderDate <= getDate() and 
SubscriptionPeriodsLeft = 0 and 
SubscriptionEnabed > 0 and 
Orders.ApprovalCode like '%approved%' 
)

This function is run by a JobQueue job which looks like the example below:



Parameter value
param1 Selection logic (with the first field being the record locator code for the listing or advertisement)
param2 n/a
param3 n/a

Notes: