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    

Site Settings

Your Recurly site settings are core to your business. These settings help define your address and currency requirements, set your company contact information, and establish payment gateway support for your business location.

Clear Test Data

When your Recurly site is in sandbox mode, use the Clear Test Data button to delete all accounts (and related subscriptions and transactions) that were created in your test site. This action will not impact any configuration elements like subscription plans, coupons, or email templates. This action is not reversible, so use it with caution.

Company Name and Site Subdomain

Company Name is used on hosted pages and default invoice templates, and can be modified here.
To update the name shown on your customer bank statements, please contact your merchant bank and request an update to your DBA.

Site subdomain is used on hosted pages and within your API credentials, so changes to site subdomain will also require an update to your API authentication. You may need to log out and log back in to see subdomain changes take effect.

Address Requirements

This sets the minimum fields required for billing address from your customers. Please make sure this matches the address requirements for your gateway's Address Validation Service requirements. Most gateways require Street Address and Postal Code, while PayPal requires a full address, and Beanstream asks for full address and phone number.

Recurly recommends collecting postal code at a minimum.

Taxes

If you are collecting taxes, make sure you are collecting enough address information for an accurate tax rate. When taxes are enabled, Country is automatically required for all Billing Information addresses on your site. Site Settings address requirements do not work with the Account Information address. If you are taxing based on the Account Information address, make sure you collect and save in Recurly the details you will need for an accurate tax rate.

Here are our recommendations:

  • United States - Full Address (Postal Code and Country is required at a minimum for U.S. Sales Tax to be calculated.)
  • Canada - Country and State/Province
  • Australia, New Zealand, Israel, European Union, Non-EU Europe - Country

Countries, Provinces and States

Recurly uses ISO alpha-2 country codes on all forms. For example, United Kingdom is "GB", not "UK". Only the United States (US), Canada (CA), Italy (IT) and the Netherlands (NL) will require a state/province if that field is required in your Site Settings address requirements. See Recurly's ISO alpha-2 Codes.

Accepted Currencies

Merchants with our Multiple Currency add-on are able to define multiple currencies in their Recurly account, which is set here. Once you start processing transactions in one currency, you will not be able to change your site to another currency.

Billing & Technical Contact

Recurly will communicate directly with Billing Contact Email for any Recurly receipts. This email address is also your site's default From email address, but this can be reconfigured in your Email Templates. The Technical Contact Email and Phone Number will be used for any major technical issues related to your site. Multiple Technical Contact Emails can be added, separated by a comma. Since many of these messages are directly actionable, please do not use role-based email addresses (e.g. sales@, info@, or admin@) for either of these contacts.

Company Details

These fields define your company information for display on your customer invoices. Setting your country will also determine the Payment Gateways available to your business.

Value Added Tax (VAT)

VAT is available on all Recurly accounts that have set an EU country in their customer invoice details. Please see our Value Added Tax (VAT) documentation for more information on how VAT is processed.

Whitelisted IP Address Range

This feature allows merchants to specify a public IP address or range that represents your computers and bypasses Recurly's fraud checks. This feature is especially useful for merchants who manually process transactions on behalf of their customers.

IP Addresses can be given in the following formats:

Single IP: 192.168.0.1

IP Range: 192.168.12.0/24 (Range must be narrower than /24).

Invoice Prefixing

Merchants who have multiple billing systems funneling into one gateway account can define an Order Number Prefix inside of Recurly. This will help you uniquely identify Recurly transactions inside your payment gateway virtual terminal. Please note that this is on the backend only and will not show up on the invoice.

Site Settings

Your Recurly site settings are core to your business. These settings help define your address and currency requirements, set your company contact information, and establish payment gateway support for your business location.