Skip to content

Magento 2 Donations Suite Manual

Donations Suite Cover

Introduction

Magento 2 Donations Suite is the extension that makes it possible to accept online donations and support non-profits and charities you care about. Out of the box, Magento 2 doesn’t allow to add such order surcharges.

Requirements and installation

Donations Suite supports Open source (Community), Commerce (Enterprise) editions and Commerce cloud. The current version of the Magento installed on your website can be found in the lower right corner of any backend page.

Donations Suite has 3 separate ways of installation:

1) Copy the code (ready-to-paste package);
2) Use MageWorx Repository;
3) Use local Composer.

Extension configuration

Backend setup

The main extension’s settings can be found under STORES ⟶ Configuration ⟶ MAGEWORX ⟶ Donations.

Mageworx Donations Settings Mageworx Donations Settings Mageworx Donations Settings

  • Accept Donations enables / disbales the entire donations functionality in the store.

  • Enable Cart Donations adds the donations box to the shopping cart page. If disabled, the donations functionality will be disabled in the cart page on the front-end. It is possible to add donations via the backend though.

  • Enable donations in Admin Orders enables/disables the possibility to add donations from the backend.

  • Minimum Donation specifies the minimal value of the allowed donations. This will be shown on the frontend as well.

Note

Please bear in mind that this value is for the frontend only. For the orders with donations that are being created in the backend, it won't be counted.

  • Default Description allows to set the default text of the donation box, shown on the front-end.

  • Donation Amount Placeholder sets the placeholder (default text, which is shown inside the input field) for the donation amount field if the custom donation amounts are allowed: Mageworx Donations Settings

  • Default Organization allows you to choose the default charity, which will be pre-selected on the front-end if the charity functionality is enabled.

  • Show Predefined Amounts allows you to add the predefined donation amounts available for your customers. Below this field the store owner can add these values one by one.

  • Enable Donation Custom Amount allows you to enable the feature of custom donation amounts. If enabled, your customers will be able to specify custom donation amounts on the front-end.

  • Predefined amounts allows you to add the predefined donation amounts available for your customers.

Example

This is the way how these settings can be combined to show the donations on the frontend. The predefined amounts are shown in the dropdown menu. If Custom Amount is selected, the client can specify the desired value. The donation placeholder text (Enter your donation in this case) is shown on this box. Mageworx Donations Settings

  • Enable Round Up Donation enables the round-up functionality.

Example

It provides the possibility to add some small donation amounts, calculated as round-up of the order total to the full price. In case the user's subtotal has the decimal part (like $20.40), this setting will allow to add the roundup (60 cents) to the donation.

If the subtotal doesn't have decimal part, the 'round-up' feature will add $1.

The round-up amount is added to the selected charity (if this feature is enabled).

Mageworx Donations Settings

  • Donations RoundUp Message set the message, which is shown near the 'Round-up' check-box on the front-end. You can use the following variables here: %roundupamount% - inputs the rounded amount; %charity% - inputs the selected organization.

  • Enable Gift Aid Donations enables the Gift Aid functionality.

  • Gift Aid confirmation message set the confirmation notice required to be compliant with Gift Aid. See the Gift Aid section for more details.

Track donations

The extension gives you the ability to see all orders with the donations on a single page. To see all orders with donations, go to SALES ⟶ MageWorx Donations ⟶ Donations. The grid has the "Donation amount" and the "Organization" column to display the added donation amount and the selected organization/charity. The orders grid is available for each organization as well.

Manage charities

To add or edit the organization / charities section, go to SALES ⟶ MageWorx Donations ⟶ Organizations.

Mageworx Donations Charity Setup

To add the new Charity, click the Add New Organization button.

Mageworx Donations Charity Setup

Under these settings you can specify the Name of the charity and its Description, upload an Image (logo), define the Sort Order and the Status of this charity.

Name, Description and the Image will be shown on the frontend. The sort order provdes the position of this charity.

The "Orders" section displays all orders with the donations for a certain charity:

Mageworx Donations Charity Setup

Donations for back-end orders

You can also add the donation to the orders, created in the back-end (add the products to the order first):

Mageworx Donations Backend

When added, it will be shown in the order summary

Mageworx Donations Backend

Frontend experience

On frontend, the donations box is shown in the cart side bar. Please check the image below to see how the cart block looks like if all features are enabled:

Mageworx Donations Frontend Cart

Themes compatibility

The extension is compatible with Magento 2 Luma, Porto, Ultimo, Amasty Jet themes by default. If you have any issues with compatibility with any other 3rd party themes, please drop us a line and we will be happy to assist.

Gift Aid

Gift Aid is a tax relief allowing UK charities to reclaim an extra 25% in tax on every eligible donation made by a UK taxpayer. See more details on JustGiving and on Gov.uk.

The Donations Suite extension allows you to collect the donataions compliant with Gift Aid. You can enable the Gift Aid feature in the extension configuration. See the Back-end setup section.

Once the Gift Aid is enabled, the "Gift Aid" check-box will appear on the front-end. If your customers will choose it, they will have to select another check-box to confirm they are UK taxpayers. Once it is confirmed, the new field to enter their UK address will appear.

All these details are stored in the order and you can see these columns in Magento 2 native orders grid (Sales ⟶ Orders).

These columns are also added to the orders export feature in order to easily export all orders with Gift Aid.

PWA themes

The extension out of the box has the integrations with the following PWA themes:

  • Magento 2 Venia

Note

The free compatibility addon must be installed from https://github.com/mageworx/mageworx-donations-veniapwa

Hyvä themes

The extension out of the box has the integrations with Hyvä themes:

Note

The free compatibility addons must be installed. See this link for more details.

GraphQL API

The GraphQL API is added by the free DonationsGraphQl addon.

1. mwDonationsInfo query returns the information about donations

Syntax

mwDonationsInfo: MwDonationsInfo

The MwDonationsInfo object may contain the following attributes:

min_value: Float @doc(description: "Minimum donation amount")
default_description: String @doc(description: "Donation default description")
amount_placeholder: String @doc(description: "Donation amount placeholder")
default_charity_id: Int @doc(description: "Default organization")
predefined_values: [Float] @doc(description: "Predefined donation amounts")
allow_round_up: Boolean @doc(description: "Allow Round Up Donation")
enable_round_up_by_default: Boolean @doc(description: "Enable Round Up by default")
is_gift_aid_allowed: Boolean @doc(description: "Indicates if gift aid donations are allowed")
gift_aid_message: String @doc(description: "Gift Aid confirmation message")
charities: [MwCharity] @doc(description: "An array of Charities")

The MwCharity object may contain the following attributes:

id: Int @doc(description: "Charity ID")
name: String @doc(description: "Charity name")
description: String @doc(description: "Charity description")
sort_order: Int @doc(description: "Sort Order")

Request:

{
    mwDonationsInfo {
        min_value
        default_description
        amount_placeholder
        default_charity_id
        predefined_values
        allow_round_up
        enable_round_up_by_default
        is_gift_aid_allowed
        gift_aid_message
        charities {
            id
            name
            description
            sort_order
        }
    }
}

Response:

{
    "data": {
        "mwDonationsInfo": {
            "min_value": 10,
            "default_description": "Default Description: Default text of the donation box, shown on the front-end",
            "amount_placeholder": "Enter your donation",
            "default_charity_id": 3,
            "predefined_values": [
                15,
                20,
                25
            ],
            "allow_round_up": true,
            "enable_round_up_by_default": true,
            "is_gift_aid_allowed": true,
            "gift_aid_message": "I confirm I'm a UK taxpayer.",
            "charities": [
                {
                    "id": 2,
                    "name": "Don Org 1 - def_st_v - name",
                    "description": "Don Org 1 - def_st_v - descr",
                    "sort_order": 0
                },
                {
                    "id": 3,
                    "name": "test 2",
                    "description": "Description for test 2",
                    "sort_order": 0
                }
            ]
        }
    }
}

2. The addMwDonationToCart mutation is used to add a donation to the shopping cart.

Syntax

addMwDonationToCart(input: AddMwDonationToCartInput): AddMwDonationToCartOutput

The AddMwDonationToCartInput object may contain the following attributes:

cart_id: String! @doc(description:"The unique ID that identifies the customer's cart")
charity_id: Int @doc(description: "Charity ID")
amount: Float @doc(description: "Donation amount")
round_up: Boolean @doc(description: "Round up")
uk_confirm: Boolean @doc(description: "Confirms UK Taxpayer")
gift_aid_address: String @doc(description: "UK address")

The AddMwDonationToCartOutput object contains the Cart object. We add the new attribute added_mw_donation to the Cart object.

added_mw_donation: AddedMwDonation @doc(description:"Added donation")

The AddedMwDonation object may contain the following attributes:

charity_id: Int @doc(description: "Charity ID")
charity_name: String @doc(description: "Charity name")
global_amount: Float @doc(description: "Global donation amount")
amount: Float @doc(description: "Donation amount")
round_up: Boolean @doc(description: "Round up")
gift_aid_address: String @doc(description: "UK address")

Request:

mutation {
  addMwDonationToCart(
    input: {
      cart_id: "kPi7RAFpz6qNJMEYDmjwXenMWvj5NqSz"
      charity_id: 2
      amount: 20
      round_up: false
      uk_confirm: true
      gift_aid_address: "test address. API"
    }
  ) {
    cart {
      items {
        id
        product {
          sku
          stock_status
        }
        quantity
      }
      added_mw_donation {
            charity_id
            charity_name
            global_amount
            amount
            round_up
            gift_aid_address
        }
    }
  }
}

Response:

{
    "data": {
        "addMwDonationToCart": {
            "cart": {
                "items": [
                    {
                        "id": "122",
                        "product": {
                            "sku": "24-MB02",
                            "stock_status": "IN_STOCK"
                        },
                        "quantity": 4
                    },
                    {
                        "id": "123",
                        "product": {
                            "sku": "24-MB04",
                            "stock_status": "IN_STOCK"
                        },
                        "quantity": 1
                    },
                    {
                        "id": "126",
                        "product": {
                            "sku": "MW-Gift-mail",
                            "stock_status": "IN_STOCK"
                        },
                        "quantity": 4
                    }
                ],
                "added_mw_donation": {
                    "charity_id": 2,
                    "charity_name": "Don Org 1 - def_st_v - name",
                    "global_amount": 20,
                    "amount": 20,
                    "round_up": false,
                    "gift_aid_address": "test address. API"
                }
            }
        }
    }
}

REST/SOAP API

Create Charity

The method needs the admin authorization token.

Request Format

POST /V1/mw-donations/charity

Request JSON example

{
    "charity": {
        "store_ids": [
            0
        ],
        "is_active": 1,
        "store_locales": [
                {
                    "store_id": 0,
                    "store_name": "Org 1",
                    "store_description": "Org 1 description"
                },
                {
                    "store_id": 1,
                    "store_name": "Org 1 name - for store_id 1",
                    "store_description": "Org 1 description - for store_id 1"
                }
            ]
    }
}

Response JSON example

{
    "id": 11,
    "charity_id": 11,
    "name": "Org 1 name - for store_id 1",
    "description": "Org 1 description - for store_id 1",
    "image_url": "",
    "sort_order": 0,
    "is_active": 1,
    "date_added": "2021-09-13 12:28:17",
    "date_updated": "2021-09-13 12:28:16",
    "collected_amount": 0,
    "store_ids": [
        0
    ],
    "store_locales": [
        {
            "store_id": 0,
            "store_name": "Org 1",
            "store_description": "Org 1 description"
        },
        {
            "store_id": 1,
            "store_name": "Org 1 name - for store_id 1",
            "store_description": "Org 1 description - for store_id 1"
        }
    ]
}

Update Charity

The method needs the admin authorization token.

Request Format

PUT /V1/mw-donations/charity

Request JSON example

{
    "charity": {
        "charity_id": 11,
        "store_ids": [
            1,2
        ]
    }
}

Response JSON example

{
    "id": 11,
    "charity_id": 11,
    "name": "Org 1 name - for store_id 1",
    "description": "Org 1 description - for store_id 1",
    "image_url": "",
    "sort_order": 0,
    "is_active": 1,
    "date_added": "2021-09-13 12:28:17",
    "date_updated": "2021-09-13 12:37:42",
    "collected_amount": 0,
    "store_ids": [
        1,
        2
    ],
    "store_locales": [
        {
            "store_id": 0,
            "store_name": "Org 1",
            "store_description": "Org 1 description"
        },
        {
            "store_id": 1,
            "store_name": "Org 1 name - for store_id 1",
            "store_description": "Org 1 description - for store_id 1"
        }
    ]
}

Delete Charity by ID

The method needs the admin authorization token.

Request Format

DELETE /V1/mw-donations/charity/:charityId
where the "charityId" is the ID of the charity you want to remove.

Get Charities matching the specified criteria

The method needs the admin authorization token.

Request Format

GET /V1/mw-donations/charities

You should specify the searchCriteria in the Query Params like:

key value
searchCriteria[filter_groups][0][filters][0][field] is_active
searchCriteria[filter_groups][0][filters][0][value] 1

Response JSON example

{
    "items": [
        {
            "id": 2,
            "charity_id": 2,
            "name": "Don Org 1 - def_st_v - name",
            "description": "Don Org 1 - def_st_v - descr",
            "image_url": "",
            "sort_order": 0,
            "is_active": 1,
            "date_added": "2020-09-04 09:48:32",
            "date_updated": "2021-09-02 10:25:46",
            "collected_amount": 100,
            "store_ids": [
                1,
                2,
                15,
                16
            ],
            "store_locales": [
                {
                    "store_id": 0,
                    "store_name": "Don Org 1",
                    "store_description": "Don Org 1 - def - descr"
                },
                {
                    "store_id": 1,
                    "store_name": "Don Org 1 - def_st_v - name",
                    "store_description": "Don Org 1 - def_st_v - descr"
                }
            ]
        },
        {
            "id": 3,
            "charity_id": 3,
            "name": "test 2",
            "description": "Description for test 2",
            "image_url": "https://m24.kostevich.webra.mageworx.com/media/mageworx/donations/charity/1/1/11.jpeg",
            "sort_order": 0,
            "is_active": 1,
            "date_added": "2021-06-22 16:06:28",
            "date_updated": "2021-09-01 16:19:10",
            "collected_amount": 72.1,
            "store_ids": [
                0
            ],
            "store_locales": [
                {
                    "store_id": 0,
                    "store_name": "test 2",
                    "store_description": "Description for test 2"
                },
                {
                    "store_id": 2,
                    "store_name": "test 2 - stw2 - name",
                    "store_description": "test 2 - stw2 - descr"
                },
                {
                    "store_id": 15,
                    "store_name": "test 2 - test dis - name",
                    "store_description": "test 2 - test dis - descr"
                }
            ]
        }
    ],
    "search_criteria": {
        "filter_groups": [
            {
                "filters": [
                    {
                        "field": "is_active",
                        "value": "1",
                        "condition_type": "eq"
                    }
                ]
            }
        ]
    },
    "total_count": 2
}

Add Donation to Cart for admin orders

The method needs the admin authorization token.

Request Format

PUT /V1/mw-donations/carts/:cartId/donation
where the "cartId" is the ID of the cart.

Request JSON example

{
    "donationData": {
        "charity_id": 2,
        "amount": 0,
        "round_up": true,
        "uk_confirm": true,
        "gift_aid_address": "test address. API"
    }
}

If the operation was successful, the server returns true.

Add Donation to Cart for customer's orders

The method needs the admin authorization token.

Request Format

PUT /V1/mw-donations/carts/mine/donation

Request JSON example

{
    "donationData": {
        "charity_id": 2,
        "amount": 0,
        "round_up": true,
        "uk_confirm": true,
        "gift_aid_address": "test address. API"
    }
}

If the operation was successful, the server returns true.

Add Donation to Cart for guest's orders

The method needs the admin authorization token.

Request Format

PUT /V1/mw-donations/carts/guest-carts/:cartId/donation

You should add the masked ID of the cart (masked_id), which can be taken from the quote_id_mask table.

PUT /V1/mw-donations/carts/guest-carts/kPi7RAFpz6qNJMEYDmjwXenMWvj5NqSz/donation

Request JSON example

{
    "donationData": {
        "charity_id": 2,
        "amount": 0,
        "round_up": true,
        "uk_confirm": true,
        "gift_aid_address": "test address. API"
    }
}

If the operation was successful, the server returns true.

Got Questions?

Need help with the extensions? Feel free submit a ticket from https://www.mageworx.com/support/ 



Mageworx offers outstanding services developing custom-tailored solutions for Magento platform to attain your eCommerce objectives. Our professional impassioned team provides profound and custom oriented development of your project in a short timeframe.