The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Go Live Checklist

Have you explored all of Recurly's functionality and configurations before going live? Follow the checklist below for a complete integration!

Site Settings

Your site settings are the core part of helping Recurly bill your customers. Everything from the gateways Recurly displays to the taxes that can be charged, are controlled by these settings.

Company Name & Recurly Subdomain

Your company name will be displayed all all invoices and emails, while subdomain is only exposed on the hosted pages.

Company Location

Your company location determines what supported gateways are shown as well as how tax rates are offered and calculated. The company location that is used at signup will also help define the default site currency, although that may later be changed.

Company URL

This is used primarily for the logout link on the Hosted Account Management Page - the customer will be brought to this URL when they opt to log out.

Tax Information

Supply your own company information for display on your customer invoices.

Site Contacts

Site Technical and Billing Contacts should be your go-to contacts for any urgent issues coming from Recurly support. The site billing contact is also the default address for your customer communications, but that can be overridden on the Email Settings page.

Plans

Your subscription plans tell Recurly how much and how often to bill your customers.

Accounting Code Scheme

This is an optional set of data, but for larger companies an accounting department may insist on populating data with an accounting code scheme to help recognize revenue in specific buckets. This data can always be added to Recurly in the future as your company grows!

Editable Quantities

Checking this option allows your customers to choose the quantity of their purchase at checkout. Regardless of this setting, you may still override quantities using other Recurly integration methods.

Tax Options

At a high level, you can decide whether or not this subscription plan is eligible for tax rates. You may also define the tax type, which is used for more advanced tax calculations.

Trial Options

By configuring this option, your subscription plans will have a default trial period. This can always be overwritten on a per-user basis or customized during Recurly.js checkouts.

Reminder Emails

There are two options to configure at the plan level - a trial ending email and a renewal reminder email, each sent 7 days before a trial ends or subscription renews. These emails are especially important to configure if your state/location has trial opt-in rules, or you offer annual subscriptions.

Success Configuration (for Hosted Payment Pages only)

For merchants with an integration using the Hosted Payment Pages, look to enable this functionality to allow the customers a redirect to a specific page after their subscription process is complete.

Invoice Settings

Making sure to properly set your invoice settings will ensure your customers get timely notifications, as well as ensure your modification settings fit your billing requirements.

Invoice terms

Configure your invoice defaults to give your customer support agents a step in the right direction! These values can always be overwritten as needed.

Subscription modification settings

These two settings allow your business to control what happens when a user wishes to change their subscription and has a payment problem. This setting may not be as needed as you just start in Recurly, but can always be modified as you experience issues with subscription changes and non-payment.

Currencies

Most customers will default to just one currency (defined above, in your site settings), but multiple currencies can be enabled on this page for merchants subscribed to Recurly's Professional plan. If you plan to add more currencies, be sure to check for:

Plan configurations

If adding multiple currencies, make sure to access your subscription plans to identify the plan price point in each currency you offer.

Coupon configurations

If adding multiple currencies, make sure to access your coupons to identify the discount price point in each currency you offer.

Taxes

Tax settings are important to ensure you're in compliance with any regulations imposed by your local tax authorities. Luckily, Recurly's got you covered with our out-of-the-box integration with Avalara:

Jurisdictions

If you need to collect tax from any customers, set your taxable jurisdictions. Not sure if you need to charge tax? Check with a tax accountant!

Tax Addresses

Decide whether to use the billing-level address (ideally for electronic goods) or account-level address (ideally for physical goods) for tax calculations

Site Settings

Update your Site Settings with important taxation information about your company - including VAT number, registration number, or invoice notes.

Validation

Decide whether or not to use VIES for VAT validation (warning: turning off this feature means you may accept potentially invalid VAT numbers), and set requirements for validation evidence.

Email Templates

Setting good communication with your customers is key to reducing churn and recovering revenue. When configuring your email templates, check for things like:

Customize Header and Footer

You can add custom HTML to the header and the footer of your emails. This allows you to put information like a company logo or address information to personalize your emails.

Email settings

Under the Settings for each email template, you can control certain functions:

Enabling/Disabling emails

Depending on your communication style, you may not want Recurly to send emails. You have the option to enable or disable each email type.

Set Email BCC's

Add BCC's to alert employees to critical actions, such as subscription cancelations or late manual invoices.

Overriding default FROM addresses

Your FROM address will default to your site billing contact. You may override this email address (which your customer sees) on a per-email basis.

Payment Gateway

Your payment gateway is key to success at Recurly, so spend time getting this just right.

Credentials

Your payment gateway will provide you with a set of credentials, usually called API credentials. Contact your gateway for instructions if you do not already have this data. You will need to select your supported currencies and card types.

Test

Once you have your credentials entered, run a test transaction to validate a basic transaction (please note this is not 100% accurate in all cases, but a good indicator of successful integration).

Account Updater

Enable Recurly's Account Updater functionality

Addresses

Validate your address requirements (see site settings) with your gateway AVS controls. Make sure you are passing through all the information your gateway requires.

ZDA

If your gateway supports Zero Dollar Authorizations, you may enable this functionality.

Apply for ACH

ACH is handled by our partner, Check Commerce. Please note ACH applications can take around 6 weeks and require significant data to process. Start early!

Hosted Pages

Hosted Pages are basic Recurly integrations targeted at companies without developer resources, or companies that want to go live quickly while developing a more robust and customized integration.

Access

Enable or disable hosted payment pages/account management pages, depending on your desired customer experience. If you want your customers to be able to log in from your website, query the Recurly API for the customer's hosted login URL.

Customize

Upload a company logo, background background color, and add a ToS and/or privacy policy link. You may also customize your signout URL, which is defined in your Site Settings

Options

Want to let your customers pay online or self-service their subscription cancelations? Make sure to choose these options.

ACH

If you already have a Check Commerce account up and running with Recurly, you may add the ACH option to your hosted pages.

Dunning Management

Recurring payments fail. It's a fact of life. Recover more of those invoices by setting a dunning policy that makes sense for your user base:

Email frequency

In general Recurly recommends that B2B companies set fewer emails, over a long time period while B2C companies set more frequent emails over a shorter time period.

End result

Expire the subscription or leave it active? Leaving the subscription active is best if you have external collection efforts.

Dunning length

Make sure your dunning cycle is never longer than your shortest plan.

User Access

User invites and settings are managed in the Admin section on the Users page. Because Recurly doesn't charge on a per-seat basis, you're free to add everyone in your company! How can you do this safely?

User access

Each user should be added to Recurly under their own company email address. This allows for proper auditing and account controls

Permissions

Set a role appropriate to each user's access needs - don't give access to more than a person needs.

Timezones

Each user can configure Recurly to display in their local timezone. This is great for multi-national teams.

Passwords

Your Recurly password should be unique. Do not share this password or use it for any other systems

Alerts

Subscribe to status.recurly.com and/or follow @recurlystatus for system updates

Training

Attend a Recurly class. Register at info.recurly.com.