Getting Started with Sales in Arc XP Subscriptions

With Arc XP Sales you can build a robust Subscriptions platform so your users can easily make subscription and product purchases. We have engineered our sales process to reduce purchase friction while allowing you to customize the user experience.

The main component of Arc XP Sales is the checkout for both subscriptions and single products but we also manage the renewal process.

Step 1: Picking a Payment Gateway

Arc XP Subscriptions supports a wide selection of payment gateway partners and tax providers for easy setup and seamless checkout functionality. Using hosted pay pages lets Arc XP Subscriptions offer bank-level security with a consistent user experience. The following table lists the payment providers that Arc XP Subscriptions supports.

Before you get started building your checkout workflow you need to determine your payment method. We provide multiple options and cover many methods of digital payments.

Gateway	Covered Counties	Identifier	Setup Documentation
IFX	Use the payment gateways of your choice with our extensible payment gateways capabilities	19	IFX Setup
Braintree	United States, Canada, Australia, Europe, Singapore, Hong Kong SAR China, Malaysia, and New Zealand	15	Braintree Setup
Stripe Intents	https://stripe.com/global	18
PayPal Classic	https://www.paypal.com/us/webapps/mpp/country-worldwide	10
PayU	Colombia, Argentina, Brazil, Mexico, Chile, Peru and Panama	8
Payment Express	https://www.windcave.com/support-processing-partners	2
Subscribe with Google (SwG)	https://developers.google.com/news/subscribe/integration-requirements	18

Adding a payment provider

Payment providers can be configured in the Subscriptions Admin. In the Settings admin, select Payment Provider under the Sales section, then click Add payment provider.

The list of required parameters for each payment provider are available in a table at the bottom of this article.

Step 2: Building up your Checkout Flow

It is the process through which the customers are driven to order products online. It enables customers to quickly select products knowing how much they need to pay for them. Once the customer has selected their products by adding them to a cart, the system guides users through the checkout process where the client can select among different payment gateway partners.

One or several products are selected and added to a cart by the customer. Then, once they wish to start the payment process, an order is created with all products into the cart and the payment process is initialized according to the payment option selected by the customer (payment options list provided by the system). Finally, the customer should provide billing information and authorize the payment.

Note: You can configure to not allow customers to add more than one item to their shopping cart during checkout. This setting default value is OFF, so the cart allows multiple products, but setting the switch to ON can help eliminate cases where customers accidentally purchase multiple subscriptions. If you want to enable this setting, please contact ACS to submit a ticket for the Subscriptions team to turn the switch On.

Step 3: Understanding Subscriptions and Renewals

Arc Subscriptions supports three different subscription acquisition methods, which enables a host of business strategies. In this context, the acquisition method refers to how the customer came to possess the subscription. One underlying subscription product SKU, such as Digital All Access, can be granted to a user in one of three ways:

1. Paid: When a customer purchases a subscription using an Arc Subscriptions-orchestrated checkout, this subscription is attributed to the Identity account as a paid subscription.

2. Associate - Paid subscriptions can have additional Identity accounts that leverage the subscription entitlement. This is typically used for Friends and Family packages.

   • When configuring a product, you can specify how many users the subscription owner can share their subscription with. The person who purchased the subscription maintains sole ownership of the subscription, and can share the benefits of the product with the allotted number of people. Each associate must have their own Identity account and password.

3. Linked: A client-controlled service that is outside of the Arc Subscriptions universe can Securely Communicate With Arc Subscriptions to grant a subscription to a customer without a related Arc Subscriptions transaction. This acquisition method is intended for scenarios where the user is entitled to a subscription because of a purchase made elsewhere. For example, the customer purchased a print subscription which was bundled with digital access. More details on linked subscriptions are in the How to link external subscriptions to Arc XP Digital Subscriptions guide.

Free: A customer can be granted a free subscription by a customer service agent from within the admin. This is intended for scenarios where the customer should have access to a subscription without a related transaction. For example, the advertising department might want to grant digital access to the Chief Marketing Officer of a large advertiser so that the CMO doesn’t hit the paywall while checking out their ads in action.

Renewal Calculations

• Yearly: Renewal payment due date is set to the same day of each year. The only exception is when the initial purchase is completed on a leap year, February 29, all subsequent renewal payment due dates will be on February 28.

• Monthly: Renewal payment due date is set to the same day of each month except when the day does not exist in the next month. The renewal payment due date will take place on the last day of the month when the initial purchase day does not exist. The due date is recalculated each month and will return to the day of purchase if possible.

  Example: Initial purchase: 1/31, Calculated Next Due Dates: 2/28, 3/31, 4/30, 5/31, 6/30, 7/31, 8/31, 9/30, 10/31, 11/30, 12/31.

• Weekly: Renewal payment due date is set to the dame day of the week as the initial purchase.

Subscriptions Status Codes

Code	Status	Access Notes
1	Active	User can fully access entitlement
2	Terminated	Subscription is no longer available for user to access
3	Canceled	Entitlement will be revoked when the termination date is reached
4	Suspended	Entitlement will be revoked if payment is not made by termination date
5	Gifted	Subscription was provided as a one time payment gift, to continue past the termination date user will need to provide new payment method and update their subscription.
6	Smart Dunning	Renewal payment failed, retry logic will proceed and entitlement will be revoked if payment is not successful
7	Vindicia	Renewal payment failed, subscription was sent to Vindicia for collection, entitlement will be revoked if payment is not successful

Step 4: Setup Tax Calculations

Arc XP Subscriptions offers 3 options for managing tax calculations

1. Zero tax
2. Custom Manual Tax: Up to 8 countries & regions
3. Taxamo integration

More details on setting up these options, managing tax configurations and updating individual customer address tax status is available in the How to calculate taxes in Arc XP Subscriptions article.

Step 5: Updating Active Subscriptions

Upselling is critical to a successful subscription business and now you can create a flow on your site for users to quickly upgrade. Customer subscriptions can be changed through the Customer Service admin by your representatives or using public APIs with an upgrade flow for your customers. Both of these options allow for immediate subscription product or price changes. There are also developer APIs available to schedule a price change after the current renewal cycle is complete.

Customer Service Admin Subscription Changes

At times your customer service agents will want to update a reader’s subscription as a retention effort or as a large price strategy change. Changes to one subscriber’s product or price can be made in the Customer Support Portal on the active subscription screen.

Website Subscription Changes

A key part of a subscription product strategy is helping customers upgrade to a higher tier product. There are two public APIs that can be used to build a user flow that will make a change to a customer active subscription granting them immediate entitlement. This can be used to upgrade customers to a high value product but also in a “save” flow to downgrade a product or price. As part of the subscription change, these APIs will provide the customer a refund for any remaining balance, and then charge the customer for the new subscription terms.

There are two main API endpoints that need to be used to make the subscription change, calculate a refund and the new charge amount.

• InitializePriceUpdate: This will validate all details for change, calculate any refund amount, new charge amount based on the Subscription ID and Price Code that is passed. The respond will include the details below.

       {
      “initializedId”: “793cdad9-231e-4579-a3f0-3b5ace6f8c19″,
      “refundAmount” : 12.3,
      “chargeAmount” : 33.2,
      “taxAmount” : 3.2,
      “refundAmountMin” : 10.0,
      “chargeAmountMin” : 10.0,
      “refundAmountMet” : true,
      “chargeAmountMet” : true,
      “sameRenewalterms” : true,
      “nextRenewalDateUTC” : “2018-06-22T15:27:43.606Z”
  }

• FinalizePriceUpdate: This will execute the change with the already calculated refund and charge amount based on the Subscription ID and Initialized ID (from initializePriceUpdate) that are passed in. The response will include the details below.

       {
      “subscriptionID”: 123,
      “productSKU” : “SKU”,
      “productName” : “productName”,
      “priceCode” : “PRI001″,
      “nextEventDateUTC” : “2018-06-22T15:27:43.606Z”
  }

For a Price Code to be eligible for a price change by an end user it will need to be set as “change eligible” in the Price details screen. This can be done for all Prices, even ones that are part of a Published offer.

An example flow for an upgrade path can be found in the Developers guide to setting up a Paywall.

Based on the type of change made to the active subscription renewal terms there are two options for the next renewal date, refund and new charge:

1. Change Subscription and keep the same renewal terms: (month to month, year to year)
2. Change product/price and move to different renewal terms: (monthly to yearly, yearly to weekly, compare number of weeks & days as different terms, example 30 days to 10 days, 2 weeks to 4 weeks)

Server to Server and Bulk Subscription Changes

Prices increase and your subscription strategy needs to be adjust with the market. The pricing tiers provides flexibility when creating short term promotional rates and increases but for wider strategy updates more tools are needed. We provide 2 API endpoints for clients to do a mass price change and move subscribers to a new price rate. These APIs can be used to update an individual subscription using the Subscription ID or bulk updates using the Product and Start Date.

Individual Subscriptions

• The endpoint PUT …/sales/api/v1/subscription/{id}/pricechange is used to update the product and price for the specific Subscription ID.
• A future date, effectiveDate, is required and will be used to schedule when the price change can be processed. The change goes into affect on the first renewal after this date.
• The Product SKU and Price Code are used to set the new price rate. The Price must be added and linked to the Product prior to starting the price update and applying it the subscriptions for the change to process.
• The initial price rate cycle index is 0. The first rate, index 0, will be used if no cycle is entered. A different cycle can be entered by using 1 as the second tier, 2 as the third.

This API allows clients to connect with propensity systems that can select the Subscribers most likely to accept a price increase.

Bulk updates

• The endpoint POST …/sales/api/v1/batchpricechange is used to update the product and price for multiple subscriptions based on their current Product, Price and the date they started. This endpoint can be used for updating all customers who have been subscribers of a specific product for a length of time.
• The Started Before Date, from SKU and from Price Code determines what subscriptions are impacted by the update.
  • Product SKU and codePrice need to be associated for the change to process
• A future date, effectiveDate, is required and will be used to schedule when the price changes can be processed. Each change will go into affect on their first renewal after this date.
• The To Product SKU and To Price Code are used to set the new subscription details. The Price must be added and linked to the Product prior to starting the price update and applying it the subscriptions for the change to process.
• The initial price rate cycle index is 0. The first rate, index 0, will be used if no cycle is entered. A different cycle can be entered by using 1 as the second tier, 2 as the third.

Client Communication
Three WebSocket Events are sent at different intervals when a price change is scheduled; Price Change Scheduled, Upcoming Price Change (sent 14 days prior to price change), Update SKU PriceCode. These can be used to communicate with your customers on the pending price change.

Considerations:

• Changing price only applies to “paid” subscriptions. “cancelled”, “terminated”, “free” and “linked” subscriptions cannot have a price change. Only an active or suspended subscription can have its price changed.
• The new price should be equal to or higher than zero. Note: Paypal doesn’t accept zero-dollar price change renewals.
• When several changes are made over the same price, these changes are queued and will be applied in order. For now, the only way to remove the values from this queue is using Private APIs.
• If a change price is scheduled for a batch of users, this will only affect those subscriptions that exist when the price change is requested.

Additional details on using these APIs can be found in the Arc XP Sales Developer APIs.

Refunds Calculations for Subscription Changes

When making an update to an active product or price in the Customer Service Admin, if the change is to take effect immediately, a refund will sometimes need to be given to the customer for the remainder of the balance. More details of the Customer Service Admin functionality are available in the How to Use Customer Service Admin guide, under the Subscription section.

The system will provide a suggested prorated refund amount based on the amount that was paid during that billing cycle. The prior refunds are considered in the calculation for the suggested refund amount. If the subscription is in the middle of a payment cycle then a prorated amount will be suggested using the calculation below. Tax is included as part of all calculations and all time calculations are to the millisecond.

suggestedRefund = (lastPaymentAmount) * [remainingTimeOnCurrentCycle / totalTimeCurrentCycle]

After the refund and new price charge, the subscription renewal will continue based on the new price terms. The next charge will happen based on the new price terms schedule.

Payment Provider Parameters

Payment provider	Parameters	Additional information
2	Payment Express Nickname* Tenant’s PxPay user id: Tenant’s PxPay password: PxPay API URL provided by Payment Express: PxPay success URL: PxPay fail URL: PxPay success redirect: Tenant’s PxPost user id: Tenant’s PxPost password: PxPost API URL provided by Payment Express: Currency to be used during payment method update: PxPay update success URL: PxPay update failure URL: PxPay update success redirect: Minimum refund value & Minimum charge value**
8	PayU Latam Nickname* Public key Account ID Public API URL Credit card Verification amount Merchant ID API login API Key CGU endpoint (URL) Payment/Account country Language Test mode flag Query endpoint (URL) CVV2 security code for renewals Minimum refund value & Minimum charge value**
10	PayPal Nickname* Return URL Cancel URL Order description Billing Agreement description PayPal Classic username PayPal classic password PayPal classic signature PayPal classic App ID mode: sandbox or production
15	Braintree Nickname* Publishable API key Private API key Merchant ID mode: Sandbox or production Delete unneeded payment tokens flag	Braintree credentials How to add Braintree as a payment provider
16	SwG Nickname* SwG Publication ID SWG OAuth2 Service Account Document
18	Stripe Intents Nickname* Publishable API key Private API key Delete unneeded payment tokens flag	Checkout flow with Stripe Intents

*Nickname: This is used to help describe the payment provider elsewhere in Arc XP.

**Minimum refund value and Minimum charge value are the thresholds used during the change product/price.