Subscriptions Overview

The CODE Magazine subscription system consists of two parts:

1. The web site that allows subscribers to sign up
2. The back-end services (Microservices) that make up most of the logic of the system

Subscriptions can either be new subscriptions, or they can be renewal of an existing subscription. Both are handled by the same code/logic, although the URL seen in the browser is different, and different parameters are passed to the page.

Initial Display of Options on the Page

The first step, when a user navigates to the subscription/renewal page is to figure out what options are available to the user. The logic for that is this:

• The system figures out the “offer” the user can take advantage of, which detirmines the options available to the users. (Note: For more information on setting up subscription offers, see Olympus - Subscription Offers)
  • This is done by looking at the “referral code” parameter, which can be either a referral code or an offer code.
    • If no code is passed on the URL, the system assumes a “default” offer code
  • A referral code can actually be an offer code, or a referral code. Referral codes are sub-codes of offers, so we can differentiate different sources of the same offer. For instance, the offer code may be “conferences” for a special conference offer we are running, but the referral code may be “Build2019” to identify that this conference subscription came from a Microsoft BUILD conference attendee.
  • The referral code pulls the offer from our back-end system, and the offer then detirmines a number of things
    • The displayed information in the header area.
    • Is the subcription going to be free or paid?
    • Can the user choose print, digital, or both?
    • What is the duration of the subscription, and can the user pick different durations?
    • How many copies of the print magazine are included in this subscription, and can the user change the number of copies?
    • What countries (delivery region… we have 4 regions) is the offer valid for, and how does that change, price, print/digital, copies? For instance, a free offer for the US region may only offer digital subscriptions for free in all other regions and charge for print copies.
• The system figures out whether a coupon code was passed along on the URL
  • The URL can be https://www.codemag.com/subscribe/{offer}/{coupon}
  • If no coupon code was passed along using the standard pattern, the code can also be passed by named parameter. The parameter name is either token or coupon. As in: https://www.codemag.com/subscribe/{offer}?token={coupon} or https://www.codemag.com/subscribe/{offer}?coupon={coupon}
  • If so, a call to the subscription service is made passing along the coupon code as well as the ID if the corrent offer or referral code (whichever is used).
  • If a matching coupon is found, it is returned as part of the data that is sent to the client. This is true, even if the code was already used. However, the client will show that the code was already used and isn't valid anymore in that case. If the offer code was not found, the process continues without error. The client simply never receives a usable code. (This means that a user who has a URL code can pass that URL on to a friend, and the friend can use it to subscribe, but will never see the coupon and will not get the benefit of the coupon amount).
  • See below for more specific information about how coupons are processed.
• The system figures out whether we already know the user by checking if a user is logged in
  • If the user is logged in, we pre-fill name and address information
• The system shows a list of countries at the very top, which needs to be picked first, since it drives everything else further down the page.
  • When the user changes the country, everything from here on down changes accordingly.
  • Countries are assigned to one of 4 delivery regions. (US, North America Other, Europe, Rest of World… although this is data driven and can be changed)
  • All offers/options are set up for each delivery region (there is a “matrix” if you want to think of it like that). This is easier for us than creating all the options for each and every country.
• The system auto-generates appropriate UI elements for print/digital
  • If print is an option for the chosen region, a choice for that will be displayed
  • If digital is an option for the chosen region, a choice for that will be displayed
  • If both print and digital are options for the chosen region, then a third option for a print/digital combination will be displayed
• The system auto-generates appropriate UI elements for the duration based on the delivery region, if there is more than one choice for the subscription duration
  • Otherwise, this UI is hidden, but the duration is still listed in the summary (see below)
• The system auto-generated appropriate UI elements for the number of copies the reader wants, based on the selected delivery region, and if there is more than one option available.
  • Otherwise, this UI is hidden, but the number of copies is still listed in the summary (see below)
• The system displays a UI to enter name, email and phone number of the reader.
  • If the user is known, this section is pre-filled, but can be changed
• The system displays a UI to enter the delivery address for the subscription
  • This is handled in a format that is appropriate for the chosen country so the system can display appropriate formats (is the ZIP code before or after the City? Do we have a State? ...)
  • The country cannot be changed here, but needs to be changed at the very top, since you can't pick something like the “US” at the top to get those options, but then pick a country in a different delivery region.
  • For countries that require a state (or province), we display a state drop-down with all the states for that country (if we have a list of states/provinces for that country… otherwise a state textbox is shown). If the country does not have states/provinces, all the state/province UI is hidden and the system takes care to make sure the data for those states/provinces is set to empty as well.
• If the subscription is paid, we display a checkbox that allows the user to indicate that the billing address is the same as the delivery address.
  • If that checkbox is unchecked, a second address entry UI is displayed.
  • This address UI is identical to the delivery address area, except that the user can change the billing country.
• If the subscription price is greather than zero (this may change as the user picks different options, and is then re-evaluated) and no coupon is known (either because it was passed in on the URL, or because the user has manaully entered one), the system displays a coupon-code UI.
• If the subscription is paid, a credit card UI is displayed
• A checkbox to sign up for an email newsletter is displayed

More Info About Addresses

It can be confusing which addresses or parts of addresses can be changed. The delivery address can generally be changed, but not the country, as the country is driven by the initial choice. However, if the overall country is changed, it also changes in the delivery address UI, including address formats. The billing address can be changed freely. The address in the credit card must match the address on file with the credit card company. This enables relatively complex scenarios. For instance, someone could subscribe with a delivery address in Texas, but have EPS Austria be the true customer (thus the billing address - which is on the invoice - shows the company/address in Austria), yet the user uses a personal credit card with an associated address in Hawaii (and would then, presumably, be reimbursed by the Austrian company).

Only for Renewals

• A subscription ID parameter must be passed on the renewal URL so we know which subscription to renew
• If the subscription identified by this ID is not found, or the ID is not provided, the renewal process is abandoned
• Renewals can still be combined with offer codes
• The name of the reader cannot be changed for renewals, but things like email, phone number, and addresses can be changed.

Coupons

The system supports coupons in a variety of ways. Typically, a coupon code can be passed on the URL. It can also be entered manually (if no coupon is otherwise defined) if the subscription price resulting from the offer is greater than zero.

The value (and validity) is evaluated based on the following rules (on the client):

• The system first checks if a coupon is known
• If there is a known coupon, the system checks if the Used flag on the coupon is set. In that case, the coupon is used up and cannot be used anymore. The system displays a message accordingly, and no price deductions will be made.
• The coupon's value is considered. (For instance, a coupon may be worth a maximum of $50).
• If the price of the chosen subscription option is the same as the coupon, or lower, the system displays a message that the coupon has been applied, and thus the resulting subscription price is $0 (free).
  • If the subscription price is lower than the coupon amount (perhaps a subscription could be $29.99, but the coupon's maximum value is $50), then the system displays a message that “a coupon worth $29.99 has been applied” and thus the subscription is free. This is done even though the coupon's maximum value was higher. This is done for logistical reasons. Most of the time, users do not see the value of a coupon anyway. They just know they have a “coupon for a free subscription”.
• If the coupon's maximum value is lower than the calculated price of the subscription, the system displays a message that the coupon of a certain value was applied and thus reduced the price of the subscription. The remaining amount is being displayed and the user has to pay for the remaining amount as always (which causes the credit card UI to become visible).
• Coupons have an indication whether they can be applied to print, digital, or combo subscriptions. If the subscription offer chosen has a non-matching default (such as “print”, but the coupon is not valid for print subscriptions) then the system forces an override to a matching medium (for instance, if the offer allows for digital and the coupon does too, digital subscriptions are the new default, even if the offer says otherwise. The order of preference for coupons is “print”, “digital” and then “combo” if a switch has to be attempted.)
  • The user can still pick other options in this case. However, if the coupon does not match the selected option, the coupon value is not applied at all, and the UI shows a message stating that the coupon cannot be applied. When the user then submits such as a subscription, the coupon code is not flagged as used, since none of the coupon value is applied.
• The coupon data is then passed along when the user submits the order (see below).

Note that it is possible that the coupon is passed along as part of the URL (see above). It is also possible to enter a coupon in a coupon UI. The rules for that are as follows:

• If no coupon is known, and the calculated subscription price for the currently selected subscription options is more than $0 (not free), then a coupon UI is displayed below the displayed price (see image below).
• The user can enter a coupon code and click Apply. The system then sends the coupon code and the current subscription offer code (could be a referral code or a sub-code) to the server where the coupon information is retrieved.
• If the coupon was deemed valid for the current offer, a message is displayed to the user stating as much, and then the system calculates the new subscription price with the coupon included (see above). The coupon UI is now hidden, as it is only possible to apply one coupon per subscription.
• If the coupon is not valid, a message is displayed indicating the problem. The coupon UI remains visible.

Submitting the Order

Once a user has chosen all the desired options for the subscription/renewal, the system performs the following tasks:

• The system checks whether all required fields have been provided
  • Note that we are not using a reCaptcha control here, since it is unlikely that a spammer goes through the trouble of creating a subscription. This has never been a problem so far. We thus want to keep it as simple as possible for users to subscribe, without having to go through a reCaptcha check.
• The system first checks whether the user is already known
  • If the user was logged in, we know the user ID and thus proceed based on that knowledge. The new subscription will be tied to this existing user.
  • If the user was not logged in, we try to identify the user based on an email and phone number match. If we can uniquely identify the user, we proceed as if that user was logged in and a new subscription will be tied to that existing user.
    • Note that we only do this if we can uniquely idenfity the user. We may find the email in our system but find it for multiple people (typically for things like office@company.com or info@company.com). In that case, we must assume the user is unknown and create a new user record.
  • If we can identify the user, we see if we need to update the user data
    • If the phone number or email addres was previously unknown, we add it as additional information
    • If we can't find a matching address (see below) for the delivery address, we add it as an additional address for the user.
    • We do the same for the billing address, if the billing address is different from the delivery address (and only for paid subscriptions).
    • Credit card billing addresses are not stored as normal addrresses with the user. They will be used for credit card charging only and are discarded immediately after the card is processed.
  • If we cannot identify the user, a new user record is created and email, phone number, and addresses are assigned to the new user.
    • The billing address is only considered for paid subscriptions.
• The system creates a new subscription record for new subscriptions
  • The system sets the start date of the subscription to today for print subscriptions.
    • If the subscription includes a digital option, the system looks up when the current issue of the magazine was released and starts the subscription one day before the release date of the current issue, to make sure subscribers have immediate access to some content.
  • The end date is set to a future date relative to today, based on the lenght of the subscription. (This is true, even for digital subscriptions).
• In renewal processes, the end date of the subscription is extended
  • For current subscriptions, the end date simply extends the current end date by the chosen duration. Example: A subscription that expires in a month, and is renewed with a 2-year offer, will now expire in 2 years and one month.
  • For subscriptions that have been expired for more than 6 months, we extend by the chosen duration starting today. Example: A subscription that expired 10 months ago, and is renewed iwth a 2-year offer, will now expire 2 years from now. This potentially gives the customer free accecss to 10 months of online content. But we are OK with that. The alternative would be to give them a renewal that could potentially be already expired. Or, we would have to create a second, brand new subscription and handle it as an interruption. But we do not want to do that, since giving the customer some free digital content doesn't actually cost us anything. We throw the customer a bone here, if you want to think of it that way.
• If a coupon code is included in the request, the system checks a number of things for the coupon
  • The coupon code is verified. If the coupon is tied to a referral or sub-code (which is usually is), the system checks if the code is valid for the current subscription.
  • The system checks if the coupon has already been used.
  • The system checks the max amount of the coupon to make sure the submitted information matches what we have on file and all the amounts add up.
  • If all checks pass, the coupon is flagged as used and it is linked to the name and the subscription.
• If the subscription is paid, the system creates an invoice assigned to the billing address.
  • If a coupon is used as part of the subscription, a line item subtracting the coupon for the invoice is added.
• If the subscription is paid (and the amount is not fully covered by a coupon), the system runs the credit card.
  • If the credit card is charged successfully, the invoice is flagged as paid, and a payment record records when and how payment was made (logging that it was paid with the credit card).
  • If the credit card is declined, the transaction has to be rolled back.
    • The invoice is removed from the system.
    • If it was a new subscription, we remove the subscription from the system.
    • If it was a renewal, the end-date of the subscription is set back to the original end-date we had before the renewal process.
• If the subscription was successful, a confirmation email to the customer is triggered. We also send an email internally so we know a new subscription was placed.
• At the end of the process, a message is displayed to the user showing that the subscription was successful.
  • If the subscription was not successful for some reason, the subscription UI shows an error message and all the information remains on screen so the user can change what needs changing and trigger the subscription process again.

About Address Matching

We have a pretty good process in place to match addresses. We also have a good process in place to verify US addresses and change their format to what the USPS expects, since we call their service for verification. However, the combination of these two processes causes some odd scenarios.

Consider this address that we may enter during the subscription process:

385 Kualono Pl.
96753, Kihei, HI

When we run this through the USPS address verification processor, it is changed to the following:

385 KUALONO PL
96753-7769, WAILEA, HI

Those two addresses are identical, and we recognize this, because if we see that the addresses are both from the US, and one is verified but the other isn't, we also verify the unverified one on the fly, and check for a match then. This is slow, but it works mroe reliably than our previous process. Having added this ability (as well as fixing a number of special case scenarios we had previously), made our address verification system much more reliable and fixed several problems that used to plague us. When we compare addresses, we do NOT consider the 4-digit ZIP extension used by US addresses to be meaningful. In other words: addresses with and without the 4-digit ZIP extension are considered to be equal as long as all other fields match.

User Interface Examples

Subscription HTML UI Examples

The following is an exaple UI from a default subscription. Note the different options for print/digital, duration, and number of copies:

Compare the above to the following screen shot, which is based on a free subscription offer for Microsoft Regional Directors. Note that it does not have the duration options, and it doesn't allow for the number of copies to be selected:

Note that the price is free, even though the customer chose to have a print & digital combo subscription. That is because this is a free offer (even for print) for US customers. However, if the delivery region changed to something else, the print option now has to be paid (although if the user was to choose digital only, it woudl still be free), and accordingly, credit card UIs and logic would now kick in:

The following example shows a US address being edited:

If the country is changed to someting else however, the address format would change:

Here is the credit card UI:

Also note how the UI responsively changes for narrow browser widths or mobile devices: