Install - Configuration

You are about to begin the 4th and final section of the Salesforce installation. Do not install the integration in any other order than what is instructed by Chargify.

Multi-Currency Support

You DO NOT have to enable these settings if you don't intend to use multi-currency functionality.

You have the ability to select a currency for each of your Chargify sites so that the proper currency reflects in your Opportunities standard and custom fields as well as the line items in the price book.

First, you must enable multi currency support in your Salesforce Org. Once enabled, multi-currency cannot be disabled in Salesforce.

Enable multi-currency in Salesforce: + Go to Setup > Company Information + Click Edit + Select Activate Multiple Currencies + Save

Once activated, you can manage the currencies allowed in your Org.

  • Go to Setup > Manage Currencies
  • Under “Active Currencies” select “New”
    • Select currency type
    • Enter conversion rate
    • Select decimal places
    • Save

Additional steps are required to enable multiple currency support for the API User:

  • Go to Setup > Create > Objects
  • Click Chargify Setting label
  • Click Chargify Currencies field label in the Custom Fields & Relationships section
  • Select “Set field level security”
  • Make visible for any relevant profiles (be sure to enable it for the profile assigned to the sync user that installed the package as the background jobs are assigned to this user)

To enable multi-currency for the Site Guest User which handles webhooks:

  • Go to Setup > Develop > Sites
  • Click your Site Label
  • Select Public Access Settings
  • Go to Custom Field-Level Security in the Field-Level Security section
    • Click View next to Chargify Settings
    • Edit
    • Provide Read and Edit access for Chargify Currencies
  • Save

You can now navigate to the Chargify Configuration tab in Salesforce and select the supported currency for each of the subdomains you have available in your org.

Note: Field level security should already be provided for the following objects and site guest user by default if multi currency support is enabled:

  • Products (Product2)
  • Opportunities (Opportunity)
  • Price Book Entries (PriceBookEntry)
  • Coupons (CHRGFY__Coupon__c)
  • Opportunity Products (OpportunityLineItem)
  • Product Versions (CHRGFY__Product_Version__c)
  • Price Brackets (CHRGFY__Price_Brackets__c) 

Restricted Coupons Support

You DO NOT have to enable these settings if you don't intend to use restricted coupon functionality.

Restricted coupons allow you to discount only certain products or components. If you use restricted coupons in Chargify, you will want to enable restricted coupon support in your Salesforce org as well so only certain Opportunity line items are discounted.

Without this setting enabled, the SUM of all line items in your Opportunity will be discounted by default.

Enable restricted coupons in Salesforce:

  • Go to Setup > Develop > Custom Settings
    • Select “Manage” link next to “Batch Size”
    • Choose “New” (or edit existing)
    • Select “Chargify Restricted Trigger” checkbox
    • Save

Person Account Support

You DO NOT have to enable these settings if you don't intend to use Person Accounts.

This setting will allow you to create Person Accounts, which combine an Account and Contact in one. This is different from the default sync, which creates a Business Account and a Contact. Person Accounts are a good choice for businesses who work with individual customers, as opposed to companies who may have multiple contacts associated with the same account. If this functionality is enabled, all new Accounts created from Chargify will be Person Accounts.

If there are Chargify customers with existing Business Accounts, the sync will not modify the type of Account to a Person Account. Similarly, the integration will not modify any existing Person Accounts by changing them into Business Accounts.

Additionally, this setting only applies to new Chargify subscriptions that do not meet any of the matching rules you provide. As an example, let’s say the integration is configured to match subscriptions by email address and Person Account creation is enabled. If a matching email is found on a Business Account, the Opportunity will be created under the existing Business Account. A new Person Account won’t be created.

To enable integration support for Person Accounts:

  • Follow Salesforce’s guide to enable Person Accounts. Once the requirements are met, you will need to contact Salesforce support to enable Person Accounts.
  • Ensure the Person Account record type is available for all profiles that need access to its functionality. To do so, follow these steps:
    • Click on Setup
    • In the “Quick Find” box, type profile and select Profiles under Users.
    • Click on the name of a specific profile and scroll down to the section labeled “Account Record Type Defaults.”
    • Click “edit” under Person Accounts and select Person Account from the available record types.
    • Save
  • You may need to edit the Page Layout of Person Accounts to view Chargify fields. If so, follow the steps here for a Business Account but replicate the steps on a Person Account.
  • Click the checkbox for “Store Chargify Customer as Person Account” when setting up Chargify Configuration (instructions below).

Chargify Sync Configuration

Before you sync your data, there are a few things to keep in mind:

  • You may wish to enable the unique email setting in Chargify under Settings > Fields to avoid duplicate Accounts in Salesforce based on email address.
  • OR … disable Duplicate Rules and Matching Rules in Salesforce to allow duplicate Accounts, Contacts and Opportunities to be created.
  • If you are migrating from the previous Chargify Salesforce Integration, please review the Migration Path to ensure duplicate Account records are not created in your Salesforce account.

Chargify Authentication

WARNING: Once you’ve entered your Chargify subdomain and API Key in the Chargify Configuration tab and press “Submit”, data will begin to flow into Salesforce (if all previous installation steps have been completed successfully). We recommend configuring all settings on the Chargify Configuration page prior to entering your Subdomain and API Key.
Select the “Chargify Configuration” tab
  • Enter the following fields:
    • Subdomain (Format: ONLY subdomain section of: https://subdomain.chargify.com)
    • API Key
      • You can generate a new API v1 key in each Chargify site under Integrations –> API Keys. Do not use Chargify Direct or Public Keys.
    • Currency (Note: You must have multi-currency enabled in Salesforce for to use this feature)
      • If you leave the currency blank, the default currency in your Salesforce Org will be used
Location of API keys in your Chargify site
  • Select “Add a subdomain” to sync additional Chargify sites

The integration allows you to connect multiple Chargify subdomains to one Salesforce account. Please be sure you’ve created a Remote Site for each subdomain you plan to connect.

Product Filtering

The integration will not sync any Subscriptions with Salesforce if they are associated with the specified Chargify Product ID. Configure this setting from within the Chargify Configuration panel in your Salesforce account.

  • Select “Add Product”
  • Enter Product ID
  • Select “Add Product” again to enter additional product ID’s

To remove a product from the list, select the “Remove” button.

Enable product filtering by product ID
Please continue on to the next section, configuration of Chargify application within Salesforce.

Chargify Sync History (Logs)

Chargify Logs will be cleared every 12, 24, 36, 48, 60, 72 hours on the basis of the time interval selected from the dropdown.

Note: The data stored in Chargify logs will count toward your Salesforce data limits. If you run out of data in your Salesforce account, no additional logs will be stored and no additional data will sync. You can check data limits under Setup > System Overview in your Salesforce account.

Resyncing Salesforce Data

Occasionally you may need to resync your SalesForce data from the information contained in Chargify. Please follow the steps below to perform a resync:

  1. Navigate to the Chargify Configuration tab
  2. Hit submit at bottom of page after making sure “historical data import settings” are set to the right dates, or import all data if that is preferable.
  3. Go to setup Setup and search for Apex jobs.
  4. See if any CHRGFY jobs are running. If all completed the the resync is done!

Matching Rules

Match Chargify Data to Existing Account, Contact & Opportunity

Under the Chargify Configuration tab, there are a number of options available to match your Chargify data to Salesforce records based on your businesses use case. Please choose one of the following options:

Matching rules overview
  • Do Not Match Chargify Data To Existing Salesforce Data:
    • A new Chargify customer and subscription will always create a new Account, Contact, and Opportunity.
  • Match Contact Email:
    • Match Chargify Customer email to existing Salesforce Account and Contact. If email is not associated with an existing Account, create new Account and Contact. (Unique email setting suggested in Chargify Settings > Fields or use Parent Accounts in Salesforce to link multiple Accounts)
    • See Contact Email Matching Rules for more information about behavior.
  • Match Reference ID
    • Match Chargify Customer unique Reference ID to existing Salesforce Account and Contact. If Reference ID is not associated with an existing Account, create new Account and Contact.
WARNING: Reference ID's MUST be unique across all Chargify sites connected to your Salesforce account.

Match Contact Email or Reference ID

If Match Contact Email or Match Reference ID are selected, an additional option will appear for selection:

Match Contact Email or Reference ID

Match Subscription to existing Opportunity - Match Chargify Subscription to existing Salesforce Opportunity and update.

  • If this setting is selected, the integration will update the existing Opportunity with the Chargify subscription data.
  • If this setting is not selected, a new Opportunity will always be created when a Chargify subscription is created.

If this setting is selected, additional options will appear for selection:

  • If multiple Opportunities exist for a single Account, check product price book for Chargify product and update that Opportunity.

This setting allows you to match the Chargify subscription to the correct Opportunity in Salesforce if the CHargify product is attached to the Price Book (Standard Price Book and Custom Price Books supported).

If this setting is selected, additional options will appear for selection:

  • If no Chargify product associated in price book:
    • Update most recently modified Opportunity (default behavior)
    • Create new Opportunity
      • Use case: You do not want to match the Chargify subscription to an existing Opportunity if the Chargify product is not associated. For example, if your sales staff has multiple Opportunities under one Account for various upsells and each is associated with a different product.

Trialing Subscription Behavior

Some companies that offer free trials do not wish to import trialing subscriptions until they’ve transitioned to paid.

Control trial subscription behaviour
  • Include Trialing subscriptions in Matching rules selected above.
    • Use case: Treat Trialing subscriptions the same as all other states and create/update Accounts and Opportunities.
  • Update existing Opportunities with new subscriptions in a Trialing state, but do not create new Opportunities. (Only available when “Match Subscription to existing Opportunity” is selected in settings above)
    • Use case: If your sales team manually converts Leads to an Account, Contact and Opportunity, the integration will update an existing Opportunity. If the Opportunity doesn’t yet exist, the integration will not create a new one.
  • Do not import any Trialing Subscriptions until they are active.
    • Use case: You do not want to import any Trialing subscriptions unless they convert to Active.

Options for Existing Opportunities

If you have selected one of the following options under “Trialing Subscriptions Behavior”, the additional “Options for Existing Opportunities” section will appear:

  • Include Trialing subscriptions in Matching rules selected above.
  • Update existing Opportunities with new subscriptions in a Trialing state, but do not create new Opportunities.

This will allow you to choose between one of the following options:

  • Convert To Closed/Won
  • Retain Stage and Probability

Opportunities are imported as Closed/Won and 100% probability whether Trialing or Active by default. However, selecting “Include Trialing subscriptions in Matching rules selected above.” will also give you the option to configure the stage to use when creating new Opportunities:

  • When New Opportunity is created, mark as: (dropdown selection)

Convert Leads To Account And Contact

  • Match Lead by Email address - Look for any leads with the Chargify Customer email address and convert into an Account and Contact.
    • See Lead Email Matching Rules below for more information about behavior.

Leads are converted to Account and Contact. If a subscription exists for the Customer in Chargify, an Opportunity will also be created with the subscription data based on your Matching rules.

Converting leads rules overview

Owner Options

When Convert Leads in enabled, you will also have the ability to select one of the following options:

  • Retain Lead owner when converted to Account and Contact
  • Update owner to a specific user when Account and Contact are created (“Select Owner” dropdown provided to input unique user name)
    • Please ensure the selected user is a system admin or has Modify All permissions for Account and Contact Standard Object Permissions.
Owner options overview

Contact Email Matching Rules

  • When Match Contact Email setting is selected and you have multiple Contacts in Salesforce with email abc@123.com (for example) and only 1 Customer in Chargify with email abc@123.com, the integration will match the Chargify customer with the most recently modified Salesforce Contact.

  • When Match Contact Email setting is selected and you have only 1 Contact in Salesforce with email abc@123.com and multiple Customers in Chargify with email abc@123.com, the integration will match the most recently created Chargify Customer with the most recently modified Salesforce Contact. All other Chargify Customers will create a new Account and Contact in Salesforce.

  • When Match Contact Email setting is selected and you have multiple Contacts in Salesforce with email abc@123.com and multiple Customers in Chargify with email abc@123.com, the integration will match the most recently created Chargify customer with the most recently modified Salesforce Contact, the second most recent Chargify customer with the second most recently modified Salesforce contact, and so on …

Lead Email Matching Rules

When Match Lead Email is selected, but Match Contact Email is not selected, the integration will not check for Salesforce Contact email addresses that match the Chargify Customer email address. Instead it will only search Leads and convert them to an Account and Contact.

When Match Lead Email and Match Contact Email are selected, the integration will check for Salesforce Contact prior to checking for leads, if the Chargify Customer email address does not match any Salesforce Contacts, then it will check for leads and convert the most recently created Lead.

Email Validation

Chargify validates email addresses using regex recommended by the W3C, however Salesforce validation may be more strict. If an email address is deemed invalid in Salesforce, the Contact will fail to create. To avoid this, any invalid email addresses will be replaced with invalid@email.com inside Salesforce while the original email address is retained inside the Chargify Customer record.

Additional Settings

Auto Update Options For Account and Contact

You have the option to automatically push custom field updates to Chargify when edited in Salesforce Accounts and Contacts upon pressing “save”, or you can opt to require the additional action of selecting “Update Customer in Chargify” button on Account or Contact.

Additional settings overview
  • Automatically update Contact and Account field updates in Chargify upon “Save”
  • Do not push Contact and Account updates to Chargify unless “Update Customer in Chargify” button is used

Opportunity Settings For Product Change

The integration gives you the option to create a new Opportunity in Salesforce when a subscriptions product changes.

  • Update existing Opportunity on Chargify Product change
  • Create new Opportunity on Chargify Product change
Opportunity settings for product change
  • Immediate product changes with no proration and upgrade/downgrades will result in an Oportunity being created or updated immediately.
  • A delayed product change will result in an Opporutnity being created or updated once the product change takes place at the next renewal.

Once the product change takes place, the previous Opportunity will continue to store the Chargify Subscription ID, but the ID will be in parenthesis and the Opportunity will no longer receive any updates. For example, (1234567). This allows you to see which Subscription ID that Opportunity was attached to in the event you have multiple subscriptions attached to a single Customer resulting in multiple Subscription ID’s attached to a single Account in Salesforce.

The integration will respect the Matching Rules you’ve configured when updating and creating Opportunities as a result of a product change. For example, if you’ve selected “If multiple Opportunities exist for a single Account, check product price book for Chargify product and update that Opportunity.” and “If no Chargify product associated in Price Book, Create new Opportunity”, a product change will respect those rules and behave accordingly.

If the integration creates a new Opportunity based on your settings, the same Opportunity Owner as the previous Opportunity will be assigned. If the integration updates an existing Opportunity, the Opportunity owner will be retained.

Store Allocation History

When this functionality is enabled, component allocation changes will be pushed to Salesforce moving forward. Historical allocations won’t be passed.

Toggle allocation history

Default Payment Collection Method

This setting controls which option is selected by default when creating a subscription through an Opportunity. On that page, you can override the default by selecting the other option. Automatic billing will automatically charge customers each renewal; invoice billing will generate an invoice to request a manual payment.

Default Payment Collection Method

Contact Role Options

The integration will automatically link Contact and Opportunity when records are updated or created. Existing Contact Roles will be retained, but if no Contact Role is present, you can indicate which Contact Role you’d like assigned.

  • When Contact Role is created, mark role as: (dropdown selection)

Opportunity Record Type Options

All new Chargify Opportunities will be created as the record type specified here.

  • When Opportunity is created, select record type as: (dropdown selection)

Transaction Settings

Store Transactions

You have the ability to store various transaction types in Salesforce in order to report on the data. Transactions are stored in the “Chargify Transactions” Opportunity Object.

For a full list of Transactions types and kinds (subtypes), please review the documentation listed here.

Mascot
  • Select “Yes” radio button under “Do you want to store transactions in Salesforce?”
  • Choose a transaction Type
  • Click “Edit Kinds”
  • Enable all transaction kinds you’d like to store
  • Press “Submit” at the bottom of the page
Mascot

Import Historical Transactions

You also have the ability to import historical Transactions from Chargify on the basis of Transaction start and end date.

Transaction storing options by type of transaction
  • Select “Yes” radio button under “Do you want to import historical transactions to Salesforce on the basis of Transaction Date?”
  • Choose start and end date
  • Press “Submit” at the bottom of the page

Custom Price Book Settings

In order to insert Chargify products and components in Opportunity Line Items, all Chargify products must be stored in the Standard Price Book and any Custom Price Books you use in your Salesforce Org.

  • Add any Custom Price Books to “Selected” column

Historical Data Import Settings

The integration offers multiple options for importing historical data during the initial sync.

Select types of transactions
  • Import all historical data from Chargify
  • Import only Products, Components, Coupons and Custom Fields.
    • Use case: You plan to enable the “If multiple Opportunities exist for a single Account, check product price book for Chargify product and update that Opportunity.” setting and want to do an initial sync of Products only prior to importing existing Chargify subscriptions so you can attach the appropriate Chargify product to existing Opportunities.
  • Import Subscription on the basis of Start Date (created_at date in Chargify) and Subscription State

You can choose to import only Active, Past Due, and Trialing subscriptions if you have no need for storing subscriptions in Salesforce that are in an end of life state.

If you have a lot of historical data you may also wish to only import subscriptions that were created after a specific date.

Chargify Opportunity Name

You have the option of displaying the Opportunity name as Organization name + Subscription Product name OR just the Subscription Product name to satisfy multiple use cases.

Chargify Opportunity Name
  • Create and Update the Opportunity by Organization name + Subscription Product name
    • If selected and no Organization name exists, the Opportunity name will use First Name and Last Name + Product name
  • Create and Update the Opportunity by Subscription Product name

Chargify Account Name

You can add the ability to “lock” an Account name to prevent changes when the integration matches/updates a subscription to an existing Salesforce Account. If not enabled, the integration will update the Account name with the organization name, or with a combination of first name + last name if no organization is present.

Chargify Account Name

Enable Person Accounts

This setting modifies the sync to create Chargify subscriptions as a Person Account along with an Opportunity inside Salesforce.

Enable Person Accounts

If you’d like to use this feature but this setting does not appear, please follow the instructions above to enable Person Account support.

Enable Custom Field Storage

This offers the ability to store custom fields as objects inside of Salesforce. Once enabled, custom fields will be stored in Salesforce moving forward; to import custom fields that were configured before this setting was turned on, the “Import Chargify Custom Fields” button on the Opportunity may be used.

Enable Custom Field Storage

Reassign Chargify Background Job

All background jobs are assigned to the user that installed the managed package. If that user is removed from the Salesforce Organization, background jobs must be reassigned.

Reassign Chargify Background Job

Select the checkbox while logged in and all background jobs will be reassigned to the user you’re logged in as:

  • All background jobs will be removed from the previous user and restarted assigned to the current user. Select this option if the user that installed the Chargify managed package has been removed from your Salesforce Organization or you wish to reassign to another user for any reason.

API Calls During Initial Sync

To calculate how much data and how many API calls will be used during initial sync, you can multiple the below values by the number of Products, Components, Coupons, Customers and Subscriptions you have in your Chargify account.

Order Entities API Call Total API Calls
1 Validate subdomain and API Key 1 API call for each subdomain 1
2 Product Sync 1 API call per subdomain 1
3 Component Sync 1 API call per product family 1
4 Coupon Sync 1 API call per product family 1
5 Customer Sync 1 API call per 50 customers 1
6 Subscription 1 API call per 200 subscriptions 1
7 Subscription Component Sync 1 API call per subscription 1
    Total 7

Each record is approximately 2-4 kb of data stored in Salesforce. Custom fields and transaction history are not stored in Salesforce.

Congrats! You've reached the end of the Chargify / Salesforce integration installation.