Installation

We recommend testing the integration in a Salesforce test environment prior to enabling in production. You can signup for a Salesforce developer account free of charge or create an additional sandbox environment in your existing Salesforce account.

Download

Download the Chargify for Salesforce package from the Salesforce AppExchange.

You will receive a 14-day free trial. Please contact Chargify support to purchase user licenses if you wish to continue the service.

Install

Chargify offers a paid Salesforce Installation Assistance service. Please submit a request if you’re interested in having our team of experts install and configure the integration on your behalf.

Once installation is complete, you will automatically be redirected to the Installed Packages page in Salesforce. This process may take a few minutes.

Accessing The Installed App

  • In the App Menu, select the Chargify App

  • All Chargify tabs will be configured
    • Accounts
    • Contacts
    • Opportunities
    • Products
    • Product Families
    • Coupons
    • Chargify Configuration
    • Chargify Settings
    • Chargify Logs

Remote Site Settings

A separate Remote Site is required for each Chargify subdomain you plan to connect to your Salesforce account.

  • Go to Setup → Security Controls → Remote Site Settings
  • Create a New Remote Site
  • Enter:
    • Remote Site Name (supports lower case characters and underscores only)
    • Remote Site URL (ie. https://subdomain.chargify.com)
    • Enable Active checkbox
  • Save

Configure Account Layout

  • Click on Accounts tab
  • Select an Account record by clicking on an Account Name in the list
  • Click “Edit Layout” on the account detail page

  • In “Fields”, drag and drop a new “Section” into the layout:
    • Section Name: Chargify
    • Display Section Header on:
      • Detail Page
      • Edit Page
    • 2 column
    • OK
  • Drag the following fields into the new Chargify section:
    • Chargify Customer Created at
    • Chargify Customer ID
    • Chargify Subdomain
    • Chargify Reference ID
    • Chargify CC Emails
    • Chargify Tax Exempt
  • Quick Save

  • Click on “Buttons”
  • Drag and drop the following buttons into the “Custom Buttons” section in the layout:
    • Create Subscription in Chargify
    • Create Customer in Chargify
    • Update Customer in Chargify
    • View Customer in Chargify
  • Save

Configure Contact Layout

  • Click on the Contacts tab
  • Select a Contact record by clicking on a Contact name in the list
  • Click “Edit Layout” on the contact detail page

  • In “Fields”, drag and drop a new “Section” into the layout:
    • Section name: Chargify
    • Display Section Header on:
      • Detail Page
      • Edit Page
    • 1 column
    • OK
  • Drag the following fields into the new Chargify section:
    • Chargify Customer ID
  • Quick Save

  • Click on “Buttons”
  • Drag and drop the following buttons into the “Custom Buttons” section in the layout:
    • Create Customer in Chargify
    • Update Customer in Chargify
    • View Customer in Chargify
  • Save

Configure Opportunity Layout

  • Click on Opportunities tab
  • Select an Opportunity by clicking on an Opportunity Name in the list
  • Click “Edit Layout” on the Opportunity detail page

Adding Total Price To Products

  • Click on the wrench icon for “Products” Related List properties
    • Add “Total Price” to the right column in the pop-up
    • OK
  • Quick Save

Adding Chargify Fields

  • In “Fields”, drag and drop a new “Section” into the layout:
    • Section name: Chargify
    • Display Section Header on:
      • Detail Page
      • Edit Page
    • 2 columns
    • OK
  • Drag the following fields into the new Chargify section:
    • Chargify Expires At
    • Chargify Next Assessment At
    • Chargify Payment Collection Method
    • Chargify Subscription Id
    • Chargify Total Revenue
    • Chargify Subscription State
    • Chargify Subdomain
    • Chargify Net Amount
    • Chargify Coupon Code
    • Chargify Coupon
    • Chargify Coupon Value
    • Chargify Coupon Counter (How many times the active coupon has been “used”)
    • Chargify Current Balance
    • Chargify Current Version
    • Chargify Last Product Change
    • Chargify Pending Cancellation
    • Chargify Canceled At
    • Chargify Current Product Revenue
  • Quick Save

  • Click on “Buttons”
  • Drag and drop the following buttons into the “Custom Buttons” section in the layout:
    • Create Subscription in Chargify
    • View Subscription in Chargify
  • Quick Save

Adding Chargify Actions

  • Select “Visualforce Pages”
  • Drag and drop a new “Section” into the layout:
    • Section name: Chargify Actions
    • Display Section Header on:
      • Detail Page
      • Edit Page
    • 1 column
    • OK
  • Drag the following field into the new Chargify Actions section:
    • ChargifyActionInline
  • Quick Save

Adding Transaction History

  • Select “Visualforce Pages”
  • Drag and drop a new “Section” into the layout:
    • Section name: Chargify Transactions
    • Display Section Header on:
      • Detail Page
      • Edit Page
    • 1 column
    • OK
  • Drag the following field into the new Chargify Transactions section:
    • SubscriptionTransactions
  • Quick Save

  • Click on the wrench icon of the SubscriptionTransactions section you just created:

  • Set the Width (in pixels or %) to 100% and Height (in pixels) to 400
    • Click OK
  • Quick Save

Adding Custom Fields

  • Select “Visualforce Pages”
  • Drag and drop a new “Section” into the layout:
    • Section name: Chargify Custom Fields
    • Display Section Header on:
      • Detail Page
      • Edit Page
    • 1 column
    • OK
  • Drag the following field into the new Chargify section:
    • ChargifyCustomFields
  • Quick Save

  • Click on the wrench icon of the ChargifyCustomFields section you just created:

  • Set the Width (in pixels or %) to 100% and Height (in pixels) to 600
    • Select “Show Scrollbars” checkbox
    • Click OK
  • Save

Configure Product Layout

  • Click on the Products tab
  • Select a Contact record by clicking on a Product name in the list
  • Click “Edit Layout” on the Product detail page

  • In “Fields”, drag and drop a new “Section” into the layout:
    • Section name: Chargify
    • Display Section Header on:
      • Detail Page
      • Edit Page
    • 2 columns
    • OK
  • Drag the following fields into the new Chargify section:
    • Chargify Created at
    • Chargify Accounting code
    • Chargify Id
    • Chargify Component Type
    • Chargify API Handle
    • Chargify Pricing Scheme
    • Chargify Product status
    • Chargify Price in cents
    • Chargify Interval
    • Chargify Interval unit
    • Chargify Product Family
    • Chargify Product Family Id
    • Chargify Product Version
  • Quick Save

  • Select “Related Lists”
  • Drag the following sections into the layout:
    • Product Version
    • Price Brackets
  • Quick Save

  • Click on the wrench icon for “Product Version” Related List properties:

  • Add the following items to the right column in the pop-up:
    • Version Number
    • Chargify Price In Cents
  • OK
  • Save

Webhook Configuration

Chargify webhooks are used to create and update Customer and Subscription records in Salesforce. The “Sites” feature is required to create a webhook endpoint within Salesforce, which is available in Salesforce Enterprise, Unlimited, and Developer accounts. The Sites feature is not available in Professional edition as an add-on.

Create A Force.com Domain

You may already have a Force.com Domain created in your account. If so, you can skip ahead to Create a Site.

  • Go to Setup -> Develop -> Sites
  • Check site domain availability (Example: my-company-name)
  • If available, select “Register my Force.com Domain”

Create A Site

  • Go to Setup -> Develop -> Sites
  • Click “New”

  • Populate the following fields:
    • Site Label (Example: Chargify Site Name)
    • Site Name (Example: Chargify_Site_Name)
    • Select Site Contact
    • Enable “Active” checkbox
    • Active Site Home Page: Unauthorized
    • Inactive Site Home Page: InMaintenance
    • Site Template: SiteTemplate
    • Clickjack Protection Level: Allow framing by the same origin only (recommended)
    • Enable Require Secure Connections (HTTPS)
    • Enable Access to the Support API
  • Save

Set Standard And Custom Object Permissions

  • Go to Setup -> Develop -> Sites
  • Click on the “Site Label” you created in the previous step

  • Select “Public Access Settings”
  • Choose “Edit”
  • Under “Standard Object Permissions”, enable all available checkboxes for the following:
    • Accounts
    • Contacts
    • Ideas
    • Leads
    • Opportunities
    • Price Books
    • Products
  • Under Custom Object Permissions”, enable all available checkboxes for the following:
    • Chargify Custom Fields
    • Chargify Logs
    • Chargify Settings
    • Coupons
    • Price Brackets
    • Product Families
    • Product Version
  • Save

  • Select “Enable Apex Class Access” link
  • Click “Edit”

  • Move “CHRGFY.UpdateFromWebhook” into the right column
  • Save

Configure Custom Settings

  • Go to Setup -> Develop -> Custom Settings
  • Select the “Webhook Configuration” label
  • Click “Manage”
  • Choose “New”
    • Enter the Name (Example: Company Name Webhooks)
    • Shared Key
      • Your Shared Key can be found by logging into your Chargify account and selecting “Edit” in your Site box

  • Subdomain (Your Chargify site subdomain)
    • If your Chargify subdomain is https://example.chargify.com, enter “example” into the subdomain field.
  • Save

In order to receive webhooks from multiple Chargify sites, Custom Settings need to be configured for each Chargify subdomain you plan to connect to your Salesforce account.

Enter Salesforce Webhook URL In Chargify

  • Go to Setup -> Develop -> Sites
  • Click on the “Site Label” you created

  • Copy the Site “Domain Name”

NOTE: If you have a “secure” domain available in your Salesforce account (example “chargify.force.com” and “chargify.secure.force.com”), always use the “secure” URL for the Chargify webhook configuration.

  • Login to Chargify and navigate to Settings > Webhooks
    • Select “Add New Endpoint”
    • Enable all Webhook Subscriptions by selecting “All On”
    • Enter https:// then the copied Domain Name in step 2 above and append with /services/apexrest/CHRGFY/ChargifyWebhook (Example: https://chargifyapp-developer-edition.ap2.force.com/services/apexrest/CHRGFY/ChargifyWebhook)
  • Save

In order to receive webhooks from multiple Chargify sites, webhook endpoints must be configured in each Chargify subdomain you plan to connect to your Salesforce account.

Create Public Group For Webhook Guest User

To avoid giving all Internal and External users Public read/write access to Opportunities and Accounts, you can assign Public Read/Write access to the Webhook Site Guest User only.

  • Go to Setup -> Manage Users -> Public Groups
  • Click “New”

  • Populate the following fields:
    • Label: “Site User”
    • Group Name: “Site_User”
    • In Search dropdown, select “Users”
    • Move the Site Guest User from “Available Members” to “Selected Members”
  • Save

Assign Sharing Settings To New Public Group

  • Go to Setup -> Security Controls -> Sharing Settings
  • Select “New” in “Opportunity Sharing Settings”

  • Populate the following fields:
    • Label: “Site User Opp Settings”
    • Rule Name: “Site_User_Opp_Settings”
    • Step 2, select “Based on record owner”
    • Step 3, select “Public Groups” and “All Internal Users”
    • Step 4, select “Public Groups” and “Site User” (Public Group you created above)
    • Step 5, select “Read/Write”
  • Save

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/Chargify Direct

  • 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.

  • 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.

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.

Matching Rules

Match Chargify Data to Existing Account, Contact & Opportunity

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:

  • 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.

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

  • 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.

  • 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.

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.

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 Accunt and Contact

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

  • 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

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.

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)

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.

  • 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.

  • 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

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.

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.

Updating Your Managed Package

You can view the version installed in your Salesforce account by going to Setup -> Build -> Installed Packages.

The most recent version of the managed package will always be available in the AppExchange listing.

  • Go to the Chargify for Salesforce AppExchange listing
  • Choose “Get It Now”
  • Login to your Salesforce account
  • Install into the appropriate environment
  • Agree to terms and Confirm
  • Install update for the appropriate users

You will be notified when new versions become available. The notifications will include release notes to indicate features that were added or removed, affects on custom or standard fields, as well as details about bug fixes and severity.

Uninstalling the Package

If you’d like to Unistall the Chargify for Salesforce managed package, you can do so at any time.

If your free trial has ended and you are paying for user licenses, please contact Chargify support to cancel any applicable license fees.

  • Go to Setup > Build > Installed Packages
  • Select “Uninstall”
  • Select “Yes, I want to uninstall this package and permanently delete all associated components”
  • Press “Uninstall”

Please note that all Chargify custom fields and values will be removed from your Accounts, Contacts and Opportunities.