API Reference

About Action-Based Impact API

Our mission at ShoppingGives is to help our clients create an impact with every action. Action-based Impact is an extremely versatile and flexible tool to make our mission real.

With the Action-based Impact API, you can define an action that your customers can take to generate a donation to any of our 1.8 million+ supported causes. The action can be anything you want!

  • User subscribes to your email list.
  • Attending an event.
  • Posting to social media.
  • Referring a friend to your products/services.
  • Filling out a survey.
  • Driving safely.
  • Walking to work.
  • Having a birthday or client relationship anniversary.

The list is endless because the action can be anything you want.

  1. You tell us which actions are eligible.
  2. You tell us when your customers take an eligible action. At the same time, you tell us who is getting a donation, for how much, and who is paying for it (you or your customer).
  3. Our donation rails ensure that 100% of the donation value goes to the cause(s) you chose. We provide all the reporting you need to know about your customers, their actions, and the causes they support.

It's that simple!

📘

Before Getting Started

Action-based Impact is an API-based product, so you'll need to know how to consume JSON-based HTTPS web services to utilize its capabilities thoroughly.

🚧

Action-based Impact is available to any Impact Partner client or above. Please contact your Account Manager if you would like to upgrade and utilize this and many other great features.

How do I get started?

  1. Contact us to receive your API key and your Store ID. If you already have a ShoppingGives API key and Store ID, great! You're all set!

  2. Consult the Creating Action-Base Donations API or our recipes for detailed technical information. Here's a quick primer so you get the gist:

Registering an "Action"

Let's say you run a canine wellness company and want to donate to the ASPCA (EIN: 13-1623829) any time a customer brings in their dog for a routine checkup. We'll register an action called "Routine Checkup". To do this, use the Action POST /action endpoint and provide a name and description for your action:

  • Name: "Routine Checkup"
  • Description: "The customer brought their pet in for a routine checkup."
    You'll also need to supply your API Key and Store ID in the header.

You just registered a new action in the Action-based Impact system. The action is "active" by default (meaning it can generate donations). You can de- and re-activate existing actions at any time using the PUT /action/{id}/deactivate and PUT /action/{id}/activate endpoints, respectively. You can get a list of all your registered actions and their id's using the GET /actions` endpoint. You can still report on deactivated actions, but you cannot use them to generate donations unless you re-activate them.

Generating a Donation from an Action

As soon as your action is active, you can use it to generate donations. For example, say you want to contribute $1.00 to the ASPCA whenever a customer completes a wellness check at one of your facilities. You have a scheduling system that tracks wellness visits and a way to report on those visits and wire them to HTTPS requests.

One day, your customer Austin Taranta (customer id C5382) completes a wellness check for his dog, Buddy. Seeing this in your schedule system as appointment #32912, you issue a request to the AbiConversion endpoint POST /. You provide the following information:

{
  "referenceId": "32912",
  "actionType": "Routine Checkup",
  "donationAmount": 1.00,
  "customerId": "C5382",
  "causeIds": "131623829",
  "donorType": "merchant",
  "customTags": "{ \"dogName\": \"Buddy\" }"
}

📣 Some things to note:

  • The Reference ID can be anything you want so long as it's a unique identifier in your systems. We'll provide this number to you in reporting so that you can correlate donations to objects in your system.

  • The Action Type can be either the exact string name of the action or the action id (GUID) that you can retrieve from the Action GET /actions endpoint.

  • The Donation Amount is the amount that you want to donate. It is represented in your account's default currency. If you're a United States client, your donation will be in USD. If you're unsure of your account's default currency, contact ShoppingGives, and we'll be happy to help!

  • The Customer ID is your identifier for your customer. This value is also provided back to you in reporting.

  • The Cause IDs is a comma-delimited string of EINs (up to 6) without dashes. In this case, we're only donating to a single cause: the ASPCA. So, we included their EIN with no dashes. If you include additional causes, the donation amount will be distributed equally between all the supplied causes.

  • The Donor Type is either "merchant" (you're funding the donation) or "consumer" (your customer is funding the donation). We invoice you either way, but you should select "consumer" if you're explicitly passing the donation cost to your consumer.

  • The Custom Tags field can contain whatever you want. We won't do anything with it except provide it verbatim in your reporting. This can be useful for your post-doc analytics. Please be sure the value you provide is properly escaped using backslashes.

You generated a donation! 🙌🏼

Reporting on your Donations from Actions

You can see your Action-based Impact donations alongside your other donations using the Shopping Gives Impact Portal's reporting functionality. Donations that you funded will be in the "Merchant Donations" tab. Your consumer's funded donations will be in the "Consumer Donations" tab. The "Source" will be "Action-based Impact" in both cases. When you export your reporting data, you'll be able to see all of the info you used to generate the donation, including any "Custom Tags" you provided.