Overview

This document describes the steps for a merchant to implement the ChangeUp donation API as a donate-at-checkout widget in their shopping cart. ChangeUp makes this process easy by providing an API as well as a hosted admin dashboard that merchants can use to configure their checkout experience.

The main tasks involved in this implementation are:

  • Configure your donation experience using the hosted admin dashboard
  • Make API calls to fetch the config that was generated by the admin dashboard
  • Display the donation in your shopping cart
  • (optional) Display a charity selector on your confirmation page
  • Send the donation data to the ChangeUp API

API Access

Your ChangeUp account manager will provide you with an API key for the staging environment, and you can view the API documentation here.

Once the ChangeUp team has confirmed the functionality of your API implementation by reviewing your shopping cart experience and reviewing the donation data that was sent to our staging environment, you will receive a production API key.

Configuration

Your ChangeUp account manager will provide you with a link to your admin dashboard as well as credentials to log in. The dashboard will allow you to configure your donate-at-checkout in a variety of ways.

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. Donations can be made by the merchant or by the customer, or customer donations can be matched by the merchant. Charities can be searched for and selected, up to a maximum of 5. Finally, text can be configured in the dashboard to display in your shopping cart or confirmation page. 

Reporting and Analytics

By clicking the “Reports” button, you will be able to see charts displaying the donations that have been made by you or your customers. This data will update each time you send donation data to the ChangeUp API.

Fetching the Config Data

The admin dashboard generates a config object that is stored by ChangeUp and made available via an API call to the endpoint:GET /v2/organization/ui-config

You will use this config data to render your in-cart donation experience. Additionally, the config data will include the data for your selected charities. You can use the names, logo URLs, and potentially other charity data to build a rich user experience for your customers.

Your Shopping Cart

Your in-cart donation experience is highly flexible and should be tailored to your brand, but there are a few best practices that ChangeUp encourages merchants to follow in order to provide a best-in-class donation experience. More details can be found in this help article, but the general rules of thumb are provided in this sample image:

If you have any questions regarding your in-cart user experience, please do not hesitate to contact ChangeUp and we will be happy to help.

Confirmation Page

If you display multiple charities in your shopping cart, we recommend that you give your customer the option to select which charity should receive the donation with a charity selector widget on your purchase confirmation page. We consider this a best practice because it does not distract the customer from completing the purchase, and still gives them an opportunity to engage with your donation experience by selecting a charity after the purchase has been completed.

A good charity selector widget is embedded near the top of your purchase confirmation page and clearly explains that the user has the option to select which charity will receive the donation. If the user does not select a charity, we recommend making the donation to the default charity that you selected in your admin dashboard.

Sending Donation Data to ChangeUp

Donation data is sent to ChangeUp using the following endpoint:POST /v2/donation

ChangeUp’s donate-at-checkout service does not interfere with the flow of your checkout process because the donation data is sent to ChangeUp after the customer has completed the purchase.

Donations can be sent in batches, and the recommended best-practice is to store the donation data until your product has shipped, and then send the donation data to ChangeUp once shipping is confirmed. This reduces the complexity of canceled orders because once a donation has been recorded with ChangeUp, refunds are not an option. 

It is common practice to send batches of donations to ChangeUp on an interval that is aligned with your purchase volume so that the number of donations in a batch does not exceed 100 donations. This is commonly done on an interval of 1 to 5 minutes, but can be up to an hour for low volume merchants.

Donation Invoicing

ChangeUp will provide a donation report on a monthly basis in order to collect the donated funds and distribute them to your selected charities. Your ChangeUp account manager will provide you with a link where you can sign up for automated bank transfers for the monthly donation amount. ChangeUp handles all funds distribution and reconciliation. 

QA

Before going live, the ChangeUp team will need to confirm the functionality of your implementation by taking a look at your shopping cart and confirmation page as well as the donation data you sent to our API. 

More information on our QA process can be found in this help article. Feel free to get in touch if you have questions!

Contact Us

Get in touch to learn more about how to implement ChangeUp in your checkout process!

hello@changupforcharity.com