Overview

ChangeUp for Charity offers merchants the ability to allow their customers to make charitable donations using three type options: 1) fixed, 2) percentage of the order total, and 3) round-up to the next whole monetary value.  How the donation amount is calculated is variable based on several configurable options.  These options can be configured on the ChangeUp dashboard; functionality that is made possible by the Business Manager cartridge included in the distribution.  There are also several configurations to allow a customer to choose a charity of their own liking or guide them to one of your more preferred charitable organizations.

Once the cartridge is installed, merchants will choose a default charity.  This is to ensure that if there is no customer interaction that their order’s donation will be given to a charity that the merchant deems important to them.  Several featured organizations may be selected in the configuration as well, which are displayed to the user on the order confirmation page to select from.  Within the dashboard, you can configure customers to use the same search you will use to find your default and featured charities.  If enabled, customers can search for charities of their liking.

Installation

This section describes the installation of the cartridge which includes several tasks:

  • Data import
  • ChangeUp cartridge integration into merchant code base
  • Setup and configuration

Compatibility

The ChangeUp for Charity cartridge is built using and is compatible with SFRA architecture.

Data Import

Locate the metadata > changeup_import directory within the distribution.  We’re going to have to make a few changes to the data files within.

1) Rename the metadata > changeup_import > sites > [MERCHANT-SITE-ID] directory to be the ID of the site the cartridge is being installed for.

  • If the site is assigned to a shared library, open library.xml for editing and in the primary <library> node, add the attribute library-id, making its value the ID of the shared library to import the content assets into.
<library xmlns=“http://www.demandware.com/xml/impex/library/2006-10-31" library-id=“site-lib-id”>

2) Open metadata > changeup_import > inventory-lists > inventory.xml for editing.  Modify the list-id value in the <header> node to be the ID of the inventory list the site is assigned to.

<header list-id="MERCHANT-LIST-ID">
NOTICE:  If your recurring inventory import is using the REPLACE method, you will need to include the donation product’s inventory within that feed so it is always present.  For reference of the inventory setup, look to the inventory.xml file included in the distribution.

3) Open metadata > changeup_import > catalogs > storefront-catalog > catalog.xml for editing. Modify the catalog-id value in the <catalog> node to be the ID of the storefront catalog the site is using for categorization.

<catalog xmlns="http://www.demandware.com/xml/impex/catalog/2006-10-31" catalog-id="MERCHANT-STOREFRONT-CATALOG-ID">
NOTICE:  If your recurring storefront catalog import is using the REPLACE method, you will need to include the donation product within that feed so it is always present.  For reference of the storefront catalog setup, look to the catalog.xml file under the storefront-catalog directory included in the distribution.

4) Open metadata > changeup_import > jobs.xml for editing.  Modify the site-id value in the context 

<context site-id="[MERCHANT_SITE_ID]"/>

5) Now create a zip file from the changeup_import directory, ensuring the zip file is named changeup_import.zip

6) On the Commerce Cloud instance you are installing the data on, navigate to Administration > Site Development > Site Import & Export and upload the changeup_import.zip file you created in the last step.

7) Import the data. Select the changeup_import.zip archive and click the Import button.

 

Code Integration

Templates

There are two templates which must be integrated into your storefront templates:

  • int_changeup_sfra/cartridge/templates/default/changeUp/checkout/checkout.isml
  • int_changeup_sfra/cartridge/templates/default/changeUp/checkout/confirmation.isml

These files need to be included into these existing SFRA files, respectively:

  • [app_storefront_overlay]/cartridge/templates/[locale]/checkout/checkout.isml
  • [app_storefront_overlay]/cartridge/templates/[locale]/checkout/confirmation/confirmation.isml
NOTICE: 
[app_storefront_overlay] refers to the storefront cartridge where app_storefront_base templates are overridden, so that base templates remain unaltered.  This can vary from merchant to merchant, and you may need to copy these files from the app_storefront_base cartridge if you have not already.
[locale] refers to the locale directory, which is typically “default”, but may be different depending on your architecture.

[app_storefront_overlay]/cartridge/templates/[locale]/checkout/checkout.isml

NOTICE: 
The exact location to include this template is up to the merchant and their desired checkout user experience.  This example renders the donation module at the bottom of the right column, below the order summary.  For example, you may choose to include it on the left side, in the billing area.  The donation UI will function independent of any other checkout elements and forms, and therefore can be included anywhere. Below is a screen shot of the reference placement.

 

[app_storefront_overlay]/cartridge/templates/[locale]/checkout/confirmation/confirmation.isml

NOTICE: 
The exact location to include this template is up to the merchant and their desired checkout user experience.  This example renders the charity selection module above the order confirmation.  The charity selection UI will function independent of any other elements and forms, and therefore can be included anywhere. Below is a screen shot of the reference placement.

 

 

Script

There is one small change needed to the calculateProductPrices() function, in the scripts/hooks/cart/calculate.js file, or whichever file you use for the dw.order.calculate hook.  Because the donation line item does not have a pricebook price, you must handle the product id explicitly.  Here is an example applied to the default SFRA script. On line 125, you need to replace

if (!productLineItem.catalogProduct) 

with

if (!productLineItem.catalogProduct || productLineItem.productID == ‘changeup-donation’)

 

 

Cartridge Paths and Permissions

bm_changeup

  1. Put a reference to the bm_changeup cartridge in the Business Manager cartridge path.

int_changeup_sfra

  1. Put a reference to the int_changeup_sfra cartridge in the cartridge path of the site(s) the cartridge will be enabled for.
    1. Ensure the reference is to the left of the SFRA base cartridge’s entry on the path.
  2. Put a reference to the int_changeup_sfra cartridge in the Business Manager cartridge path.

Business Manager Module Permissions

  1. Navigate to Administration > Organization > Roles & Permissions, click the role that will be using the dashboard to configure ChangeUp. (Administrator for example)
  2. Click on the Business Manager Module tab
  3. In the Select Context modal, select the sites that will be using ChangeUp, and click Apply.
  4. Select the Write checkbox for the ChangeUp > Dashboard module, and click Update.

Setup and Configuration

Site Preferences

API Key

An API key is required to send requests to the ChangeUp API.  Once you obtain this key, you will need to place it in the site preferences for the site the cartridge is being installed for.

  1. Navigate to Merchant Tools > Site Preferences > Custom Preferences > ChangeUp
  2. Enter the API key in the field next to ChangeUp API Key
  3. Click Save.

Enable ChangeUp

To enable the cartridge’s functionality on the storefront, you must enable a site preference setting:

  1. Navigate to Merchant Tools > Site Preferences > Custom Preferences > ChangeUp
  2. Choose Yes in the drop-down field next to ChangeUp Enabled.
  3. Click Save.

ChangeUp Configuration

Navigate to the ChangeUp dashboard to start configuring the options available.  Merchant Tools > ChangeUp > Dashboard

Troubleshooting

NOTE - If no response from ChangeUp Charity API, then no charities will be will listed or set as default.

Charity Search

The search input on the dashboard will help the merchant search charities and set them as their default and featured charities.  To search charities, type three or more characters in the search input.  After a charity is selected from the results, buttons will appear below the search input that will allow you to set the default charity or add the charity to the list of featured charities.

Charity search controls to set the selected charity as default or featured.

Default and Featured Charities

The dashboard displays the selected/saved default and featured charities.  These charities are presented to the customer on their order confirmation page.  The display of these charities can be seen in the storefront charity selector section of this document.

 

Donation Type

Who Makes the Donation?

The donation type Actor is the entity that will be monetarily responsible for the donation.  There are three actor values to choose from based on the merchant’s preference:

  • Merchant — The merchant is solely responsible for funding the donation.
  • Customer — The customer is solely responsible for funding the donation.
  • Merchant/Customer Match — The merchant will match the donation amount of the customer and both are responsible for funding their donation amount.

What's the Donation Format?

The donation type Option is the method used to calculate the monetary donation amount.  There are three options available for the merchant to choose from:

  • Fixed — A fixed donation amount can be set within the Fixed Amount input. (The Fixed Amount input field is displayed when this option is selected).
  • Percentage — The donation amount will be calculated as a percentage of the adjusted merchandise total (subtotal). The percent amount can be set within the Percentage Amount input. (The Percentage Amount input field is displayed when this option is selected).
  • Round-up — The donation amount will be calculated as round-up of the monetary value to the right of the decimal point (i.e. USD: cents). This round-up is calculated using the order total and will always cause the order total to calculate to a whole monetary value (e.g. $39.49 will round to $40.00 and the donation amount would calculate to $0.51).

Donation Display Type

The donation display type offers the ability to show the donation amount as a monetary value or a percentage of the order.  This only affects the way the amount is rendered to the user and has nothing to do with the calculation of the donation amount.

  • Actual Amount — Display the donation amount as a monetary value.
  • Percentage — Display the donation amount as a percentage of the order total.

Total Donations Display

The total donations display offers the ability to display the total donations made to date through your ChangeUp account, across all customers and charities.  Additionally, you have the ability to offset the total with an amount of your choosing, to reflect donations your organization has made outside of ChangeUp.

  • Enable total donations display – Toggle the display of total donations on the donation widget.
  • Starting display value – A starting value added to the displayed total donation amount.
  • Minimum display threshold – The mimimum value of total donations before displayed in the widget. This threshold includes the starting display value, so the total donations will display when (Start Value + ChangeUp total) > Minimum Display Threshold.

 

Functionality

Donation Confirmation

The donation confirmation is a widget that displays on checkout.  It provides the following functionality:

  • Agreement to donate — For donation types Customer and Merchant/Customer Match, the donation confirmation element provides a checkbox that allows the user to decide whether to agree to donate or not.
  • Charity Logos – If the default charity is the only charity saved on the dashboard, and no featured charities have been saved, then the default charity’s logo will be shown on the left side of the widget (and to the right of the checkbox when present). If at least one featured charity has been saved in addition to the default charity, up to 5 logos will display in a row at the bottom of the widget.
  • Total donations – If the total donations display toggle has been enabled on the dashboard, and the minimum threshold is less than the starting value plus the real time total, then a message “$x.xx donated to date.” is shown.
  • User Messaging – Depending on the dashboard settings, including the number of charities, the donation actor and option, and the customer search toggle, a dynamic set of messages are displayed to the customer. All of the text for this area is found in the int_changeup_sfra/cartridge/templates/resources/changeup.properties file, and can be customized or translated during integration.
  • Donation amount — The amount calculated for the donation is shown on the right side of the element.

 

When the actor is configured to be the Merchant on the dashboard, no monetary changes are made to the order because the donation amount will be funded by the merchant.  When the actor is configured to be the Customer or Customer/Merchant Match, the customer will be presented with a checkbox on the widget that allows them to consent to funding the donation.  When the checkbox is checked on or off, the donation amount will be added to the order, or removed.  The donation is applied to the cart as a Product Line Item, with dynamic pricing, based on the Donation Actor, Donation Option, and cart totals.

NOTE: Because a donation product is used to affect monetary change for the donation amount, the product has the potential for displaying to the customer within the product line item summary on checkout and confirmation page.  If the checkout page is reloaded for instance, the line item will display in the summary without a custom approach to hide it.  It is up to the merchant whether they want to hide this line item or not.  To hide, custom code will be needed in the template to look for the donation product’s ID, place identifying attributes (e.g. class or id) on the parent element of the line item, then use CSS to hide it.  Keep in mind that any product counts displayed will also display the number of products plus one for the donation product unless custom code is used to affect this.

Donation Confirmation Examples:

 

 

Donation Reporting

ChangeUp requires donation data reporting after the payment of the order has been captured.  Capturing payment usually happens one of two places within an organization: 1) on a backend system (OMS/ERP), or 2) on the Commerce Cloud platform itself.  Regardless of the system that captures on the payment, the request structure is the same.  The difference will be whether you will inject the reporting script into the capture process on the platform, or the backend system (OMS/ERP) calls the exposed route to initialize the reporting process.

{
     "orders": [
        {
            "order_id": "00002004"
        },  
        {
            "order_id": "00002005"
        }
     ]
}

Donation reporting JSON request

Backend System (OMS/ERP) Request

If the capture process occurs on a backend system that is not the Commerce Cloud platform, the merchant must make a request to their Commerce Cloud instance through the route ChangeUp-DonationReporting (this route can be aliased in Business Manager to shorten the URI).  The request details are as follows:

  • Method — POST
  • Headers — Content-Type: application/json
  • Body — Use the structure defined above

 

 

Commerce Cloud Injection

The merchant should point you to where in their code base they are capturing on order payments. It is within this code that you will need to construct an Object resembling the request example above from the orders that are being processed.  To make the process more efficient, you could pre-flight a check on each order’s custom attribute changeupAgreedToDonate to see if it should be sent to the donation reporting code.  After you have constructed the object, inject this line of code and pass the object to the constructor (data is the object in the example).  The result can be used to throw errors or ensure that the capture reporting completed successfully.

var result = require('~/cartridge/scripts/changeup/services/captureReporting')(data);

 

Testing

Dashboard

Test the functionality of the dashboard within the Business Manager module.

  • Search — Ensure the charity search works correctly by delivering search results after 3 characters are typed into the input.
  • Save Configuration — Save a configuration and reload the dashboard to confirm that the settings have been saved.

 

Donation Confirmation Widget

Test the functionality of the donation confirmation widget on checkout.

  • Donation Type | Actor — Check that as each actor is set, the donation confirmation widget displays the correct layout and copy from the associated content assets.
  • Donation Type | Option — Check that as each option is set, the donation is calculating correctly (refer to Donation Type: Option section for details on calculations).
  • Agreed to Donate — For actors Customer and Customer/Merchant Match, ensure when checking the box to agree to donate that the order total is recalculated; adding and removing the donation amount respectively.

 

Charity Selector Widget

Test the functionality of the charity selector widget on order confirmation.

  • Displays Correctly — The charity selection widget should display only if the customer has checked the box on the donation confirmation widget (applies to when donation type actor is set to Customer or Customer/Merchant Match). Also, check that the copy from the content assets are correct.
  • Search — Ensure the charity search works correctly by delivering search results after 3 characters are typed into the input.
  • Send It — Ensure the Send It action performs correctly and that the correct messaging is displayed after the action.
  • Timer End — Ensure the timer ending action performs correctly and that the correct messaging is displayed after the timer counts down (10 minutes after the confirmation page load the timer should trigger its actions).

 

ChangeUp Custom Order Attributes

Check the custom attributes on the test orders placed while testing the different configurations.  Ensure that the donation amounts are applied to the correct attribute (customer and/or merchant).

 

Donation Reporting

Within the code in the distribution, navigate to cartridges > int_changeup_sfra > cartridge > tests > endpoints.txt.  Using VS Code, install the REST Client for Visual Studio Code extension referenced at the top of the file.  Read the documentation on how to trigger a request.  Replace [your-instance-url.demandware.net] with the domain of the instance you are testing on.  Trigger the request with a JSON request using orders that you have created testing the ChangeUp cartridge.  Once this is complete, the order should have confirmation UUIDS within the ChangeUp custom attribute group.  This confirms the necessary reporting data has been transmitted.

 

Failover

If the ChangeUp API experiences a failure, users will be given the option of donating only to the default selected charity.

 

Known Issues

Array.prototype.every = function (callback) {
     const { length } = this;
     
     for (let index = 0; index < length; index += 1) {
      const value = this[index];

     if (!callback(value, index, this)) {
      return false;
     }
    }

    return true;
   };

If for some reason the client-side Javascript needs to be recompiled for the bm_changeup cartridge, there is a code update needed in an autocomplete.js file node_modules > autocomplete.js > zepto.js.  This update needs to go in on line 7 of the aforementioned file.  This is due to Business Manager utilizing the Prototype.js library that overrides the default functionality of the Array.prototype.every function.  This leads to client-side script errors when autocomplete.js tries to initialize its DOM elements.

 

User Interface Design

The UI design shown above is for demonstration purposes only. Merchants may custom-design the ChangeUp endpoints to match their own eCommerce style and design.