Intended audience and subject matter

This guide is intended for customers and partners who implement client applications for the RaiseNow API in the context of face-to-face donations with and without mobile point of sales devices. Please note, that the following is supported for Salesforce enhanced recurring donations only. 

The goal of this article is to highlight essential parameters of the RaiseNow ontology in the context of installment schedules and dunning processes for recurring donations. This article should 

• provide a semantic interpretation for these parameters and
• describe how these are translated when objects are created or updated in Salesforce based on interactions with the RaiseNow API.

With regards to direct debit recurring donations and in conjunction with dunning processes implemented in Salesforce, what seems at first glance a trivial combination of a few parameters quickly becomes a complex problem and may result in creating recurring donations and payments that must be fixed manually to avoid missing charges or even charging donors twice for the same installment if the recurring donation is not created according the the guidelines outlined here. 

Important parameters and their interpretation

The following parameters and their combination are essential when creating subscriptions via the RaiseNow API.

"planned_effective_from": "YYYY-MM-DD"

The date on which RaiseNow will start executing charges according to the charge interval definition on the RaiseNow subscription. This value will also be used as the value for npsp__StartDate__c on Salesforce's recurring donation object. 

"recurring_interval": "15 * *",

The charge interval definition on the subscription. This is a value in the Unix cron format without minutes and hours. The above example defines a charge interval for the 15th day of every month of every year.

RaiseNow will execute charges for subscriptions when the date specified in planned_effective_from has been reached and the cron expression defined in recurring_interval evaluates to true. 

Based on planned_effective_from and recurring_interval RaiseNow will set the following values for the following fields on the recurring donation in Salesforce: 

• npsp__InstallmentFrequency__c
• npsp__Day_of_Month__c
• npe03__Installment_Period__c
• npsp__StartDate__c (Effective Date) 

"crm_contract_effective_date": "YYYY-MM-DD"

Use this parameter to directly set the npsp__StartDate__c (effective date) of the recurring donation in Salesforce superseeding the values calculated by RaiseNow. This is applicable on creating the subscription only.  

Use this field to specify the effective date in Salesforce and calculate due installments before an eventual charge execution via RaiseNow on creating the inital subscription. For example, when direct debit contract verification is mandatory and requires backoffice processing time, this allows for defining due installments based on the signature date of the contract for retrospective collection based on the opportunities generated in Salesforce after successful contract verification.

Example:

• You have created a subscription, specifying the current date as crm_contract_effective_date.
• Due to the pending contract verification you cannot start collection at the present time. 
• The first opportunity for the recurring donation in salesforce will still be created with the current date as closed date. 
• At an unspecified time in the future the contract is verified. Collection can now be triggered for the opportunity with a past Closed Date from within Salesforce. 

Please note, RaiseNow does not automatically execute charges retrospectively. Leverage Salesforce flow to automate this process on activation of the recurring donation. 

Considerations for parameter combination

Charge execution by RaiseNow will depend solely on the definition of the recurring_interval parameter. If you have chosen to set crm_contract_effective_date separately, you must ensure that this matches the defined recurring_interval definition with regards to the day of the month. It makes sense to set these parameters according to your planned collection configuration in Salesforce. Assuming you have configured Salesforce for direct debit collection initiation on the 15th and the 25th of the given month, the following combination would be recommended: 

Valid example: 

• Assuming: today <= 14 April 2022:

"crm_contract_effective_date": "2022-04-15",
"recurring_interval": "15 * *",

• Assuming: 15 <= today <= 24 April 2022:

"crm_contract_effective_date": "2022-04-25",
"recurring_interval": "25 * *",

• Once 25 of April 2022 has been reached, rinse and repeat for May. 

The day specified for recurring_interval and crm_contract_effective_date must match. Else, the calculated installment schedule in Salesforce will not match the actual charge execution by RaiseNow. 

If you do not need crm_contract_effective_date but use planned_effective_from the same rule applies. For example: 

• Assuming: 15 <= today <= 24 April 2022:

"planned_effective_from": "2022-04-25",
"recurring_interval": "25 * *",

• Assuming: 25 April <= today <= 14 May 2022:

"planned_effective_from": "2022-05-15",
"recurring_interval": "15 * *",

Please note that planned_effective_from & crm_contract_effective_date are mutually exclusive and should not be used in the same call. 

Examples

For all below examples we will assume monthly charges and an initial date of 1. April 2022. We will also assume direct debit collections on the 15th and the 25th of the given month. 

Creation of recurring donation via RaiseNow with subsequent activation after contract verification - no support for mobile point of sales (mpos)

Create the initial subscription in RaiseNow. This will create a lapsed recurring donation in Salesforce with an npsp__StartDate__c for 15. April 2022. Salesforce will automatically create the first opportunity with a close date for 15 April 2022. 

// POST /subscriptions
{
....,
    "timezone": "Europe/Zurich",
    "recurring_interval": "15 * *",
    "status": "pending",
    "raisenow_parameters": {
    "fundraising_automation": {
        "crm_contract_effective_date": "2022-04-15"
    },
...
}

Assuming a backoffice process for contract verification is completed, you want to update the subscription in RaiseNow by using a PATCH request. For example attaching contract documents. Note that these changes will only be propagated to Salesforce on a later activation of the subscription.

// PATCH /subscriptions/{subscription-uuid}
{
     "custom_parameters": {
         "campaign_id": "7013X000002FLLhQAO"
     },
     "raisenow_parameters": {
        "fundraising_automation": {
            "marketing_location": "F2F AG00001",
            "contract_document_identifier": "azx-1be",
            "contract_document_url": "http://some-url/some-file.pdf"
        }
    }
}

These optional parameters support providing additional information when updating the RaiseNow__Subscription__c or RaiseNow__Direct_Debit_Mandate__c object in Salesforce: 

• marketing_location: Optional parameter to provide a location of acquisition. 
• contract_document_identifier: Optional parameter to provide an identifier for a physical copy of your contract document, for example in your document management system. 
• contract_document_url: Optional parameter to allow for pushing a copy of that contract document directly to Salesforce. You must whitelist the target url in the configuration of the RaiseNow integration for Salesforce. 

Now activate the subscription. The activation will automatically be propagated to the recurring donation in Salesforce. 

POST /subscriptions/{subscription-uuid}/activate

As discussed above, if the activation is executed after 15 April, RaiseNow will not charge that subscription retrospectively. 

Creation of recurring donation via RaiseNow with subsequent activation after contract verification with mpos support

Create the initial subscription in RaiseNow as above. 

// POST /subscriptions
{
....,
    "timezone": "Europe/Zurich",
    "recurring_interval": "15 * *",
    "status": "pending",
    "raisenow_parameters": {
    "fundraising_automation": {
        "crm_contract_effective_date": "2022-04-15"
    },
...
}

Now assuming we execute a successful mpos payment for the contract by adding 

"stored_rnw_subscription_id" : {subscription-uuid}

as a pramaeter to our mpos payment. As the RaiseNow subscription engine is not aware that this was the initial payment we have to prevent RaiseNow from executing the initial charge. We do this by adding a planned_effective_from date to the subscription. This should now be set to the date of the second installment:

// PATCH /subscriptions/{subscription-uuid}
{
    "planned_effective_from": "2022-05-15"
}

Now activate the subscription. This will automatically activate the recurring donation in Salesforce as well. Though the effective date on the recurring donation will now be updated, the installment schedule will not be changed. 

POST /subscriptions/{subscription-uuid}/activate

However, RaiseNow will now skip the initial collection on the 15. April and instead, start charging the subscription on 15. May.